데이터 구조를 바꿨는데, AI 는 옛 MCP 도구로 예전 칸에 쓸 수 있었습니다

내부 프로젝트 관리 도구의 데이터 구조를 바꿨습니다. 백엔드와 화면을 새 구조로 옮겼고, 테스트도 전부 통과해 배포까지 마쳤습니다. 그런데 AI 가 쓰는 도구 쪽을 열어 보니 옛 구조가 그대로 남아 있었습니다.

AI 는 옛 도구로 예전 칸에 값을 계속 쓸 수 있었습니다. 화면은 새 구조만 읽습니다. 그래서 사람 눈에는 AI 가 넣은 내용이 그냥 사라진 것처럼 보였을 겁니다. 이 글은 그 점검에서 나온 빈틈 7가지와, 다음 구조 변경 때 쓰려고 만든 점검 목록을 정리한 기록입니다.

프로젝트당 종료 정보 하나에서, 계약 여러 개로

하루 전에 '프로젝트 종료 관리' 기능을 만들었습니다. 이 구조는 프로젝트 하나에 종료 정보를 하나만 둘 수 있었습니다. 실제로는 한 프로젝트에 계약이 여러 개 붙는 경우가 많습니다. 1차 개발, 추가 개발, 유지보수가 각각 따로 계약되고, 대금도 착수·중도·잔금으로 나뉩니다.

그래서 '프로젝트 아래 계약 여러 개'로 구조를 바꿨습니다. 계약마다 개발 일정, 검수 기한, 하자보증, 월 유지보수, 대금 회차, 산출물이 붙습니다. 계약 단계(수행 중 → 검수 대기 → 하자보증 → 유지보수 → 종료)와 이번 달 청구 대상은 서버가 오늘 날짜를 기준으로 계산합니다. 프로젝트 쪽에 있던 종료 값 6개는 계약 하나로 옮기고 지웠습니다.

여기까지는 흔한 구조 변경입니다. 달라진 건 그다음 결정이었습니다. 계약은 웹 화면에서 직접 넣기보다 **AI 를 통해 넣게 하자**고 정했습니다. 그렇다면 AI 가 쓰는 MCP 도구(AI 가 외부 시스템을 조회·수정할 때 부르는 함수 묶음)도 새 구조를 알아야 합니다. 그래서 구조를 바꾼 당일에 AI 쪽을 점검했습니다.

AI 쪽을 열어 보니 빈틈이 7가지였습니다

이 빈틈은 사용자 문의로 알게 된 게 아닙니다. 구조를 바꾼 날 개발자가 점검하다 찾았고, 같은 날 고쳤습니다. 그 사이 AI 가 실제로 예전 칸에 쓴 일이 있었는지는 기록에 없습니다.

옛 도구는 안내하지 않고 지웠습니다

옛 도구를 처리하는 방법은 둘이었습니다. 남겨 두고 '쓰지 말라'고 안내하거나, 아예 지우는 것입니다. 지우는 쪽을 골랐습니다.

사람은 메뉴가 사라지면 그 기능을 못 씁니다. AI 는 다릅니다. 도구 목록에 남아 있으면 상황에 맞는다고 판단하는 순간 그 도구를 부릅니다. 그리고 그 결과가 화면 어디에도 안 나타나면 문제는 '입력이 사라졌다'는 사람 쪽 증상으로만 드러납니다. 원인을 AI 도구에서 찾기까지 한참 걸렸을 겁니다.

안내문을 아무리 잘 써도 AI 가 그대로 따른다는 보장은 없습니다. 못 하게 막는 쪽이 더 확실하고, 설명은 그다음입니다. 옛 도구 2개를 지우고, 빠져 있던 '계약 대체' 도구와 '전체 계약 목록' 도구를 더했습니다. 종료 보고서 스킬의 8단계도 새 계약 도구를 가리키게 바꿨습니다.

신·구 경로가 같이 살아 있는 중간 상태를 어떻게 정리하는지는 따로 적어 둔 글이 있습니다.

AI 가 구조를 알게 하는 자리는 세 군데입니다

고치면서 보니 AI 에게 새 구조를 알려주는 자리가 하나가 아니었습니다. 자리마다 담을 내용이 달랐습니다.

**서버 안내문** — 구조와 원칙. MCP 서버가 접속할 때 내려주는 글입니다. '계약서 한 장 = 계약 하나', '프로젝트가 끝났는지는 계약으로 본다', 계약서 문구와 칸의 대응(검수 N일·하자보증·착수·중도·잔금·월 유지보수)을 적었습니다

