JSON-RPC 2.0 — The Wire · Protocol Quest

Underneath every MCP message is JSON-RPC 2.0. The spec is short — under 10 pages — and worth reading once because every quirk of MCP framing comes from it.

JSON-RPC has three message types. A request has a method, params, and a unique id; the receiver MUST reply with a result or error using the same id. A notification has the same shape but no id; the receiver MUST NOT reply. A response carries either a result field or an error field, never both.

Errors are first-class. Every JSON-RPC error has a numeric code, a short message, and optional data. The standard codes are: -32700 Parse error, -32600 Invalid request, -32601 Method not found, -32602 Invalid params, -32603 Internal error, and the server-defined range -32099 to -32000 for protocol-specific errors. MCP layers its own meanings on top of those last codes.

The piece that catches new MCP server authors is batch and concurrency. JSON-RPC permits batched requests (an array of request objects) and responses out of order on the same connection. MCP transport implementations vary in how strictly they support batches; the safe rule is to write your server such that it can handle interleaved requests and out-of-order responses, even if your current transport happens to serialize them.

Code

The three JSON-RPC message shapes·json

// Request — has id; receiver MUST reply
{"jsonrpc":"2.0","id":42,"method":"tools/call","params":{"name":"get_weather","arguments":{"location":"Seoul"}}}

// Notification — no id; receiver MUST NOT reply
{"jsonrpc":"2.0","method":"notifications/cancelled","params":{"requestId":42}}

// Response (success)
{"jsonrpc":"2.0","id":42,"result":{"content":[{"type":"text","text":"68°F"}]}}

// Response (error)
{"jsonrpc":"2.0","id":42,"error":{"code":-32602,"message":"Invalid params","data":{"missing":["location"]}}}

Standard JSON-RPC error codes you will see·text

-32700  Parse error           — server got malformed JSON
-32600  Invalid request       — message doesn't match JSON-RPC shape
-32601  Method not found      — your client called a method the server doesn't know
-32602  Invalid params        — params shape/types wrong
-32603  Internal error        — generic server failure
-32099 .. -32000              — protocol-specific (MCP defines its own meanings here)

JSON-RPC 2.0 — The Wire

Code

External links

Exercise

Progress

Comments 0