JSON-RPC
A small message format for remote calls: a request names a method and carries an id, the response echoes that id with a result or a numbered error, and a notification has no id and gets no answer.
Every message between an MCP clientMCP client: The part of an AI application that holds one connection to one MCP server: it negotiates the protocol version and capabilities, then sends that server's requests and receives its replies. and an MCP serverMCP server: A program that offers tools, resources or prompts to AI applications over the Model Context Protocol, locally over stdio or remotely over HTTP. is a JSON-RPC 2.0 object, whether it travels over stdiostdio transport: The MCP transport in which the client starts the server as a child process and exchanges newline-delimited JSON-RPC messages over the process's standard input and output. or Streamable HTTPStreamable HTTP: The MCP transport for servers reached over a network: every client message is an HTTP POST to one endpoint, and the server answers with a JSON body or a server-sent events stream.. There are three kinds:
- Request:
jsonrpc,method, optionalparamsand anid. MCP is stricter than plain JSON-RPC here: the id must be a string or an integer, nevernull, and must not repeat an id still waiting for an answer. - Response: the same
id, plus eitherresultorerror, never both. - Notification: a request without an
id. The receiver must not reply, so the sender never learns whether it failed.
The id is what lets many calls share one connection: answers can come back in any order and still be matched.
Error codes
JSON-RPC reserves -32768 to -32000 for predefined errors:
| Code | Name | Meaning |
|---|---|---|
| -32700 | Parse error | The body is not valid JSON. |
| -32600 | Invalid Request | Valid JSON, but not a valid request object. |
| -32601 | Method not found | The method does not exist or is not available. |
| -32602 | Invalid params | The parameters are wrong. |
| -32603 | Internal error | Internal JSON-RPC error. |
| -32000 to -32099 | Server error | Left to implementations. |
MCP 2026-07-28 splits that server range: -32020 to -32099 is reserved for codes the MCP specification defines (such as -32022, unsupported protocol version), and -32000 to -32019 is legacy, where receivers must not assume a meaning, except -32002 (resource not found in older revisions).
The two codes people hit most with tools have their own guides: -32602 Invalid params and -32601 Method not found.
Example
{"jsonrpc":"2.0","id":7,"method":"tools/call","params":{"name":"get_weathr","arguments":{}}}
{"jsonrpc":"2.0","id":7,"error":{"code":-32602,"message":"Unknown tool: get_weathr"}}
{"jsonrpc":"2.0","method":"notifications/tools/list_changed"}Common confusion
A JSON-RPC error is not the same as a failed tool. MCP reports a tool that ran and failed (an API down, a date in the wrong format) as a normal result with isError: true, which the model can read and correct. Protocol errors such as -32602 mean the request itself was wrong. Batches (an array of requests) are part of JSON-RPC, but MCP removed them in the 2025-06-18 revision.
In L2M
As a client, L2M answers requests a server sends it: ping, elicitation/create and sampling/createMessage, with -32602 for malformed ones and -32601 for any other method. The MCP gateway answers bad JSON with -32700, malformed messages with -32600, and accepts batches only on 2025-03-26. With the opt-in 2026-07-28 mode, mismatched headers get -32020 and unsupported versions -32022.
Further reading
- JSON-RPC 2.0 Specification (jsonrpc.org)
- MCP specification 2026-07-28: base protocol, messages and error codes (modelcontextprotocol.io)
- MCP specification 2025-11-25: tools, error handling (modelcontextprotocol.io)
- MCP 2025-06-18 changelog (modelcontextprotocol.io)