---
title: "What is JSON-RPC 2.0? The message format of MCP and A2A"
description: "JSON-RPC 2.0 is a lightweight remote procedure call format that MCP and A2A use for every message. How requests, responses, notifications, and errors work."
type: "glossary-term"
canonical_url: "https://theaiengineering.com/glossary/json-rpc"
markdown_url: "https://theaiengineering.com/glossary/json-rpc.md"
topic: "Model Context Protocol"
author: "The AI Engineering Editors"
publisher: "The AI Engineering"
updated: "2026-11-06"
keywords: ["JSON-RPC","JSON-RPC 2.0","JSON RPC"]
citation: "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"
---

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

Also called JSON-RPC 2.0, JSON RPC.

> **Definition of JSON-RPC:** 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](https://www.jsonrpc.org/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](https://theaiengineering.com/glossary/model-context-protocol) and the [A2A protocol](https://theaiengineering.com/glossary/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):

```json
{"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](https://modelcontextprotocol.io/specification/2026-07-28/basic) 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](https://a2a-protocol.org/latest/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](https://theaiengineering.com/glossary/mcp-transport) solves this by copying the method and tool name into HTTP headers. [What is Model Context Protocol](https://theaiengineering.com/articles/what-is-model-context-protocol) walks through a complete MCP tool call on the wire.

## Related terms

- [Model Context Protocol (MCP)](https://theaiengineering.com/glossary/model-context-protocol): Model Context Protocol (MCP) is an open protocol, introduced by Anthropic in November 2024, that standardizes how AI applications connect to external tools, data sources, and prompts through MCP servers.
- [MCP transport](https://theaiengineering.com/glossary/mcp-transport): An MCP transport is the binding that carries Model Context Protocol messages between a client and a server; the specification defines stdio for local subprocesses and Streamable HTTP for remote servers.
- [A2A protocol](https://theaiengineering.com/glossary/a2a-protocol): The A2A (Agent2Agent) protocol is an open standard, introduced by Google in April 2025, that lets AI agents built on different frameworks discover each other, exchange messages, and delegate tasks.
- [MCP server](https://theaiengineering.com/glossary/mcp-server): An MCP server is a program that exposes tools, resources, and prompts to AI applications through the Model Context Protocol, running locally over stdio or remotely over Streamable HTTP.
- [Tool calling](https://theaiengineering.com/glossary/tool-calling): Tool calling is an LLM capability in which the model, given a list of tool definitions, outputs a structured request naming a tool and its arguments, which the application executes and returns.

## Guides that cover json-rpc

- [A2A protocol vs MCP: differences and when to use each](https://theaiengineering.com/articles/a2a-vs-mcp): A2A protocol vs MCP: A2A connects AI agents to other agents, and MCP connects an agent to tools and data. Compare agent cards, tasks, transports, and security.
- [How to build an MCP server: a Python and TypeScript tutorial](https://theaiengineering.com/articles/how-to-build-an-mcp-server): Learn how to build an MCP server with the official Python and TypeScript SDKs: tools, resources, transports, testing, client config, and production security.
- [What is tool calling? How LLM function calling works](https://theaiengineering.com/articles/tool-calling): Tool calling lets an LLM request actions from your code through structured calls. Learn the request loop, parallel calls, structured outputs, security, and MCP.
- [What is the Model Context Protocol (MCP)? How it works](https://theaiengineering.com/articles/what-is-model-context-protocol): The Model Context Protocol (MCP) is an open standard for connecting AI apps to tools and data. Learn its architecture, transports, tool calls, and security.

Part of the [Model Context Protocol](https://theaiengineering.com/topics/mcp) topic hub.

## 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: 2026-11-06
- URL: https://theaiengineering.com/glossary/json-rpc
- Markdown: https://theaiengineering.com/glossary/json-rpc.md
