MCP 연결 오류 설명: /sse에서의 404, 406 Not Acceptable, 세션 400번대, 402

MCP Streamable HTTP는 하나의 URL입니다. 클라이언트는 이 주소로 JSON-RPC를 POST하고 같은 URL에서 GET 스트림을 열 수 있으며, 그 외에는 주소의 일부가 없습니다. 저희 서버 로그에서 발견하는 대부분의 연결 실패는 클라이언트가 제공받은 주소가 아닌 다른 주소와 통신하거나 잘못된 헤더를 전송했기 때문입니다. 각 상태 코드가 무엇을 의미하며 해결 방법과 공식 TypeScript 및 Python SDK가 보내는 정확한 메시지를 설명합니다.

/sse에서의 404 Not Found, 또는 /mcp가 추가된 경우

이전 HTTP+SSE 전송 방식(프로토콜 개정일 2024-11-05)은 SSE URL로 GET을 열고 endpoint 이벤트를 읽어 POST를 위한 두 번째 URL을 지정했습니다. Streamable HTTP(2025-03-26 이후)는 이 둘을 단일 URL로 대체했습니다. 여전히 SSE만 지원하는 클라이언트나 추측하는 브릿지는 /sse를 추가하여 어떤 Streamable HTTP 서버에서도 404 오류를 받게 됩니다. 일부 클라이언트는 이미 서버 경로로 끝나는 URL에 /mcp를 추가하기도 합니다.

해결 방법: 게시된 대로 정확한 URL을 사용해야 합니다. stdio만 지원하는 클라이언트의 경우, npx mcp-remote https://tanod.dev/mcp --transport http-only와 같은 브릿지를 실행하여 SSE로 폴백(fallback)하지 않도록 해야 합니다. Tanod의 모든 서버는 Streamable HTTP입니다: https://tanod.dev/mcp이며, https://tanod.dev/mcp/docs; /mcp/docs/sse, /mcp/docs/mcp, 그리고 /api/mcp와 같은 포커스된 서버들은 모두 404입니다.

406 Not Acceptable: 클라이언트는 application/json과 text/event-stream을 모두 수락해야 함

