Skip to content

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, optional params and an id. MCP is stricter than plain JSON-RPC here: the id must be a string or an integer, never null, and must not repeat an id still waiting for an answer.
  • Response: the same id, plus either result or error, 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:

CodeNameMeaning
-32700Parse errorThe body is not valid JSON.
-32600Invalid RequestValid JSON, but not a valid request object.
-32601Method not foundThe method does not exist or is not available.
-32602Invalid paramsThe parameters are wrong.
-32603Internal errorInternal JSON-RPC error.
-32000 to -32099Server errorLeft 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 ​

json
{"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 ​

This website (not the L2M product) uses Google Analytics, only after you accept cookies. Cookie settings