LLM UI로서 Claude Code를 위한 MCP 서버를 구축하세요: 도구(tools)를 20개로 제한하고, 의도(intent) 중심으로 설계하며, JMESPath를 사용하여 페이로드(payloads)를 80-90% 절감하세요.

무엇이 바뀌었나 — 당신에게 필요한 MCP 서버 설계 규칙

Bump.sh의 새로운 가이드는 효율적인 MCP 서버를 구축하기 위한 네 가지 구체적인 규칙을 제시합니다. 핵심 통찰은 다음과 같습니다: MCP 서버를 단순한 API 프록시(proxy)가 아닌, LLM을 위한 사용자 인터페이스(UI)로 취급하십시오. 이러한 사고방식의 전환은 도구를 설계하고, 설명을 작성하며, 응답을 처리하는 모든 방식을 변화시킵니다.

만약 여러분이 REST 엔드포인트(endpoints)를 일대일로 래핑(wrapping)하고 그것으로 끝냈다면, 여러분은 토큰(tokens)과 Claude Code의 인내심을 낭비하고 있는 것입니다.

규칙 1: 도구(Tools)를 15~20개로 제한하라

노출하는 모든 도구는 토큰을 소모합니다. 서버의 도구 목록은 매 요청마다 Claude Code로 전송됩니다. 도구가 많아질수록 = 컨텍스트 윈도우(context window)가 커지고 = 응답이 느려지며 + 비용이 높아집니다.

규칙: 각 MCP 서버를 대략 15~20개의 도구로 제한하십시오. 더 많은 도구가 필요하다면 도메인별로 여러 서버로 분리하십시오.

Claude Code 사용자에게 이는 다음을 의미합니다:

• 관련 작업을 하나의 도구로 그룹화하십시오 (예: create_project, create_task, create_document 대신 create_resource 사용)
• 거의 사용되지 않는 도구는 제거하십시오
• 10개의 별도 쿼리(query) 도구 대신 매개변수(parameters)를 가진 단일 "query" 도구를 고려하십시오

규칙 2: API 엔드포인트가 아닌 사용자의 의도(Intentions)를 중심으로 도구를 설계하라

여러분의 API에는 POST /users/{id}/permissions와 같은 엔드포인트가 있습니다. 여러분의 MCP 서버에는 grant_user_access라는 이름의 도구가 있어야 합니다.

차이점: Claude Code는 여러분의 RESTful 리소스 계층 구조(resource hierarchy)에 관심이 없습니다. 그것은 사용자가 무엇을 달성하고 싶어 하는지에 관심이 있습니다.

특히 Claude Code의 경우:

• 모델이 이해할 수 있는 동작 동사(action verbs)로 도구 이름을 지정하세요: search_code, deploy_service, run_test 등
• 단계들이 항상 함께 수행된다면, 여러 단계의 작업을 하나의 도구로 그룹화하세요
• CRUD (Create, Read, Update, Delete) 작업을 직접 노출하는 것을 피하고, 의도 기반(intent-based) 도구로 래핑(wrap)하세요

규칙 3: 모델을 유도하는 도구 설명(Tool Descriptions) 작성하기

도구 설명은 Claude Code가 귀하의 서버를 사용하는 방식을 제어할 수 있는 가장 주요한 수단입니다. "사용자를 생성합니다"와 같은 일반적인 설명은 모델의 해석에 너무 많은 것을 맡기게 됩니다.

더 나은 예시: "새 사용자 계정을 생성합니다. 'name'과 'email'이 필요합니다. 사용자 ID를 반환합니다. 사용자가 가입(sign up) 또는 등록(register)을 요청할 때 이 도구를 사용하세요. 관리자 사용자 생성에는 이 도구를 사용하지 마십시오. 대신 'create_admin_user'를 사용하세요."

에러 메시지도 중요합니다. "400 Bad Request" 대신 다음과 같이 반환하세요: "'example.com' 이메일 도메인은 허용되지 않습니다. 회사 이메일 주소를 사용하세요." 이는 Claude Code가 동일한 실수를 반복하지 않고 스스로 동작을 수정하는 데 도움을 줍니다.

규칙 4: 응답 페이로드(Response Payloads)를 공격적으로 필터링하기

이것이 가장 큰 토큰 절약 방법입니다. 대부분의 API 응답에는 Claude Code가 필요로 하지 않는 필드들이 포함되어 있습니다. 이를 그대로 보내는 것은 매 호출마다 토큰을 낭비하는 일입니다.

해결책: JMESPath(또는 그에 상응하는 도구)를 사용하여 모델에 반환하기 전에 응답을 필터링하세요.

예시: 40개의 필드가 포함된 전체 사용자 객체를 반환하는 대신, {id, name, email, role}로 필터링하여 반환하세요.

가이드에 따르면 이 관행만으로도 80~90%의 페이로드 감소가 보고되었습니다. Claude Code 사용자에게 이는 매 도구 호출 시 더 빠른 응답과 더 낮은 비용을 의미합니다.

지금 바로 시도해보세요

1. MCP 서버 감사 — 서버당 도구 개수를 세어보세요. 만약 20개가 넘는 서버가 있다면 분리하세요.
2. 도구 설명 재작성 — "...할 때 이 도구를 사용하세요" 및 "...할 때는 이 도구를 사용하지 마세요"와 같은 가이드를 추가하세요.
3. JMESPath 설치 — 서버의 도구 핸들러(tool handlers)에 응답 필터링 기능을 추가하세요.
4. 차이점 테스트 — 전형적인 워크플로우를 적용 전후로 실행하여 토큰 수를 비교해보세요.

이것이 Claude Code에 중요한 이유

Claude Code의 에이전틱 루프 (agentic loop)는 도구 (tools)를 빈번하게 호출합니다. 목록에 포함된 모든 불필요한 도구, 모든 장황한 설명, 모든 비대해진 응답 페이로드 (response payload) — 이 모든 것들이 복리로 쌓입니다. 이 네 가지 규칙은 모든 상호작용의 토큰 오버헤드 (token overhead)를 직접적으로 줄여주어, 귀하의 Claude Code 세션을 더 빠르고 저렴하게 만들어 줍니다.

결론: 귀하의 MCP 서버는 LLM UI입니다. UI처럼 설계하세요.

출처: dev.to

[Updated 06 Jul via devto_mcp]

Mattrx의 프로덕션 (production) MCP 서버는 타입화된 스키마 (typed schemas)와 타입화된 에러 (typed errors) 덕분에 [dev.to에 따르면], 읽기 p95 지연 시간 (latency) 120ms, 도구 호출 에러율 단 0.8%로 하루 약 85,000건의 도구 호출을 처리합니다. 또한 이 서버는 모든 결과에 대해 캡 (cap) 및 페이지네이션 (pagination)을 적용하며 (페이지 ≤ 200, 불투명 커서 (opaque cursor)), CancellationToken을 준수하고, 호출당 OpenTelemetry 트레이싱 (tracing)이 포함된 /healthz 및 /readyz 엔드포인트를 노출합니다. 이는 응답 필터링 (response filtering)만으로는 모든 프로덕션 요구 사항을 충족할 수 없다는 본 가이드의 요점을 강조합니다.

원문 게시: gentic.news