MCP-ERR-008

New implementation-defined codes avoid the legacy -32000…-32019 range

“New codes MUST NOT be allocated in this sub-range, and new implementations SHOULD NOT use codes from this sub-range at all.” — spec anchor

How to fix this

Move implementation-defined codes out of `-32000`…`-32019`. New codes must not be allocated there, and new implementations should avoid the range entirely.

Example: failing and passing

The server uses -32001 for an upstream outage, a code from the legacy -32000…-32019 sub-range.

Violates MCP-ERR-008 · JSON

{
  "jsonrpc": "2.0",
  "id": 4,
  "error": {
    "code": -32001,
    "message": "Upstream database unavailable"
  }
}

The server uses an application-defined code outside the JSON-RPC reserved range -32768…-32000.

Complies with MCP-ERR-008 · JSON

{
  "jsonrpc": "2.0",
  "id": 4,
  "error": {
    "code": 1002,
    "message": "Upstream database unavailable"
  }
}

How the validator checks this

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

pass: No response used the legacy -32000…-32019 range
warn: Used … from the legacy -32000…-32019 range, which new implementations SHOULD NOT use at all

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

This rule is checked heuristically: a fail is inferred rather than certain, so it bumps the overall grade up one level instead of being treated as certain non-compliance.

Checked in the same request as MCP-HDR-008, MCP-HDR-009, MCP-RES-003, MCP-RES-006, MCP-RES-007, MCP-ERR-003, MCP-ERR-004, MCP-ERR-005, MCP-CAC-001, MCP-CAC-002, MCP-CAC-003, MCP-CAC-004, MCP-CAC-005, MCP-SCH-001, MCP-SCH-002, MCP-SCH-003, MCP-SCH-004, MCP-SCH-005, MCP-SCH-006, MCP-SCH-007, MCP-SEC-004, MCP-SEC-005, MCP-SEC-006, MCP-DEP-005.

Check your own server against MCP-ERR-008

Probe P2.1 checks MCP-ERR-008 in the same request as 24 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-002Unknown method returns HTTP 404 and JSON-RPC -32601
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