CSE Roadmap

Core tier · about 5 hours · 14 parts

Part 4 of 14 · 2 min read

The protocol changed eras: a handshake session gave way to a stateless one

Think of a phone call that starts with "hello, can you hear me?" before any real conversation, versus a letter that states the sender's address on every single page so no page needs the one before it.

In plain words: the older protocol era opens a connection with a handshake (initialize, then a notifications/initialized message), and the server remembers that session. The newer era removes the handshake entirely. Every request carries its own protocol version and capabilities instead, so the server need not remember anything about who it is talking to between calls.

A worked example. A client that supports both eras probes a server by trying server/discover first. If the server answers normally, the client treats it as modern. If it answers with the specific "unsupported version" error, the client picks a version from the list the error provides. If it answers with anything else at all, the client treats the server as legacy and falls back to the handshake. Run against all nine combinations of three client modes and three server eras, this produces exactly the outcomes the specification's own compatibility table predicts. A modern-only client against a legacy-only server fails outright. A legacy-only client against a modern-only server fails too, because it has no way forward. A dual-era client works against all three.

The key lines. From code/mini-mcp/client.py:

# from code/mini-mcp/client.py
def connect(self) -> str:
    """Choose an era and get ready. Returns 'modern' or 'legacy'. Raises if no common version exists."""
    if self.mode in ("modern", "dual"):
        self.era, self.version = "modern", rpc.MODERN
        try:
            res = self._rpc("server/discover")
            self._take_discover(res)
            return "modern"
        except RpcError as e:
            if e.code == rpc.UNSUPPORTED_VERSION:                      # a modern server: pick a version it supports
                supported = (e.data or {}).get("supported", [])

Read it as: the method tries the modern probe first and only falls back on a specific, recognised failure. Any other exception propagates unchanged. That is what makes the probe safe: a dual-era client does not silently misread an unrelated error as "this must be a legacy server."

Protocol era (legacy, modern)

The legacy era opens a connection with an initialize handshake and a session the server remembers. The modern era removes the handshake: every request carries its own protocol version and capabilities, and the server remembers nothing between calls.

Example: measured on the same server and the same call, the legacy handshake costs one extra round trip before the first real call but 441 bytes per call afterwards. The modern era costs zero extra round trips but 738 bytes per call, because every request now repeats what the handshake used to establish once. It is a fixed cost traded for a per-call cost.