Client-side 2026-07-28 support: .discover()/.adopt() + Client(mode=); request-metadata green

Merged
MA
5mo ago
+2533-993

Client-side support for the 2026-07-28 per-request-envelope path: ClientSession gains .discover() and .adopt() alongside .initialize(); Client gains mode='legacy'|'auto'|<version-pin> and prior_discover=. Removes request-metadata and auth/authorization-server-migration from the conformance baseline, plus the carried-forward tools_call/auth/scope-step-up/auth/scope-retry-limit entries from the 2026-07-28 baseline.

Part of #2891. Touches #2894, #2892, #2900.

Motivation and Context

#2928 landed the server side of the 2026-07-28 era split. This PR is the client side: the era difference becomes which outbound-stamping closure was installed at connect time, not a flag the send path reads. ClientSession previously branched on a _stateless_pinned flag inside send_request and held the protocol version in four places (session pin, init result, transport, OAuth context); the transport sniffed InitializeResult responses to learn the version for header setting.

What changed

ClientSession — three connect-time entry points install a stamp closure.

  • .initialize() (existing) terminates by calling .adopt(result).
  • .adopt(InitializeResult | DiscoverResult) installs negotiated state without wire traffic. A DiscoverResult selects the newest mutually-supported modern version and installs the modern stamp; an InitializeResult installs the handshake stamp.
  • .discover() probes server/discover, validates the response with DiscoverResult.model_validate before reading any field, and .adopt()s on success. On -32022 it retries once with the intersection of MODERN_PROTOCOL_VERSIONS and data.supported; on -32601 or request timeout it falls back to .initialize(); anything else propagates.

send_request and send_notification call self._stamp(data, opts) unconditionally — no era branch in the body. The _stateless_pinned flag, _pinned_version slot, and the ClientSession(protocol_version=) constructor kwarg are removed.

Client — policy layer. New mode: Literal['legacy','auto'] | str = 'legacy' and prior_discover: DiscoverResult | None = None. Client.__aenter__ builds the session, then: 'legacy' → .initialize(); 'auto' → .discover(); a version string → .adopt(prior_discover or synthesize(pv)). Client(protocol_version=) is removed.

Transport pv-agnostic. StreamableHTTPTransport no longer holds protocol_version, no longer derives Mcp-Method/Mcp-Name headers, and no longer sniffs InitializeResult responses. Per-message headers arrive via CallOptions['headers'] → ClientMessageMetadata.headers → merged at the POST. The transport caches MCP-Protocol-Version from the first stamped POST for transport-internal GET/DELETE/reconnect (per-connection state, same pattern as session_id).

In-process modern path. New modern_on_request(server, lifespan_state) driver in runner.py returns an OnRequest callback that builds Connection.from_envelope per call and drives serve_one. Client(Server | MCPServer, mode != 'legacy') enters the lifespan once, creates a DirectDispatcher peer-pair, and runs the server side with this callback. The interaction suite's in-memory transport is unlocked for 2026-07-28 (71 tests now run on that arm).

Version constants. SUPPORTED_PROTOCOL_VERSIONS renamed to HANDSHAKE_PROTOCOL_VERSIONS (the versions reachable via the initialize handshake); the old name survives as a deprecated union. LATEST_PROTOCOL_VERSION bumped to "2026-07-28". The three duplicate mcp-protocol-version header constant definitions collapsed to one in shared/inbound.

report_progress routes through DispatchContext.progress(). Context.report_progress was gating on a JSONRPC-specific _meta.progressToken and reimplementing the notification path; it now delegates to ServerSession.report_progress → dctx.progress(), so progress reaches the client on the in-process modern path too.

Conformance fixture. .github/actions/conformance/client.py reads MCP_CONFORMANCE_PROTOCOL_VERSION and drives Client(mode='auto') for the modern leg, 'legacy' otherwise. New handlers for request-metadata and http-standard-headers.

How Has This Been Tested?

  • Conformance: request-metadata 7/7, auth/authorization-server-migration 27/27, http-standard-headers 3/3 on both legs; tools_call/auth/scope-step-up/auth/scope-retry-limit pass on the 2026-07-28 leg
  • ./scripts/test: 100% branch coverage, strict-no-cover clean
  • 9 unit tests cover each .discover() ladder rung; 10 interaction tests in test_client_connect.py cover the mode= policy and envelope stamping end to end
  • In-memory@2026-07-28: 71 interaction tests run, 67 pass (4 progress-on-streamable-http xfails remain scoped to that transport)

Breaking Changes

All documented in docs/migration.md:

  • ClientSession(protocol_version=) removed → use .adopt() after construction
  • Client(protocol_version=) removed → use mode=
  • StreamableHTTPTransport.protocol_version and streamable_http_client(protocol_version=) removed
  • SUPPORTED_PROTOCOL_VERSIONS deprecated → use HANDSHAKE_PROTOCOL_VERSIONS or MODERN_PROTOCOL_VERSIONS
  • LATEST_PROTOCOL_VERSION value changed "2025-11-25" → "2026-07-28"; code that meant "the version .initialize() offers" should switch to HANDSHAKE_PROTOCOL_VERSIONS[-1]
  • Client.send_progress_notification / ClientSession.send_progress_notification deprecated (client-to-server progress is server-to-client only at 2026-07-28)
  • Outbound.notify Protocol grew an opts: CallOptions | None = None parameter
  • ServerMessageMetadata.protocol_version removed (no readers)

Types of changes

  • 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

Additional context

The three stamp closures: _preconnect_stamp (cancel-suppressed only — only initialize/discover go out before connect, both forbid cancel), _make_handshake_stamp(pv) (sets the MCP-Protocol-Version header), _make_modern_stamp(pv, info, caps) (the _meta triple + cancel_on_abandon=False + all three routing headers). __init__ installs the first; .initialize()/.adopt()/.discover() install one of the other two.

The in-process modern path reuses the existing DirectDispatcher peer-pair (no new dispatcher class) — the era-specific bit is the modern_on_request callback wired into the server side, mirroring how ServerRunner.on_request is wired in for the legacy path.

http-custom-headers and http-invalid-tool-headers (the Mcp-Param-* header scenarios) and sep-2322-client-request-state (multi-round-trip results) stay waived — separate work.

AI Disclaimer