본문으로 건너뛰기

오류

MCP 클라이언트가 받을 수 있는 오류는 세 가지입니다. 오류마다 전달되는 위치가 다르므로 각각 해당 위치에서 처리해야 합니다.

HTTP 오류​

요청이 도구에 도달하지 못한 경우입니다. 본문은 코드 -32000인 JSON-RPC 오류입니다.

상태발생 조건대처 방법
401토큰이 없거나, 유효하지 않거나, 만료됨WWW-Authenticate 챌린지를 따릅니다. 권한 부여를 참고하세요
405엔드포인트에 GET 또는 DELETE를 보냄POST를 보냅니다. 이 엔드포인트에는 SSE 스트림도 세션도 없습니다
429할당량 한도를 초과함Retry-After초만큼 기다립니다. 할당량을 참고하세요

도구 오류​

도구가 실행되었다가 실패했거나, 실행되기 전에 거부된 경우입니다. 어느 쪽이든 응답은 일반적인 200이며, tools/call 결과에 isError: true와 원인을 설명하는 텍스트가 들어 있습니다. 입력 스키마와 맞지 않는 인수나 존재하지 않는 도구 이름처럼 도구 자체의 코드가 실행되기 전에 MCP SDK에서 발생하는 오류도 같은 방식으로 전달되며, 텍스트가 MCP error -32602:로 시작합니다. 이 오류들도 JSON-RPC error 객체가 아니라 도구 결과이므로, 클라이언트는 error.code가 아니라 result.isError를 확인해야 합니다.

도구 자체에서 발생한 오류의 예입니다. check_availability에 { "domains": ["!!!"] }를 보낸 경우:

{
    "result": {
        "content": [{ "type": "text", "text": "Invalid domain format" }],
        "isError": true
    },
    "jsonrpc": "2.0",
    "id": 4
}

입력 검증에서 발생한 오류의 예입니다. compare_prices에 { "domain": "kettlory" }를 보낸 경우:

{
    "result": {
        "content": [
            {
                "type": "text",
                "text": "MCP error -32602: Input validation error: Invalid arguments for tool compare_prices: A full domain name is required at domain"
            }
        ],
        "isError": true
    },
    "jsonrpc": "2.0",
    "id": 1
}
메시지원인
MCP error -32602: Input validation error: Invalid arguments for tool <name>: …인수가 도구의 입력 스키마와 맞지 않습니다. 필드가 빠졌거나, 값이 범위를 벗어났거나, 도메인에 점이 없는 경우입니다. 텍스트 끝에 해당 필드가 표시됩니다. 예: Too big: expected array to have <=20 items at domains
Invalid domain format도메인 이름에 쓸 수 없는 문자를 제거하고 나니 입력에 남은 것이 없거나, NameBeta가 모르는 TLD입니다. 그 밖의 불필요한 문자는 오류 없이 조용히 제거됩니다. check_availability를 참고하세요
MCP error -32602: Tool <name> not found도구 이름의 철자가 틀렸거나 존재하지 않는 도구입니다
그 밖의 메시지도구가 내부적으로 수행한 조회가 실패했습니다. 예를 들어 WHOIS 서버나 DNS 서버가 응답하지 않은 경우이며, 나중에 다시 시도하면 성공할 수 있습니다

각 도구 페이지에는 해당 도구에만 해당하는 오류가 정리되어 있습니다. 실패한 호출도 할당량에서 차감되는지는 호출을 세는 방식에서 설명합니다.

잘못된 형식의 요청​

MCP 전송 계층이 받아들일 수 없는 요청은 도구가 실행되기 전에 4xx 상태로 거부됩니다. 예를 들어 Accept 헤더에 application/json과 text/event-stream이 모두 들어 있지 않으면 406을 반환하고, 본문이 올바른 JSON-RPC가 아니면 JSON-RPC 파싱 오류(-32700)를 반환합니다. MCP 사양이 2025-06-18 개정판에서 배치를 제외했으므로, 배치(배열) 형태의 JSON-RPC 요청은 400과 JSON-RPC 오류 -32600으로 거부됩니다. POST 하나에 요청 하나만 보내세요. 이런 요청은 재시도하지 말고 요청 자체를 고쳐야 합니다. 엔드포인트가 받는 요청은 엔드포인트와 전송 방식에서 설명합니다.

최종 수정: 에