MCP 서버 통합 문제: 프로토콜, transport, 권한, schema를 계층별로 진단하기

장애를 빠르게 분류하기

Inspector를 실행하기 전에 증상 하나와 마지막으로 확인된 지점을 기록하세요.

• process가 전혀 시작되지 않는다.
• process는 실행되지만 client가 JSON-RPC를 받지 못한다.
• transport는 응답하지만 version이나 capabilities가 일치하지 않는다.
• server가 401 또는 403을 반환한다.
• tools/list는 동작하지만 필요한 tool이 없다.
• tool은 보이지만 tools/call이 arguments를 거부한다.
• call은 완료되지만 결과를 검증할 수 없다.

기록에 API Key, bearer token, cookie, 전체 prompt, private file 내용을 남기지 마세요. 상관관계 확인에는 시간, server 이름, method, JSON-RPC id, error code, 민감 정보를 제거한 message면 충분합니다.

1. Protocol era 확정하기

Client, server, 사용하는 SDK가 어떤 version을 지원하는지 확인하세요. Connected 문구는 transport와 discovery 일부만 확인할 뿐 2026-07-28 합의를 증명하지 않습니다.

현대적인 구현에서는 다음 세 가지를 확인합니다.

1. SDK 또는 release notes가 2026-07-28 지원을 명시한다.
2. trace에 server/discover 또는 SDK가 정의한 다른 discovery path가 있다.
3. Request에 version, client 정보, capabilities를 담은 올바른 _meta가 있다.

다른 SDK의 _meta 형태를 수동으로 복사하지 마세요. 정확한 wire format은 compatible client나 official SDK가 생성해야 합니다. Server가 initialize를 기다리는데 client가 self-contained 2026-07-28 request를 보낸다면 tool schema 오류가 아니라 protocol era 불일치입니다.

Legacy initialize: 2025-11-25 이하에서만 사용

다음은 최소 legacy request입니다. “안전을 위해” modern 2026-07-28 flow에 추가하지 마세요.

{
  "jsonrpc": "2.0",
  "id": 1,
  "method": "initialize",
  "params": {
    "protocolVersion": "2025-11-25",
    "capabilities": {},
    "clientInfo": {
      "name": "mcp-diagnostic-client",
      "version": "1.0.0"
    }
  }
}

성공한 response 뒤에 legacy client는 notifications/initialized를 보냅니다. 이 exchange가 중단된다면 먼저 versions와 capabilities 목록을 비교하세요. 아직 tools/list로 넘어갈 단계가 아닙니다.

2. Transport와 MCP semantics를 분리해 검사하기

MCP는 methods와 data를 정의하고, transport는 시작, framing, 전달, request cancellation을 담당합니다. stdio에서 HTTP로 바꿔도 잘못된 inputSchema는 고쳐지지 않습니다.

stdio

stdio에서는 client가 server를 child process로 시작합니다. Message는 stdin과 stdout을 통해 줄바꿈으로 구분된 UTF-8 JSON-RPC document로 전달됩니다.

다음을 확인하세요.

1. command가 존재하고 같은 user로 실행된다.
2. Arguments가 별도 항목으로 전달되며 shell aliases에 의존하지 않는다.
3. Working directory에 필요한 files가 있거나 paths가 absolute다.
4. 필요한 variables가 실제로 child process에 제공된다.
5. stdout에 banner, debug lines, stack trace가 없고 logs는 stderr로 간다.

실수로 넣은 console.log() 한 줄이 stdout에 출력되면 client가 JSON-RPC response를 보기 전에 framing이 깨질 수 있습니다.

Streamable HTTP

Streamable HTTP에서는 client가 하나의 MCP endpoint로 POST message를 보냅니다. Response는 일반 JSON 또는 request-scoped SSE일 수 있습니다. 정확한 URL, HTTP method, Content-Type, TLS, redirect, proxy, authentication 방식을 확인하세요.

Transport test는 loopback 또는 isolated test environment에서 실행하세요. 허가 없이 public production endpoint를 scan하지 마세요. POST가 login page HTML, 다른 host로 가는 301/302, reverse proxy response를 반환한다면 아직 MCP에 도달하지 않은 것입니다.

3. 같은 실행 환경에서 시작 재현하기

stdio에서는 MCP client와 같은 directory, 같은 user로 server command를 직접 실행하세요. IDE에서 실행하는 것으로 대신하면 안 됩니다. PATH, cwd, runtime, permissions가 다를 수 있습니다.

다음을 확인하세요.

node --version
pwd
node ./dist/server.js

pwd 자체는 secret을 노출하지 않지만 path에 user 이름이나 private project 이름이 있으면 공개하지 마세요. Server command는 stdin에서 JSON-RPC를 기다리거나 stderr에 분명한 error를 남기고 종료해야 합니다. Message 없이 즉시 exit하면 보통 잘못된 entrypoint, missing dependency, 또는 log 없이 처리된 startup error를 뜻합니다.

2026년 8월 23일 기준 official Inspector CLI documentation은 Node.js 22.19.0 이상을 요구합니다. Version이 낮다면 중단하고 진단을 계속하기 전에 runtime을 바꾸세요.

4. Permissions와 authentication 분리하기

Response code에 따라 다음 확인 대상을 정합니다.

• 401 Unauthorized: credential이 없거나 만료되었거나 거부되었다.
• 403 Forbidden: identity는 인식되었지만 필요한 permission 또는 scope가 없다.
• 404: 권한 부족보다 endpoint 또는 route가 잘못된 경우가 많다.
• timeout: server, proxy, tool이 제시간에 완료되지 않았다. auth error의 증거는 아니다.

