What is JSON-RPC 2.0? The message format of MCP and A2A

Also called JSON-RPC 2.0, JSON RPC

Definition

JSON-RPC is a lightweight, transport-agnostic remote procedure call protocol that encodes method calls, results, and errors as JSON objects; version 2.0 is the message format of MCP and A2A.

JSON-RPC is a stateless remote procedure call protocol that encodes each call, result, and error as a small JSON object. The JSON-RPC 2.0 specification, dated 2010-03-26, defines the message shapes and nothing else: it is transport agnostic, so the same messages can travel within one process, over sockets, over HTTP, or through other message-passing channels. Both the Model Context Protocol and the A2A protocol use JSON-RPC 2.0, so reading MCP traffic or debugging an A2A call starts with these objects.

How JSON-RPC works#

JSON-RPC works by exchanging four kinds of JSON object. A request names a method and carries an id. A response echoes that id and returns either a result or an error. A notification is a request without an id, and the receiver never replies to it. An error object carries an integer code and a message.

  • Request: "jsonrpc": "2.0", a method string, optional params (an array or an object), and an id that is a string, a number, or null.
  • Response: the same id, plus exactly one of result or error, never both.
  • Notification: no id, so the sender cannot learn whether it failed.
  • Error object: an integer code, a short message, and optional data.

Here is an MCP tools/call request and the error a server returns for an unknown tool (MCP's per-request _meta fields are omitted):

{"jsonrpc": "2.0", "id": 7, "method": "tools/call",
 "params": {"name": "search_issues", "arguments": {"query": "login bug"}}}
 
{"jsonrpc": "2.0", "id": 7,
 "error": {"code": -32602, "message": "Unknown tool: search_issues"}}

The specification predefines five error codes: -32700 (parse error), -32600 (invalid request), -32601 (method not found), -32602 (invalid params), and -32603 (internal error). It reserves -32000 to -32099 for implementation-defined server errors. A client may also send a batch, an array of requests that the server answers with an array of responses.

How MCP and A2A use JSON-RPC#

MCP and A2A both adopt JSON-RPC 2.0 messages, then tighten the rules and add their own error codes. MCP narrows what an id may be, puts protocol metadata inside every request, and drops batching. A2A uses JSON-RPC as one of three equivalent protocol bindings, with its own method names and task errors.

The MCP base protocol requires a string or integer id that is never null and never reused while a request is in flight. In the current revision, 2026-07-28, every request carries its protocol version and client capabilities in _meta, and every result carries a resultType field. MCP splits the server-error range: -32000 to -32019 is legacy, and -32020 to -32099 is reserved for codes the specification defines, such as HeaderMismatch (-32020) and UnsupportedProtocolVersion (-32022). Revision 2025-06-18 removed batching. A failed tool run is not a JSON-RPC error at all: it returns as a normal result with isError: true, so the model can read the message and retry with corrected arguments.

The A2A specification, version 1.0, defines JSON-RPC 2.0 over HTTP(S) alongside gRPC and HTTP+JSON bindings. Its methods include SendMessage, GetTask, and CancelTask, streaming responses use Server-Sent Events, and A2A errors run from -32001 (TaskNotFoundError) to -32009 (VersionNotSupportedError).

JSON-RPC vs REST#

JSON-RPC is method-oriented and REST is resource-oriented. A JSON-RPC client posts every call to one endpoint and names the method in the message body; a REST client picks a URL per resource and an HTTP verb per action. JSON-RPC reports errors inside the body, while REST relies on HTTP status codes.

JSON-RPC 2.0 REST
Unit of work A named method call An HTTP verb on a resource URL
Over HTTP One endpoint for every method One URL per resource
Transport Any: stdio, sockets, HTTP HTTP
Errors Error object with an integer code HTTP status codes

Because the method name lives in the body, an HTTP proxy cannot route JSON-RPC traffic without parsing it. MCP's Streamable HTTP transport solves this by copying the method and tool name into HTTP headers. What is Model Context Protocol walks through a complete MCP tool call on the wire.

Cite this definition

The AI Engineering Editors. "What is JSON-RPC 2.0? The message format of MCP and A2A." The AI Engineering, updated Nov 06, 2026. https://theaiengineering.com/glossary/json-rpc

Title
What is JSON-RPC 2.0? The message format of MCP and A2A
Author
The AI Engineering Editors
Publisher
The AI Engineering
Updated
View as Markdown

Part of the Model Context Protocol hub · Updated