MCP Protocol Explained: JSON-RPC and server/discover
On this page
Learning Objective
Read and write raw MCP messages: JSON-RPC requests, results and errors, the server/discover call, the per-request metadata introduced by the stateless 2026-07-28 revision, result types, and how protocol versions are negotiated.
Concept Explanation
MCP messages are JSON-RPC 2.0. A request has a jsonrpc field set to "2.0", an id, a method such as tools/list, and params. A response carries the same id and either a result or an error with a numeric code and message. A notification is a request without an id that expects no response. Knowing this format makes MCP debuggable with nothing more than a log of messages.
Earlier revisions of MCP were stateful. A client opened a connection with an initialize request, the server replied with its capabilities, the client sent notifications/initialized, and the two remembered each other for the rest of the session. Over HTTP the server issued an Mcp-Session-Id header that every later request had to carry. That made servers hard to scale: a load balancer had to route each session to the same instance, and losing an instance lost the session.
The 2026-07-28 revision removed protocol sessions and the initialize handshake. Every request now carries what the server needs to know inside params._meta: the protocol version under io.modelcontextprotocol/protocolVersion, the client's capabilities under io.modelcontextprotocol/clientCapabilities, and, recommended, the client's identity under io.modelcontextprotocol/clientInfo. Any server instance can answer any request. If the version is unsupported, the server returns an UnsupportedProtocolVersion error and the client can fall back.
To learn what a server supports before calling it, a client may call server/discover. Servers must implement it; it returns the supported protocol versions, the server's capabilities (for example tools with listChanged), optional instructions for the model, and the server's identity. Clients use it for up-front version selection and as a probe to tell a modern server from a legacy one that still expects initialize. The official SDKs do this automatically and fall back to the old handshake on legacy servers.
Every result now has a resultType. Ordinary results are "complete". A server that needs more information to finish, such as a confirmation from the user, returns "input_required" with a list of inputRequests and an opaque requestState. The client gathers the answers and retries the original request with inputResponses and the same requestState. This multi round-trip pattern (Day 19) replaces the server-to-client requests of earlier versions, which needed a persistent connection. List and read results also carry caching hints, ttlMs and cacheScope, so clients can reuse tool lists instead of asking again on every turn.
| Element | Where | Meaning |
|---|---|---|
| jsonrpc, id, method, params | Every request | JSON-RPC 2.0 envelope |
| _meta io.modelcontextprotocol/protocolVersion | Request params | Version this request speaks, sent every time |
| _meta io.modelcontextprotocol/clientCapabilities | Request params | What the client supports, such as elicitation |
| server/discover | Method | Server's versions, capabilities, instructions and identity |
| resultType | Every result | "complete", or "input_required" with inputRequests |
| ttlMs, cacheScope | List and read results | How long and where a result may be cached |
Worked Example: A Real Exchange Captured from the Python SDK
These lines were captured between the official Python client and a small notes server running protocol 2026-07-28 over stdio. They are trimmed but otherwise verbatim. Lines starting with >> go to the server; << come back.
>> {"jsonrpc":"2.0","id":1,"method":"server/discover","params":{"_meta":{
"io.modelcontextprotocol/protocolVersion":"2026-07-28",
"io.modelcontextprotocol/clientInfo":{"name":"mcp","version":"0.1.0"},
"io.modelcontextprotocol/clientCapabilities":{"elicitation":{"form":{},"url":{}}}}}}
<< {"jsonrpc":"2.0","id":1,"result":{"resultType":"complete",
"supportedVersions":["2026-07-28"],
"capabilities":{"tools":{"listChanged":true},"resources":{"listChanged":true,"subscribe":true},
"prompts":{"listChanged":true}},
"instructions":"Search and add team notes.","cacheScope":"private","ttlMs":0,
"_meta":{"io.modelcontextprotocol/serverInfo":{"name":"notes","version":""}}}}
>> {"jsonrpc":"2.0","id":3,"method":"tools/call","params":{"name":"search_notes",
"arguments":{"query":"deploy"},"_meta":{ ...same three keys as above... }}}
<< {"jsonrpc":"2.0","id":3,"result":{"resultType":"complete","isError":false,
"content":[{"type":"text","text":"{\n \"id\": \"1\",\n \"text\": \"Deploy runbook: run make deploy\"\n}"}],
"structuredContent":{"result":[{"id":"1","text":"Deploy runbook: run make deploy"}]},
"_meta":{"io.modelcontextprotocol/serverInfo":{"name":"notes","version":""}}}}Notice there is no initialize call and no session id: request 3 is self-contained, so it could have gone to any replica of the server. The tool result carries both text content for the model and structuredContent for programs (Day 18).
Real-World Examples
- The 2026-07-28 changelog lists removing protocol-level sessions and the initialize handshake as its first two major changes, motivated by the difficulty of running stateful MCP servers behind load balancers and serverless platforms.
- Google's developer blog described the stateless update as a way to scale MCP servers horizontally on infrastructure such as Cloud Run, where any instance can serve any request.
Review Questions & Answers
Sessions forced every request from a client to reach the same server instance, which made horizontal scaling, load balancing and serverless hosting difficult. With per-request metadata any instance can handle any request.
In params._meta, under io.modelcontextprotocol/protocolVersion and io.modelcontextprotocol/clientCapabilities, on every request, with clientInfo recommended alongside them.
It returns the server's supported protocol versions, capabilities, instructions and identity. Clients call it to pick a version up front or to probe whether a server is modern or still expects the legacy initialize handshake.
The server needs more information, such as a user confirmation, to complete the request. The client collects answers to the listed inputRequests and retries the original request with inputResponses and the same requestState.