Catalog My learning Blog
Build AI Agents with MCP: 30-Day Course · Phase 3 · Lesson 12 · 4 min read

MCP Protocol Explained: JSON-RPC and server/discover

On this page
  1. Learning Objective
  2. Concept Explanation
  3. Worked Example: A Real Exchange Captured from the Python SDK
  4. Real-World Examples
  5. Review Questions & Answers

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.

ElementWhereMeaning
jsonrpc, id, method, paramsEvery requestJSON-RPC 2.0 envelope
_meta io.modelcontextprotocol/protocolVersionRequest paramsVersion this request speaks, sent every time
_meta io.modelcontextprotocol/clientCapabilitiesRequest paramsWhat the client supports, such as elicitation
server/discoverMethodServer's versions, capabilities, instructions and identity
resultTypeEvery result"complete", or "input_required" with inputRequests
ttlMs, cacheScopeList and read resultsHow 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.

Code
>> {"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).

Since 2026-07-28 there is no initialize handshake or session id. The client may call server/discover, and every request carries its protocol version and capabilities in _meta, so any server replica can answer.
Since 2026-07-28 there is no initialize handshake or session id. The client may call server/discover, and every request carries its protocol version and capabilities in _meta, so any server replica can answer.

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.
Key TakeawaysMCP is built on JSON-RPC 2.0, so every message between a host and a server is a request, a response or a notification in a fixed format. Since 2026-07-28 it is stateless: there is no initialize handshake or session id, every request carries its protocol version and client capabilities in _meta, and servers implement server/discover so clients can learn versions and capabilities. Every result has a resultType, and input_required results drive multi round-trip requests. Caching hints let clients reuse lists.

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.