Smoke test를 위해 permissions를 끄지 마세요. 최소 scope를 가진 별도 test identity를 만들고 external effect가 없는 read-only tool을 선택하세요. Client는 사람이 call을 거부할 수 있게 해야 합니다. Tool annotations는 untrusted data이며 policy를 대신하지 않습니다.

Logs에는 auth decision(allowed/denied), scope 이름, correlation ID를 남기세요. Credential 자체, Authorization header, cookie는 삭제하거나 mask해야 합니다.

5. Capability와 inputSchema 검증하기

Server는 tools/list를 제공하기 전에 tools capability를 declare해야 합니다. 각 tool에는 unique name과 inputSchema의 valid JSON Schema object가 필요합니다. tools/call의 arguments는 이 schema와 일치해야 합니다.

최소 read-only tool declaration:

{
  "name": "echo",
  "description": "전달받은 텍스트를 변경 없이 반환합니다",
  "inputSchema": {
    "type": "object",
    "properties": {
      "text": {
        "type": "string"
      }
    },
    "required": ["text"],
    "additionalProperties": false
  }
}

흔한 오류는 단순합니다. Root type: object가 없거나, required field가 properties에 없거나, client가 string 대신 number를 보내거나, argument 이름의 대소문자가 다르거나, server가 같은 이름의 tools 두 개를 advertise하는 경우입니다.

Version과 transport가 맞으면 다음 JSON-RPC payload로 method를 검사하세요.

{
  "jsonrpc": "2.0",
  "id": 2,
  "method": "tools/list",
  "params": {}
}

그다음 tool 하나만 호출합니다.

{
  "jsonrpc": "2.0",
  "id": 3,
  "method": "tools/call",
  "params": {
    "name": "echo",
    "arguments": {
      "text": "MCP_OK_2026"
    }
  }
}

이 조각들은 method payload를 보여 줄 뿐 전체 connection bootstrap은 아닙니다. 2026-07-28 flow에서는 compatible client가 필요한 request metadata를 _meta에 추가합니다. Legacy flow에서는 initialize가 먼저 실행됩니다. 허가 없이 이 JSON을 production endpoint에 수동으로 보내지 마세요.

6. MCP Inspector CLI로 안전한 test 실행하기

먼저 신뢰할 수 있는 lockfile에서 Inspector를 pinned project dependency로 설치하세요. 아래 --no-install은 진단 중 임의의 current version을 download하지 않습니다.

Local stdio server의 tools 목록:

npx --no-install @modelcontextprotocol/inspector --cli node ./dist/server.js --method tools/list

echo 한 번 호출:

npx --no-install @modelcontextprotocol/inspector --cli node ./dist/server.js \
  --method tools/call \
  --tool-name echo \
  --tool-arg text=MCP_OK_2026

Loopback의 test Streamable HTTP endpoint:

npx --no-install @modelcontextprotocol/inspector --cli \
  http://127.0.0.1:3000/mcp \
  --transport http \
  --method tools/list

Token을 shell history, URL, article에 넣지 마세요. Endpoint에 auth가 필요하면 local environment에서 Inspector의 정식 방식으로 credential을 설정하세요. 그렇지 않으면 test를 중단하고 server owner에게 test identity를 요청하세요. 위 commands에는 의도적으로 real Key가 없습니다.

증상 → 확인 → 최소 수정

성공 판정 기준

다음 다섯 조건이 모두 충족되어야 integration이 최소 acceptance를 통과합니다.

1. Logs 또는 telemetry에 예상한 negotiated protocol version이 보인다.
2. Transport가 framing을 훼손하지 않는다. stdio에는 추가 stdout이 없고 HTTP는 MCP endpoint에서 응답한다.
3. tools/list가 valid inputSchema를 가진 예상 tool 하나를 반환한다.
4. tools/call이 실제로 text=MCP_OK_2026과 함께 호출되고 MCP_OK_2026을 변경 없이 반환한다.
5. Test가 permissions를 끄지 않았고 credentials를 노출하지 않았으며 external side effect를 만들지 않았다.

Model response에서 MCP_OK_2026만 보는 것으로는 부족합니다. 일치하는 JSON-RPC id가 기록된 tool call, 또는 Inspector 기록과 민감 정보를 제거한 server log가 필요합니다.

Stop conditions

다음 상황에서는 진단을 중단하고 다음 계층으로 넘어가지 마세요.

• 어느 한쪽이 지원하는 protocol era를 알 수 없다.
• Inspector가 검토하지 않은 unpinned package version을 설치하려 한다.
• test에 production credential, auth 비활성화 또는 scope 확대가 필요하다.
• 사용할 수 있는 유일한 tool이 database 기록, message 전송, file 변경 또는 command 실행을 한다.
• HTTP endpoint가 third party 소유이고 test 허가가 확인되지 않았다.
• logs에 Key, token, cookie, personal data 또는 private resource 내용이 나타났다.
• tools/list가 불안정하거나 반복 실행에서 서로 다른 schema를 반환한다.
• valid JSON-RPC response가 나오기 전에 server가 crash한다.

이 경우 민감 정보를 제거한 symptom, client/server/SDK versions, transport, correlation ID, 최소 error 조각을 보관하세요. 불필요한 권한이나 secret을 배포하지 않고 올바른 계층의 owner에게 문제를 전달하기에 충분합니다.

출처

• MCP 2026-07-28: versioning
• MCP 2026-07-28: transports
• MCP 2026-07-28: tools
• MCP Inspector

Specification version, transport 세부 사항, 최소 Node.js version은 2026년 8월 23일에 확인했습니다. Client, server, SDK, Inspector를 update한 뒤 진단을 반복할 때는 최신 official documentation을 다시 확인하세요.