Live on Product Hunt Intraface launched today. Less steering, more vacations. See the launch
Start for free

What is JSON-RPC?

JSON-RPC is a lightweight remote procedure call protocol that encodes every message as JSON: a request names a method and carries params and an id, the response echoes that id with a result or an error, and a notification has no id and gets no reply. Version 2.0, from 2010, is the one the Model Context Protocol is built on.

Part of Glossary: the terms behind MCP, coding agents and shared pages, defined plainly.

How it works

A request carries a method and an id; the reply carries the same id with a result or an error; a notification has no id and gets nothing back.any transport: stdio,HTTP, postMessagecallerMCP clientcalleethe id is the onlylink between the two1. {id: 7, method, params}2. {id: 7, result | error}3. {method}, no reply
  1. The caller sends an object with "jsonrpc": "2.0", a method name, optional params (an object or an array) and an id.

    {"jsonrpc":"2.0","id":1,"method":"tools/list"}
  2. The callee answers with the same id and exactly one of result or error. Nothing else says which request a reply belongs to.

    {"jsonrpc":"2.0","id":1,"result":{"tools":[]}}
  3. An error carries an integer code, a short message and optional data. Codes from -32768 to -32000 are reserved; -32601 means the method does not exist.

  4. Leave out the id and the message is a notification: one way, no response, and no way to learn that it failed.

  5. The spec says nothing about transport. MCP sends these messages over stdio, one per line, over HTTP, one per POST, and inside MCP Apps over postMessage.

Source: JSON-RPC 2.0 Specification

JSON-RPC versus REST

REST spreads meaning across the HTTP request: the verb says what to do, the path says to what, the status code says how it went. JSON-RPC puts all of that inside one JSON object. The method string names the operation, params carries the arguments, and the reply is another object that either has result or has error, never both. HTTP, if it is even involved, is just the pipe.

That is why MCP picked it. An MCP server launched as a subprocess has no URLs and no status codes, only stdin and stdout. A remote server has both. With JSON-RPC the two speak identically: the same tools/call object goes down a pipe as one line of text or up to a server as the body of one POST. The spec version is 2.0, published in 2010 and last revised in 2013, and the whole thing fits on one page.

Example: a tool call in MCP

An agent wants the weather. Its client sends:

{"jsonrpc":"2.0","id":3,"method":"tools/call","params":{"name":"weather_current","arguments":{"location":"Lisbon"}}}

The server replies with the same id:

{"jsonrpc":"2.0","id":3,"result":{"content":[{"type":"text","text":"19°C, clear"}]}}

If the tool did not exist, the reply would instead carry "error":{"code":-32601,"message":"Method not found"}. Notice that a tool failing is not a JSON-RPC error: MCP returns a normal result with isError: true, because the call itself succeeded and the model should see what went wrong. Keeping protocol failures and tool failures apart is one of the more useful habits the format encourages.

Where it shows up in practice

Every MCP message is JSON-RPC, so the format decides how debugging feels. When you watch traffic in the MCP Inspector you are reading these objects. When a client logs "request 12 timed out", 12 is the id. A notifications/tools/list_changed message has no id, so no one waits for it and no one will tell you if it was dropped; that is one reason MCP's list results now carry a ttlMs hint, so a client can refresh on its own schedule instead of trusting the notification alone. MCP Apps reuse the format a third time, sending tools/call and ui/initialize between an iframe and its host over postMessage.

Common mistakes

  • Reusing ids. JSON-RPC lets a client pick any id; MCP forbids reusing one while its reply is outstanding, and forbids null. Use a counter.
  • Replying to a notification. The spec is explicit that the receiver must not. A client that gets an unexpected response to nothing will usually log an error and may drop the connection.
  • Inventing error codes in the reserved range. -32768 to -32000 belongs to the spec and, within MCP, -32020 to -32099 to MCP itself. Application errors go outside that range, or better, into a tool result the model can read.
  • Expecting ordering. Responses may arrive in any order. Match on id, not on position.

FAQ

Why does MCP use JSON-RPC instead of REST?
MCP needs the same messages to work over a pipe to a local process and over HTTP to a remote one, and it needs notifications nobody replies to. JSON-RPC gives it a framing that is independent of URLs and HTTP verbs, so one schema serves every transport.
Does MCP change any JSON-RPC rules?
It tightens a few. A request id must be a string or integer, never null, and must not be reused while a reply is outstanding. Params are always an object. Messages must be UTF-8. And MCP reserves part of the server-error range, -32020 to -32099, for codes it defines, such as -32020 for a header that does not match the body.
Does JSON-RPC support sending several calls at once?
The 2.0 spec does, as a JSON array of requests answered by an array of responses in any order. MCP's Streamable HTTP transport does not use it: each POST body must be a single request or notification.

Stop sending HTMLover Slack.

Create an account in a minute, connect your coding agent, and make your first board.