MCP 서버 구축에서 얻은 교훈

MCP 서버를 잘 만들려면 모델이 스스로 계획한다고 기대하면 안 된다. 모델은 대화와 도구 목록을 훑고 가장 그럴듯한 도구를 고를 뿐이어서, 서버가 매 단계에서 다음 호출을 명확히 제시해야 한다.

실전에서는 100개가 넘는 도구를 그대로 노출하지 않고, office_help부터 office_read, office_inspect, office_patch, office_table, office_template, office_audit, word_insert_at_anchor까지 8개 핵심 verb로 흐름을 수렴시킨다. 도구명은 word_*, excel_*, office_*처럼 접두사를 맞춰 체인을 자연스럽게 이어지게 하고, 표면은 작게 유지하되 접근 가능한 범위는 넓히는 activation set을 쓴다.

설계 원칙도 분명하다.

• discovery tool은 설명문이 아니라 추천 경로를 담은 구조화된 데이터로 반환한다.
• office_help(goal=...)는 인자 없이 호출하면 카탈로그를, 모를 때는 지원 가능한 집합을 돌려준다.
• 응답에는 next_tools와 usage 같은 breadcrumbs를 넣어 다음 호출을 유도한다.
• 주소는 line number 대신 anchors, ID, 경로처럼 호출 사이에 살아남는 값으로 유지한다.
• 하나의 도구에 dry_run, best_effort, safe, strict 같은 mode enum을 묶어 discovery 비용을 줄인다.
• mutating 도구는 status, matched_targets, unmatched_targets, next_tools 같은 diagnostics를 표준화하고, 복구용 read-only 도구와 audit 도구를 항상 남겨 둔다.
• 반복 호출은 캐시하고, 실패해도 재시도가 안전하도록 idempotence를 고려한다.

결국 서버가 대부분의 일을 하고 모델은 breadcrumb만 따라가게 만들면, schema와 설명문에서 추측 비용을 크게 줄일 수 있다.