Versions and stateless requests

The modern way: every request stands alone

A letter is different from a phone call. It has to say everything the reader needs, because the reader remembers nothing. The 2026-07-28 revision made MCP stateless, the word for keeping nothing between messages. There's no handshake. Instead, every request carries what the server needs in params._meta:

{
  "jsonrpc": "2.0",
  "id": 1,
  "method": "tools/list",
  "params": {
    "_meta": {
      "io.modelcontextprotocol/protocolVersion": "2026-07-28",
      "io.modelcontextprotocol/clientCapabilities": {},
      "io.modelcontextprotocol/clientInfo": {"name": "shop-assistant", "version": "0.3.0"}
    }
  }
}

• protocolVersion (required): the revision this request uses.
• clientCapabilities (required): the optional features this client supports, such as elicitation. An empty object means "only the basics".
• clientInfo (recommended): the client's name and version, for logs and display only.

The long names start with io.modelcontextprotocol/. That prefix marks them as the protocol's own, so other tools can add their own keys to _meta without clashing. Two of those fields are required in every modern request: io.modelcontextprotocol/protocolVersion and io.modelcontextprotocol/clientCapabilities. A request missing either is malformed. The server answers with error -32602 (Invalid params), and HTTP 400 over HTTP.

Results answer in kind. Each has resultType ("complete" for ordinary results), and a _meta holding io.modelcontextprotocol/serverInfo, the server's own name and version.

In plain words: the server no longer has to remember you, because each request introduces itself.

class LegacyServer:
    def __init__(self):
        self.sessions = {}
    def handle(self, session, method):
        if method == "initialize":
            self.sessions[session] = "2025-03-26"
            return "ok"
        if session not in self.sessions:
            return "error: unknown session"
        return f"{method} answered"

class ModernServer:
    def handle(self, meta, method):
        if "protocolVersion" not in meta:
            return "error: missing _meta"
        return f"{method} answered"

copies = [LegacyServer(), LegacyServer()]
print(copies[0].handle("s1", "initialize"))
print(copies[1].handle("s1", "tools/list"))   # the next request lands on the other copy

copies = [ModernServer(), ModernServer()]
meta = {"protocolVersion": "2026-07-28"}
print(copies[0].handle(meta, "tools/list"))
print(copies[1].handle(meta, "tools/list"))

Negotiating a version

There's no up-front agreement, so negotiation happens per request. Picture asking for something in French abroad, and the clerk answering "sorry, I speak English and German". You pick one of those and ask again.

If the server doesn't support the version a request names, it answers with UnsupportedProtocolVersion, error code -32022, and lists what it does support:

{"jsonrpc": "2.0", "id": 1, "error": {"code": -32022, "message": "Unsupported protocol version",
  "data": {"supported": ["2026-07-28", "2025-11-25"], "requested": "2027-01-15"}}}

The client picks a version both sides support, preferring the newest it knows, and retries. If there's none in common, it reports a clear error to the user, with both lists, instead of failing mysteriously. A client remembers the answer for that server, so it doesn't pay for the extra round trip on every call.

In plain words: ask in your newest language. If the server says no, pick the newest one you both speak.

CLIENT_VERSIONS = ["2026-07-28", "2025-11-25", "2025-06-18"]     # newest first

def choose_version(server_supported):
    for v in CLIENT_VERSIONS:
        if v in server_supported:
            return v
    return None

print(choose_version(["2025-11-25", "2025-06-18"]))
print(choose_version(["2026-07-28"]))
print(choose_version(["2024-11-05"]))

ours = ["2026-07-28", "2025-11-25", "2025-06-18"]
theirs = ["2025-11-25", "2025-06-18"]
print(next((v for v in ours if v in theirs), None))

When something must be remembered

Some things really do have to last across calls. A shopping basket is the classic case: add an item now, pay for it three calls later. In stateless MCP the server still can't keep that in connection memory, because the next call may reach a different copy.

The answer is a handle: the server stores the basket somewhere all its copies can read, such as a database, and returns a short id like "bsk_0001". The client sends that id back as an ordinary tool argument on later calls. It works like a coat check. You hand over the coat, you get a ticket, and any attendant can fetch the coat from the ticket.

The server should also check that the handle belongs to the caller, so one customer can't open another's basket by guessing an id.

In plain words: state that must last gets a ticket, and the ticket travels with every request.

STORE = {}                      # stands in for a database every copy can reach

class ModernServer:
    def open_basket(self):
        handle = f"bsk_{len(STORE) + 1:04d}"
        STORE[handle] = []
        return handle
    def add_item(self, handle, item):
        if handle not in STORE:
            return "error: unknown basket"
        STORE[handle].append(item)
        return f"{len(STORE[handle])} item(s) in {handle}"

copies = [ModernServer(), ModernServer()]
handle = copies[0].open_basket()             # the first call lands on copy 0
print(copies[1].add_item(handle, "socks"))   # the next lands on copy 1
print(copies[0].add_item(handle, "hat"))
print(copies[1].add_item("bsk_9999", "scarf"))