Module version 

MCP protocol version + era model, and version negotiation for both eras.

MCP versions are YYYY-MM-DD date strings marking the last backward-incompatible change; they sort chronologically as plain strings. Two eras (modelcontextprotocol.io/specification/draft/basic/versioning §terminology):

• Legacy — an initialize handshake + session (2025-11-25 and earlier). The client advertises its latest version in initialize; the server echoes it if supported, else returns one it does (client adopts or disconnects).
• Modern — stateless, per-request _meta (2026-07-28+). There is no handshake: every request declares its version, and an unsupported version is rejected per request with an UnsupportedProtocolVersion error (-32022) listing the server’s supported versions; the client retries with a mutual one. A dual-era client detects the server’s era once and caches it.

Structs

UnsupportedProtocolVersion

The payload of an UNSUPPORTED_PROTOCOL_VERSION_CODE error’s data — the modern era’s version-negotiation signal (versioning §protocol-version-negotiation).

Enums

Era

A protocol era: how version/identity/capabilities are conveyed and whether the connection is session-based.

Constants

DEFAULT_NEGOTIATED_VERSION

The version a legacy Streamable HTTP server assumes when a request carries no MCP-Protocol-Version header (transports §protocol-version-header).

FIRST_MODERN_VERSION

The first modern (stateless) revision — the era boundary. Any well-formed date >= this is Modern; anything earlier is Legacy.

HEADER_MISMATCH_CODE

The MCP-reserved JSON-RPC error code for a Streamable-HTTP header/body mismatch or a missing/malformed required routing header (-32020).

LATEST_LEGACY_VERSION

The latest legacy revision — what the initialize handshake advertises.

LATEST_MODERN_VERSION

The latest modern revision (advertised where the peer is known to be modern).

META_NS

The _meta key namespace carrying per-request protocol metadata in the modern era (io.modelcontextprotocol/{protocolVersion,clientInfo,clientCapabilities}).

PROTOCOL_VERSION

The version advertised in a legacy initialize handshake. Kept as the latest legacy revision: the handshake path speaks legacy until the modern (stateless) dialect is wired into the client (a later phase). A modern client declares its version per-request instead (LATEST_MODERN_VERSION).

SUPPORTED_PROTOCOL_VERSIONS

Every MCP revision this library understands, newest first (dates sort chronologically). To support a newly-released revision, add its date at the front. The head is the latest overall; era-specific latests are LATEST_MODERN_VERSION / LATEST_LEGACY_VERSION.

UNSUPPORTED_PROTOCOL_VERSION_CODE

The MCP-reserved JSON-RPC error code for an unsupported protocol version (-32022, modern negotiation).

Functions

best_mutual_version

Given a modern server’s advertised supported versions (from a -32022 error), pick the best mutually-supported one to retry with — our newest that the server also supports. None ⇒ no common version (surface to the user).

era_of

The Era a protocol version belongs to. A well-formed date >= FIRST_MODERN_VERSION (including unknown future dates) is Era::Modern; anything else is Era::Legacy (the safe default — legacy is the older, wider-deployed behavior).

is_date_version

Does s have the MCP YYYY-MM-DD version shape? (Cheap structural check, not a calendar validation — enough to tell a date revision from a bogus string.)

is_modern_error_code

Is code a JSON-RPC error code only a modern server emits? Used for era detection (versioning §backward-compatibility): a -32022 (UnsupportedProtocolVersion) or -32020 (HeaderMismatch) in the body of a failed modern probe identifies a modern server, so the client retries rather than falling back to initialize. Generic codes (e.g. -32601 method-not- found) are ambiguous across eras and are NOT modern-defining.

is_supported_version

Is v a revision this library explicitly understands?

negotiate_version

Negotiate the session version from a legacy server’s initialize response (lifecycle §version-negotiation). The server echoes our advertised version if it supports it, else returns another it supports.