JSON-RPC
Also known as: JSON Remote Procedure Call, JSON-RPC 2.0, RPC over JSON
- JSON-RPC
- JSON-RPC is a remote procedure call protocol that encodes requests and responses as JSON objects. A caller names a method and supplies parameters; the receiver runs it and returns a result or a structured error, independent of language or transport.
JSON-RPC is a lightweight protocol that lets one program call functions in another program by exchanging structured JSON messages, regardless of the programming languages or transport involved.
What It Is
When two separate programs need to cooperate — say, an AI assistant and an external tool that reads your files — they need an agreed way to ask each other to do things and get answers back. JSON-RPC is one of the simplest answers to that problem. It is a small set of rules for one program to call a function inside another using JSON, the same human-readable text format that powers most web APIs. If you have been reading about the Model Context Protocol (MCP), JSON-RPC is the actual language that MCP clients and servers speak to each other underneath.
The mechanics are deliberately small. The caller sends a request object with three main parts: a method (the name of the function to run, such as “call this tool”), params (the arguments that function needs), and an id (a tracking number that links the eventual answer to this specific request). It works like a standardized order form — you write down what you want and a ticket number, hand it over, and later receive a reply tagged with that same number.
The receiver does the work and sends back a response object containing either a result, when things succeed, or an error — a structured object with a code and a message explaining what went wrong. There is also a “notification”: a request sent with no id, meaning the caller does not expect a reply. Because both sides agree only on this JSON shape, neither program needs to know how the other is built internally.
That last point is why JSON-RPC travels so well. It does not care what programming languages the two programs use, and it does not care how the messages move — over standard input and output, a local socket, or HTTP. The protocol defines the conversation, not the channel. That separation is exactly what makes it a comfortable fit for AI tooling.
How It’s Used in Practice
The most common place a non-specialist meets JSON-RPC today is inside AI tool integrations. When you connect an AI assistant like Claude to an external capability — a file browser, a database, a ticketing system — through MCP, every message between them is a JSON-RPC call. The client embedded in the assistant sends a request like “list the available tools” or “call this tool with these arguments,” and the server wrapping the external system replies with a JSON-RPC result. You never see this exchange; it happens beneath the chat interface.
Beyond AI, JSON-RPC has quietly run infrastructure for years — blockchain nodes and some code-editor language servers use it to expose their functions. But for most people encountering the term now, the entry point is MCP and agentic tooling.
Pro Tip: When an MCP integration misbehaves, the JSON-RPC error object is your fastest clue. It carries a short code and a message — log the raw request and response, and you can usually tell within seconds whether the client sent malformed params or the server’s method simply failed.
When to Use / When Not
| Scenario | Use | Avoid |
|---|---|---|
| Connecting an AI assistant to external tools via MCP | ✅ | |
| Exposing a clean set of named functions between two services | ✅ | |
| Building a public, resource-oriented web API for browsers | ❌ | |
| Streaming large media or high-volume binary data | ❌ | |
| Quick internal calls where you control both client and server | ✅ | |
| Needing rich HTTP semantics like caching and status codes | ❌ |
Common Misconception
Myth: JSON-RPC is just another name for a REST API. Reality: They solve different problems. REST models everything as resources you act on with HTTP verbs (GET, POST, DELETE) and URLs. JSON-RPC models everything as functions you call by name, and it does not depend on HTTP at all — it can run over a local pipe with no web server involved. MCP chose JSON-RPC precisely because tool calls are actions (“run this”), not resources to fetch.
One Sentence to Remember
JSON-RPC is the quiet, language-neutral courier that carries “call this function” requests between programs — and when you connect an AI assistant to outside tools through MCP, it is the format doing the talking. To see how those messages actually flow between hosts, clients, and servers, the MCP architecture is the natural next read.
FAQ
Q: Is JSON-RPC the same as REST? A: No. REST organizes everything around resources and HTTP verbs, while JSON-RPC organizes everything around named function calls. JSON-RPC also works without HTTP, over pipes or sockets, which REST cannot.
Q: Why does MCP use JSON-RPC? A: MCP connects AI clients to tool servers that expose actions like “call this tool.” JSON-RPC is built exactly for named, two-way function calls and stays independent of transport, making it a natural fit.
Q: Do I need to learn JSON-RPC to use AI tools? A: No. If you use an MCP-enabled assistant, JSON-RPC runs invisibly underneath. You only need it when building or debugging an integration, where reading the request and response helps.
Expert Takes
Not a transport. A contract. JSON-RPC defines only the shape of a request and its matching reply — a method name, parameters, and an identifier that pairs answer to question. Everything else, including how bytes travel, is left open. That minimalism is the point: by specifying just enough structure to call a function and route its result, it stays usable across languages, processes, and machines without inventing anything new.
Diagnosis, then fix, in one format. When an AI integration breaks, the JSON-RPC error object tells you where: malformed params point at the client’s spec, a failed method points at the server. Treat the request and response as the source of truth for the contract between them. Write the method names and expected params into your integration notes, and a whole class of “it just doesn’t work” tickets disappears.
Here is the strategic read: the protocol that wins is the boring one everybody already understands. JSON-RPC was sitting in blockchain and developer tooling for years, unglamorous and dependable. Then agentic AI needed a way for assistants to call tools, and the industry reached for the proven format instead of inventing a new one. Boring, battle-tested plumbing beats novelty.
A question worth sitting with: if the messages between your AI assistant and its tools are invisible by design, who is actually watching what gets requested? JSON-RPC makes integration clean, but that same cleanness hides the calls — a tool quietly asked to read a file, delete a record, send a message. The format is neutral. The accountability for what flows through it is not, and it rarely has an obvious owner.