MCP-ERR-002

Unknown method returns HTTP 404 and JSON-RPC -32601

“If the server does not implement the requested RPC method, it MUST respond with 404 Not Found and a JSON-RPC error with code -32601 (Method not found).” — spec anchor

How to fix this

Answer an unknown method with HTTP 404 *and* JSON-RPC `-32601`. Both matter: every intermediary reads the status code, none parses the body.

Example: failing and passing

The method is unknown, and the server returns -32601 inside an HTTP 200 instead of a 404.

Violates MCP-ERR-002 · HTTP

POST /mcp HTTP/1.1
Host: mcp.example.com
Content-Type: application/json
MCP-Protocol-Version: 2026-07-28
Mcp-Method: x/nonexistent-method

{"jsonrpc": "2.0", "id": 1, "method": "x/nonexistent-method",
  "params": {
    "_meta": {"io.modelcontextprotocol/protocolVersion": "2026-07-28",
              "io.modelcontextprotocol/clientCapabilities": {}}}}

HTTP/1.1 200 OK
Content-Type: application/json

{"jsonrpc": "2.0", "id": 1, "error": {"code": -32601, "message": "Method not found"}}

The server answers the unknown method with 404 Not Found and JSON-RPC -32601.

Complies with MCP-ERR-002 · HTTP

POST /mcp HTTP/1.1
Host: mcp.example.com
Content-Type: application/json
MCP-Protocol-Version: 2026-07-28
Mcp-Method: x/nonexistent-method

{"jsonrpc": "2.0", "id": 1, "method": "x/nonexistent-method",
  "params": {
    "_meta": {"io.modelcontextprotocol/protocolVersion": "2026-07-28",
              "io.modelcontextprotocol/clientCapabilities": {}}}}

HTTP/1.1 404 Not Found
Content-Type: application/json

{"jsonrpc": "2.0", "id": 1, "error": {"code": -32601, "message": "Method not found"}}

How the validator checks this

Probe P4.3, against a streamable-http server on the modern protocol. What it reports:

pass: Unknown method returned 404 and -32601
warn: Returned -32601 but HTTP … rather than 404. The spec names both — every intermediary reads the status, none parses the body.
fail: Unknown method must return 404 with -32601 — got HTTP …, code

Quoted from the probe that runs this check, so it cannot drift from what the validator actually reports.

This rule is checked deterministically: a fail here is a certain violation, not an inference.

Checked in the same request as MCP-DEP-001, MCP-DEP-002, MCP-DEP-003.

Check your own server against MCP-ERR-002

Probe P4.3 checks MCP-ERR-002 in the same request as 3 other rules, so one run shows your server's result for this rule next to the rest. Validate a server or read how the validator works.

Background on this topic: MCP error codes explained.

Other Error codes rules

MCP-ERR-001Unsupported version returns -32022 with data.supported[]
MCP-ERR-003Resource-not-found uses -32602, not the retired -32002
MCP-ERR-004The retired -32042 code is never emitted
MCP-ERR-005No undefined code is emitted in the reserved -32020…-32099 range
MCP-ERR-006Missing required _meta field returns HTTP 400 + JSON-RPC -32602
MCP-ERR-007Missing client capability returns -32021 with data.requiredCapabilities
MCP-ERR-008New implementation-defined codes avoid the legacy -32000…-32019 range