MCP 오류 코드: -32601, -32602, -32001의 의미

MCP 오류 코드는 JSON-RPC 2.0 오류 코드입니다. 표준 코드는 -32700(파싱 오류), -32600(잘못된 요청), -32601(메서드 없음), -32602(잘못된 파라미터), -32603(내부 오류)입니다. MCP TypeScript SDK에서 -32000과 -32001은 MCP error -32001: Request timed out에서 보듯 클라이언트 쪽 코드로, 연결이 닫혔거나 요청 타임아웃(기본값 60초) 안에 응답이 오지 않았다는 뜻입니다. 실행은 됐지만 실패한 도구는 다릅니다. 이 경우 isError: true가 담긴 일반 결과를 반환합니다.

코드는 JSON-RPC 2.0 명세, MCP 2025-11-25 도구 페이지, 2026-07-28 변경 로그, TypeScript SDK v1.x의 types와 protocol 소스에서 가져왔으며, 모두 2026-09-28에 확인했습니다. Sume 예시는 Sume 호스팅 MCP 서버의 현재 코드를 설명합니다. 기초 페이지는 이 서버가 여전히 동작하지만 현재 주 경로에는 속하지 않는다고 설명합니다.

MCP 오류 코드는 각각 무엇을 뜻하나요?

JSON-RPC는 -32768부터 -32000까지를 미리 정의된 오류용으로 예약하고, -32000부터 -32099까지는 구현에서 정의하는 서버 오류용으로 따로 둡니다. 그래서 이 마지막 범위의 숫자는 SDK에서와 서버에서 서로 다른 뜻일 수 있습니다.

MCP error -32001: Request timed out 오류는 왜 나나요?

서버가 오류를 보내서가 아니라 클라이언트가 기다리기를 멈췄기 때문입니다. TypeScript SDK에서는 요청마다 타이머가 시작됩니다. timeout 밀리초 안에 응답이 오지 않으면 요청은 RequestTimeout과 Request timed out 메시지로 실패하고, SDK의 오류 클래스는 이를 MCP error -32001: Request timed out으로 출력합니다. 기본값인 DEFAULT_REQUEST_TIMEOUT_MSEC는 60,000ms입니다.

• 클라이언트가 허용한다면 요청 timeout을 늘리세요. SDK에서는 resetTimeoutOnProgress(기본값 false)로 진행 상황 알림이 올 때 타이머를 다시 시작하게 할 수 있고, maxTotalTimeout으로 전체 대기 시간의 상한을 정할 수 있습니다.
• 60초 기본값은 TypeScript SDK의 값입니다. 다른 방식으로 만든 클라이언트는 다른 값을 쓸 수 있으니, 해당 클라이언트의 문서를 확인하세요.
• 오래 걸리는 작업은 먼저 응답하게 하고, 짧은 구간으로 나눠 기다리세요. 현재 코드에서 Sume 서버의 생성 도구는 Job id로 응답하며, jobs_wait 호출 한 번은 최대 55초까지 대기합니다. 이 루프는 긴 영상 Job의 MCP 도구 호출 타임아웃에서 다룹니다.
• 바로 옆 코드인 -32000 Connection closed는 요청이 대기 중일 때 트랜스포트가 닫혔다는 뜻입니다. SDK는 대기 중이던 요청을 모두 이 코드로 실패시킵니다.

실패한 도구 호출도 MCP 오류 코드인가요?

아니요, 다릅니다. MCP 명세는 두 가지 방식을 씁니다. 프로토콜 오류는 알 수 없는 도구, 형식이 잘못된 요청, 서버 오류에 쓰는 표준 JSON-RPC 오류입니다. API 실패, 입력 검증 오류, 비즈니스 로직 오류 같은 도구 실행 오류는 isError: true가 담긴 일반 결과로 돌아옵니다. 클라이언트는 모델이 스스로 바로잡을 수 있도록 도구 실행 오류를 모델에 전달해야 합니다(SHOULD). 프로토콜 오류는 복구로 이어질 가능성이 더 낮습니다. 다음은 명세의 두 예시입니다.

// Protocol error: a JSON-RPC error object
{ "jsonrpc": "2.0", "id": 3,
  "error": { "code": -32602, "message": "Unknown tool: invalid_tool_name" } }

// Tool execution error: a normal result with isError
{ "jsonrpc": "2.0", "id": 4,
  "result": {
    "content": [{ "type": "text",
      "text": "Invalid departure date: must be in the future. Current date is 08/08/2025." }],
    "isError": true } }

Sume MCP 서버에서는 각 코드가 무엇을 뜻하나요?

https://mcp.sume.com/mcp에서 서버의 현재 코드는 다음과 같이 응답합니다.

• jsonrpc: "2.0"이나 문자열 method가 없는 메시지에는 -32600으로 응답합니다. MCP-Protocol-Version 헤더가 2025-03-26, 2025-06-18, 2025-11-25가 아닐 때도 HTTP 400, Unsupported MCP protocol version.과 함께 이 코드로 응답합니다.
• 메서드가 initialize, ping, tools/list, tools/call이 아닌 요청에는 -32601(MCP method is not supported: …)로 응답합니다. 서버는 tools 기능(capability)만 선언하므로 resources/list도 여기에 해당합니다.
• 도구 이름이 없는 tools/call처럼 그 밖의 요청 실패에는 -32602로 응답합니다.
• 호출자의 MCP 작업 예산이 가득 찼고 메시지가 도구 호출이 아니면 HTTP 429와 함께 -32000(MCP work budget is full; retry shortly.)으로 응답합니다.
• 도구 실패는 텍스트가 code와 message를 담은 JSON인 isError: true 결과입니다. mcp:write가 없는 OAuth 세션은 쓰기 도구에서 insufficient_scope를 받습니다(해결 방법). 알 수 없는 도구 이름에는 도구 결과로 tool_not_found가 돌아오는데, 명세 자체의 예시는 이 경우에 -32602를 씁니다.

2026-07-28 개정판에서 코드가 바뀌었나요?

이 개정판은 서버 오류 범위에 대한 정책을 정했습니다. -32000부터 -32019까지는 계속 구현에서 정의하는 범위로 남고 기존 SDK의 사용은 그대로 인정되며, -32020부터 -32099까지는 MCP 명세용으로 예약됩니다. 또한 그 초안에서 도입된 코드 세 개를 -32020(HeaderMismatch), -32021(MissingRequiredClientCapability), -32022(UnsupportedProtocolVersion)로 옮겼고, 리소스를 찾을 수 없음 오류를 -32002에서 -32602로 바꿨습니다. MCP 밖에서 쓰는 Sume의 error.code 토큰은 별개의 체계이며, 표면별 Sume API 오류 코드에 정리되어 있습니다.