**도구 설명** — 상태값과 필드를 고치는 순서. 상태값 5종을 적고, 목록 필드를 고치는 순서를 적었습니다

**스킬** — 작업 단계. 종료 보고서를 쓸 때 몇 번째 단계에서 어느 도구를 부르는지를 적었습니다

안내문에는 판단 원칙도 넣었습니다. 계약서 안에서 서로 안 맞는 내용이 있으면 AI 가 하나를 고르지 말고 고객 질문으로 남깁니다. 검수 독촉 같은 해야 할 일은 계약 칸에 적지 않고 할 일로 따로 세웁니다. 계약을 지우는 도구는 없다는 것도 적었습니다.

가장 조심한 건 대금 회차입니다. 회차는 목록 하나로 저장되고, 고칠 때는 목록이 통째로 교체됩니다. AI 가 잔금 회차 하나만 고치려고 그 회차만 보내면 착수금·중도금 회차가 지워집니다. 그래서 도구 설명에 '먼저 읽고 → 그 회차만 고치고 → 전체를 다시 보낸다'는 순서를 적었습니다.

도구 설명에 무엇을 남기고 무엇을 빼는지는 다른 글에서 기준을 정리했습니다.

AI 를 편하게 하려고 권한을 넓히지 않았습니다

7번째 빈틈인 프로젝트 현황 도구는 쉬운 길이 있었습니다. 프로젝트 상세 API 에 계약 요약을 얹으면 됩니다. 그런데 이 API 는 고객 계정도 부르는 경로입니다. 거기에 금액이 들어간 계약 정보를 얹으면 고객 화면에서도 그 값을 받게 됩니다.

그래서 MCP 서버 쪽에서 소유자 전용 계약 API 를 따로 불러 현황에 요약을 붙였습니다. 그 호출이 실패하면 계약 칸만 비우고 나머지 현황은 그대로 돌려줍니다. 계약을 못 읽었다고 현황 전체가 실패하지 않게 한 것입니다.

고친 뒤에도 남은 것

MCP 테스트는 170개가 통과했습니다. 옛 도구 테스트 4개가 빠지고 새 테스트 4개가 들어간 숫자입니다. 다만 고쳤다고 바로 끝나지는 않았습니다.

이미 연결돼 있던 MCP 클라이언트와 개인 비서 에이전트는 다시 연결하기 전까지 옛 도구 목록을 들고 있습니다. 서버에서 도구를 지운 시점과 AI 가 실제로 그 도구를 못 보게 되는 시점 사이에 틈이 있습니다.

도구 사용 기록도 같이 봤습니다. 구조를 바꾼 날 기준으로 전체 호출은 6,969회, 오류는 40회였습니다. 등록된 도구 80개 중 19개는 한 번도 불린 적이 없었습니다. 그중 9개는 이번에 새로 만든 계약 도구라 아직 쓸 기회가 없었던 것입니다. 안 쓰는 도구와 섞어 세면 정리 대상을 잘못 고르게 됩니다. 나머지를 정리할지는 아직 정하지 않았습니다.

다음 구조 변경 때 쓸 점검 목록

데이터 구조를 바꿀 때 영향받는 곳을 세면 보통 화면·API·배치까지 셉니다. AI 가 그 데이터를 읽고 쓴다면 아래를 같이 봅니다.

옛 구조에 쓰는 도구가 도구 목록에 남아 있는가 — 남아 있으면 안내하지 말고 지운다

그 도구를 부르는 스킬·작업 단계가 옛 도구를 가리키고 있지 않은가

서버 안내문에 새 구조와 판단 원칙이 들어갔는가

도구 설명에 상태값 목록과, 통째로 교체되는 필드의 '읽고 → 고치고 → 전체를 보낸다' 순서가 적혀 있는가

화면의 기능 목록과 도구 목록을 나란히 놓았을 때 화면에만 있는 기능이 없는가

AI 용 요약을 붙이려고 고객도 부르는 경로에 민감한 값을 얹고 있지 않은가

이번 점검은 '계약은 AI 로 넣는다'는 결정이 먼저 있어서 할 만했습니다. AI 를 거치지 않는 기능이라면 이 점검이 비용만 들 수 있습니다. 반대로 AI 가 쓰는 데이터라면, 화면만 새 구조로 옮긴 상태가 가장 알아채기 어렵습니다. 아무 오류도 나지 않고, AI 가 넣은 값이 조용히 안 보일 뿐이기 때문입니다.