MCP 서버 배포 전 체크리스트

MCP 서버를 배포하기 전에 10가지 체크를 수행하세요. 대부분의 서버는 최소 세 가지 항목에서 실패합니다. 이러한 실패는 에이전트(Agent)가 잘못된 도구(Tool)를 선택하거나, 인자(Argument)를 환각(Hallucination)하거나, 연결 시 서버를 조용히 누락시키기 전까지는 눈에 보이지 않습니다. 이것은 우리가 mcp-probe를 통해 강제하기 위해 구축한 체크리스트이며, 실제 환경에서 무엇이 문제를 일으키는지 정제한 결과입니다.

요약(TL;DR) — 배포 가능한 MCP 서버는 깔끔하게 연결되고, 도구의 이름을 모호하지 않게 명명하며, 모든 인자를 설명하고, 입력을 검증하며, 설치 메타데이터를 포함하여 배포됩니다. 가장 흔한 단일 실패 원인은 빈약한 도구 설명입니다. Anthropic의 5개 공식 레퍼런스 서버조차 설명 품질 면에서 60/100점에 그칩니다.

"Inspector에서 작동한다"는 것만으로는 부족한 이유

MCP Inspector는 _"내 서버가 연결되고 도구 목록을 표시하는가?"_라는 질문에 답해줍니다. 이는 필요조건일 뿐 충분조건은 아닙니다. 에이전트는 UI에서 당신이 서버를 경험하는 방식과는 다르게 경험합니다. 에이전트는 컨텍스트 윈도우(Context Window) 내의 텍스트로서 당신의 도구 설명과 스키마(Schema)를 경험하며, 이를 읽음으로써 도구를 선택합니다. 서버가 Inspector를 통과하더라도 모델이 도구를 구분할 수 없다면 기능적으로 배포가 불가능할 수 있습니다.

따라서 배포 전 질문은 "실행되는가?"가 아니라 **"배포 가능한가?"**여야 합니다. 즉, 문서도 없고 인간의 개입도 없는 실제 에이전트가 이를 올바르게 사용할 수 있는가 하는 점입니다.

10가지 체크리스트

연결 및 프로토콜 (Connection & protocol)

전송 오류 없이 연결되는가 — stdio 또는 HTTP 방식 모두에서 핸드셰이크(Handshake)가 완료되고 프로토콜 버전이 최신이어야 합니다.
도구(Tools), 리소스(Resources), 프롬프트(Prompts)를 나열하는가 — 노출하려는 모든 항목이 initialize 이후에 실제로 나타나야 합니다.
초기화 타임아웃이 없는가 — 방대한 도구 목록은 클라이언트의 프로브(Probe) 타임아웃을 초과하여 조용히 누락될 수 있습니다. initialize를 빠르게 유지하세요.

도구 가독성 (Tool legibility) (대부분의 서버가 실패하는 지점)

모든 도구는 실제적인 설명(description)을 가져야 함 — 단순히 이름을 재진술하는 것이 아닙니다. "create_issue: 이슈를 생성합니다"라는 설명은 모델에게 아무런 정보도 주지 못합니다. 설명은 모호함을 해소하는 역할을 수행해야 합니다.
이름 충돌 방지 (No naming collisions) — create_issue는 수십 개의 서버에 존재합니다. 만약 당신의 서버와 충돌한다면, 모델은 추측을 하게 됩니다. 네임스페이스 (Namespace)를 사용하거나 명확히 지정하세요.
인자(Arguments)는 단순히 타입만 지정하는 것이 아니라 설명되어야 함 — 모든 파라미터에는 설명이 필요하며, 필수 필드가 표시되어야 하고, 열거형 (Enum)은 나열되어야 합니다. 중첩된 인자 (Nested args)는 모델이 필수 필드를 놓치게 만듭니다.
변이 (Mutations)는 가독성이 좋아야 함 — 쓰기/삭제/결제 등을 수행하는 도구는 이를 명시해야 합니다. 모델이 런타임 (Runtime) 중에 부작용 (Side effect)을 발견하게 해서는 안 됩니다.

스키마 (Schema) 및 입력 (Inputs)

입력 검증 (Inputs validate) — 유효한 입력은 성공해야 하며, 유효하지 않은 입력은 스택 트레이스 (Stack trace)나 조용한 통과가 아닌 유용한 에러를 생성해야 합니다.
열거형 (Enum) 및 형태 제약 조건 (Shape constraints)이 명시적이어야 함 — 필드가 4가지 값 중 하나를 받는다면, 스키마에 이를 명시해야 합니다. 열거형을 의도한 곳에 단순히 "string"이라고 적는 것은 실수하기 쉬운 (Footgun) 방식입니다.

배포 (Distribution)

설치 메타데이터 제공 — 명확한 패키지 이름, 실행 가능한 예제, 최신 README, 그리고 공식 MCP 레지스트리 (Registry)가 당신을 발견할 수 있도록 하는 server.json을 포함하세요. 개발자들은 검색 시점이 아니라 설치 시점에 도구를 찾습니다.

3초 만에 점수 매기는 방법

이 목록을 수동으로 검토하거나, 다음 명령어를 실행할 수 있습니다:

npx @incultnitollc/mcp-probe score "node ./your-server.js"

mcp-probe는 당신의 서버에 연결하여 10가지 체크를 모두 실행하고, 설명 품질, 열거형/형태 정확성, 변이 가독성, "이름 재진술" 방지 조항, 배포 메타데이터라는 5가지 축을 기준으로 **0–100점 사이의 게시 가능성 점수 (Publishability score)**를 반환합니다. 통과 기준인 서버는 약 80점을 넘어야 합니다. 공식 레퍼런스 서버들은 60점대에 머물러 있습니다 (모든 서버에서 설명 관련 제한 사항이 걸리기 때문입니다). 일반적인 커뮤니티의 초안 서버는 40점대에 머뭅니다.

매 릴리스마다 실행되도록 CI에 연결하세요:

# .github/workflows/publishability.yml
- run: npx @incultnitollc/mcp-probe score "node ./dist/server.js" --fail-under 80

종료 코드 (Exit code)가 게시 여부를 결정합니다. 당신의 서버는 당신이 설정한 기준선 아래로 퇴보할 수 없습니다.

가장 먼저 수정해야 할 한 가지

다른 것은 아무것도 하지 않더라도, 이것만은 꼭 하세요: 맥락(Context)이 없는 모델이라도 당신의 도구와 이름이 유사한 다른 도구 사이에서 올바르게 선택할 수 있도록 도구 설명(Tool descriptions)을 다시 작성하십시오. 이 단 한 가지의 수정 작업이 이 목록에 있는 그 어떤 작업보다 더 많은 서버를 게시 가능한 기준선 위로 끌어올립니다. 그리고 이는 거의 모든 사람이 건너뛰는 작업이기도 합니다.

mcp-probe는 MCP 서버를 게시하기 전에 테스트하고 점수를 매길 수 있는 오픈 소스 CLI입니다. npx @incultnitollc/mcp-probe · github.com/incultnitollc/mcp-probe