Stop negotiating modern protocol versions through the initialize handshake

[koic]

Motivation and Context

Follow-up to #512 (comment)

A comment on #512 reported that results stay unstamped when a client negotiates 2026-07-28 through the legacy initialize handshake: the SEP-2322 resultType stamp and the SEP-2549 cache hints are both gated on the per-request _meta envelope, which such a connection never carries, so strictly validating clients reject every result as missing the REQUIRED resultType.

The root cause sits upstream of the stamp. Per the SEP-2575 era model, an era is a property of the protocol version itself: legacy versions establish a session via initialize (2025-11-25 and earlier), and modern versions carry their version on every request in _meta with no handshake at all - the 2026-07-28 schema defines no initialize, and a request without the envelope is malformed. The negotiation list of this server still contained 2026-07-28, producing a hybrid state the spec does not define and the reference SDKs refuse to construct: the TypeScript server negotiates from SUPPORTED_PROTOCOL_VERSIONS, which stops at 2025-11-25, and counter-offers its first entry; the Python server negotiates from HANDSHAKE_PROTOCOL_VERSIONS, which stops there too, and counter-offers LATEST_HANDSHAKE_VERSION.

initialize now negotiates from a new SUPPORTED_HANDSHAKE_PROTOCOL_VERSIONS list (2025-11-25 and earlier): a request for 2026-07-28, or for a version this server does not know, is counter-offered 2025-11-25, exactly as both reference SDKs answer. A counter-offered client proceeds on 2025-11-25, where resultType does not exist and its absence is the correct shape, resolving the reported rejection. 2026-07-28 stays reachable through server/discover and the per-request envelope, where the stamps already apply. The envelope && stamp gates are intentionally unchanged: with the handshake capped, an envelope-less 2026-07-28 connection is no longer constructible, so the gates are correct by construction.

The client side is symmetrized the same way, matching both reference SDKs: the legacy handshake offers LATEST_HANDSHAKE_PROTOCOL_VERSION by default, passing an explicitly modern protocol_version to the legacy connect raises ArgumentError (validated before the stdio transport spawns its child process), and a server answering initialize with a modern version is rejected like an unknown one. :auto forwards an explicitly modern version to the discovery probe and never downgrades it into the legacy fallback: the probe's failure is the real answer and propagates, instead of the fallback dying on the handshake guard. The handshake rule itself lives in one place (Configuration.reject_modern_handshake_version!), and the handshake list is derived from the stable and modern lists so the era partition cannot drift when the next revision lands.

Two consequences are worth naming. The roots/sampling deprecation warnings move to the modern connect on the client, the revision where SEP-2577 actually deprecates them, since the handshake can no longer land on a deprecating version and the call site the warnings used to sit on had become unreachable. On the server the answer is removal: Configuration#protocol_version scopes the handshake, so it now accepts handshake versions only and rejects a modern pin with ArgumentError at construction. Accepting one would configure nothing (a modern version has no handshake to pin), and neither reference SDK carries a config value that is accepted but inert: Python's negotiation has no knob at all, and every entry of the TypeScript server's supportedProtocolVersions is consumed by its own era's mechanism. With no path left onto a deprecating revision, the server-side deprecation warning plumbing became unreachable and is removed along with it. Keying those warnings on a modern-era session instead was tried and rejected, because notify_log_message is the SEP-2575 sanctioned delivery path on that wire and every log line would then carry a deprecation warning for doing exactly what the revision prescribes (a single test file produced over a thousand of them).

A session-bound request may still stamp MCP-Protocol-Version: 2026-07-28 after being counter-offered, and such a request continues to be served at the negotiated revision rather than rejected. Sending the negotiated version is a SHOULD on the client, and the spec's 400 Bad Request rule covers a version the server does not support, which is not the case here: this server does serve 2026-07-28, through the other lifecycle. The session it is bound to decides, and a test now pins that reading along with its consequence, which is that no resultType appears on those results.