POST는 Accept: application/json, text/event-stream을 포함해야 합니다. 왜냐하면 서버가 요청에 대해 JSON 본문 또는 SSE 스트림 중 하나로 응답할 수 있기 때문입니다. 두 SDK 모두 다른 것을 받으면 이 메시지를 반환하며 거부합니다. GET (선택적인 서버-클라이언트 스트림)은 text/event-stream을 수락해야 합니다. Curl과 대부분의 HTTP 라이브러리는 Accept: */*를 전송하는데, 일부 서버는 이를 받아들이지만 다른 서버는 그렇지 않습니다. 헤더를 명시적으로 설정해야 합니다.

415 Unsupported Media Type: Content-Type은 application/json이어야 함

요청 본문은 JSON-RPC여야 하며 Content-Type: application/json으로 전송되어야 합니다. 폼 인코딩(Form encoding), 누락된 헤더, 또는 간단한 스크립트에서 발생하는 text/plain이 이 오류를 발생시킵니다.

400 Bad Request: 서버 초기화되지 않음, 또는 세션 ID 누락

상태 유지형(stateful) 서버는 먼저 initialize 요청을 기대합니다. 해당 응답은 Mcp-Session-Id 헤더를 포함하며, 클라이언트는 이후 모든 요청에 이 헤더를 전송해야 합니다. initialize 전에 tools/list를 호출하거나 헤더를 누락하면 위 두 가지 400 오류 중 하나가 발생합니다. 서버가 재시작되면 이전 세션은 사라지고 서버는 404 Session not found로 응답합니다. 이 경우 클라이언트는 새로운 initialize를 통해 새 세션을 시작해야 하며, 잘 작동하는 클라이언트들은 이를 스스로 처리합니다.

Tanod의 서버는 상태 비저장형(stateless)입니다: 세션 헤더가 필요하지 않으며, tools/list가 첫 번째 요청으로 작동하므로 셸 확인은 한 개의 명령어로 충분합니다:

curl -s -X POST https://tanod.dev/mcp/docs \
  -H "Content-Type: application/json" \
  -H "Accept: application/json, text/event-stream" \
...

GET 요청에서 405 Method Not Allowed

이 사양은 서버가 독립적인 GET 스트림을 거부할 수 있도록 허용합니다. 이를 열고 405를 받는 클라이언트는 POST로 계속 진행해야 합니다. 이는 연결의 실패가 아니며, 도구 호출(tool calls)도 여전히 작동합니다.

브라우저가 웹 페이지 또는 리디렉션을 표시하는 경우

Accept: text/html을 가진 GET 요청은 MCP 클라이언트가 아니라 사람입니다. Tanod를 포함한 많은 서버들이 해당 요청을 인간이 볼 수 있는 페이지(여기서는 서버 개요)로 보냅니다. POST를 사용하는 MCP 클라이언트는 영향을 받지 않습니다.

402 Payment Required, 또는 isError와 PaymentRequired 객체를 가진 도구 결과

유료 호출(pay-per-call) 서버의 경우, 가격 견적은 MCP 내부를 통해 전달됩니다. 이때 도구 결과는 isError: true를 가지며, 그 structuredContent는 x402 PaymentRequired 객체(스키마, 네트워크, 금액, 지불 주소)입니다. x402를 지원하는 클라이언트는 결제를 수행하고, 페이로드(payload)를 params._meta["x402/payment"]에 담아 호출을 반복합니다. 이때 영수증은 _meta["x402/payment-response"]에서 반환됩니다. x402 지원이 없는 클라이언트는 가격 정보가 포함된 도구 오류를 보게 되는데, 이것이 의도된 동작입니다. Tanod의 경우, 어떠한 견적도 발행되기 전에 무료 일일 할당량이 소진되며, 일반 HTTP 경로는 JSON 형태로 동일한 객체를 가진 클래식 402 응답을 반환합니다.

호출이 멈추고(hangs), 클라이언트가 시간 초과를 보고함

대용량 PDF의 OCR이나 전체 계약서 스캔 같은 긴 도구는 수십 초가 걸릴 수 있으며, 클라이언트는 자체적인 시간 초과 설정을 가지고 있습니다. 예를 들어 Claude Code에는 밀리초 단위의 MCP_TIMEOUT 설정이 있습니다. Tanod는 모든 호출을 90초 이내에 처리하고 멈추기보다는 구조화된 오류를 반환하므로, 그보다 짧은 클라이언트 시간 초과가 문제가 될 수 있습니다. 서버가 SSE(Server-Sent Events) 진행 알림을 전송하는 경우, 스트림은 프록시를 통과하면서 연결을 활성 상태로 유지합니다.

체크리스트

• 게시된 URL을 사용하세요. 추가하거나 추측한 내용은 없습니다.
• Content-Type: application/json 및 Accept: application/json, text/event-stream으로 POST 요청을 보냅니다.
• 상태 유지 서버(Stateful servers): 먼저 initialize를 호출하고, 이어서 반환되는 Mcp-Session-Id를 사용합니다. 404 오류가 발생하면 처음부터 다시 시작하세요.
• 402 및 PaymentRequired 도구 오류를 가격 견적으로 간주하세요.
• 서버의 문제로 단정하기 전에 클라이언트 시간 초과 여부를 먼저 확인하세요.

Tanod에서 호스팅하는 MCP 서버(https://tanod.dev/mcp-servers/)가 작동 예시이며, 이 체크리스트는 모든 스트림 가능한 HTTP 서버에 적용됩니다. 최신 버전 가이드는 https://tanod.dev/learn/mcp-server-connection-errors.html를 참고하세요.