Two details follow from the pin being handshake-scoped. Reading it back when nothing is set now answers LATEST_HANDSHAKE_PROTOCOL_VERSION rather than the newest version of any era, so the getter no longer hands out a value its own writer rejects and round-tripping the setting keeps working; only Server#validate! reads that default, through three comparisons that answer the same for either value, so nothing else moves. And the rejection names its reason instead of listing the accepted versions, because this is the error an upgrade from a release that accepted the value lands on, which makes it the migration note a bare list would not be.

MCP::ProtocolDeprecations says in its own documentation that only the client emits these warnings now, and that LOGGING_MESSAGE has no caller left. It stays public and callable: removing it would be a breaking change for no gain.

The handshake examples in docs/building-clients.md and the shared initialize_params test helper now use the handshake version as well, and the README section on protocol_version describes the pin as handshake-scoped: handshake versions only, ArgumentError for a modern one, the handshake version as the default, and 2026-07-28 reached through server/discover with no configuration needed.

How Has This Been Tested?

New regression tests pin the reported scenario end to end: an initialize requesting 2026-07-28 is counter-offered 2025-11-25, locks the legacy era, and subsequent results carry no resultType (the correct shape at that revision). Client-side tests cover the default 2025-11-25 offer, the ArgumentError for an explicitly modern version on the legacy connect (asserting no child process is spawned on the stdio transport), the rejection of a modern InitializeResult on both transports, the :auto probe failure propagating for an explicitly modern version instead of falling back, and the deprecation warning firing on modern connects declaring roots/sampling capabilities.

Counter-offer adoption gets its own test on both transports, since the server-side fix only resolves anything for clients that honor a counter-offer, and this client is one of them: the offer is the latest handshake version, the answer is an older one, and the connection speaks the answer afterwards (over HTTP the next request's MCP-Protocol-Version header carries it). The existing tests could not tell adoption from an echo, because every one of them had the server answer with the version the client had just offered. Both new tests were confirmed to fail when the client is made to report its own offer instead.

Tests that pinned the previous dual-lifecycle negotiation were inverted or reworked: the server tests asserting 2026-07-28 echoes and fallbacks now assert the counter-offer, and the deprecation warning tests keyed on a legacy-negotiated 2026-07-28 now assert no warning fires. The server-side deprecation tests that reached their state by calling mark_initialized! with a modern version, or by pinning one in Configuration, were replaced by tests asserting no warning fires on those paths, since no code path can produce the warning state any more; Configuration rejecting a modern pin has its own tests on the constructor and the setter, asserting the reason in the message rather than the list of accepted values.

The default-pin test now also round-trips what it reads back into a fresh Configuration, which is what the old default could not do. The default move was checked for neutrality outside the suite as well, by building a server that uses every feature Server#validate! gates on that value (description, title, website_url, instructions, a $ref input schema, and tool annotations) and confirming all of them are still accepted.

Breaking Changes

Servers no longer echo 2026-07-28 from initialize: clients that negotiated it through the handshake are counter-offered 2025-11-25 and are served at that revision, matching the TypeScript and Python servers. Configuration.new(protocol_version: "2026-07-28") now raises ArgumentError (the pin scopes the handshake, which cannot land there); the value was only accepted since v1.1.0, whose handshake behavior this change replaces anyway. Reading Configuration#protocol_version with no pin set answers 2025-11-25 instead of 2026-07-28; nothing in this SDK behaves differently for either value, but code comparing that reader against a literal will see the change. The client no longer offers modern versions on the legacy handshake and rejects a modern InitializeResult. Server-side deprecation warnings for SEP-2577 features no longer fire at all, because no negotiation or configuration path can put a connection on a deprecating revision; the client-side warning on a modern connect replaces them.

Types of changes

• Bug fix (non-breaking change which fixes an issue)
• New feature (non-breaking change which adds functionality)
• Breaking change (fix or feature that would cause existing functionality to change)
• Documentation update

Checklist

• I have read the MCP Documentation
• My code follows the repository's style guidelines
• New and existing tests pass locally
• I have added appropriate error handling
• I have added or updated documentation as needed