Client-side 2026-07-28 support: .discover()/.adopt() + Client(mode=); request-metadata green
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. ADiscoverResultselects the newest mutually-supported modern version and installs the modern stamp; anInitializeResultinstalls the handshake stamp..discover()probesserver/discover, validates the response withDiscoverResult.model_validatebefore reading any field, and.adopt()s on success. On-32022it retries once with the intersection ofMODERN_PROTOCOL_VERSIONSanddata.supported; on-32601or 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-metadata7/7,auth/authorization-server-migration27/27,http-standard-headers3/3 on both legs;tools_call/auth/scope-step-up/auth/scope-retry-limitpass on the 2026-07-28 leg ./scripts/test: 100% branch coverage,strict-no-coverclean- 9 unit tests cover each
.discover()ladder rung; 10 interaction tests intest_client_connect.pycover themode=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 constructionClient(protocol_version=)removed → usemode=StreamableHTTPTransport.protocol_versionandstreamable_http_client(protocol_version=)removedSUPPORTED_PROTOCOL_VERSIONSdeprecated → useHANDSHAKE_PROTOCOL_VERSIONSorMODERN_PROTOCOL_VERSIONSLATEST_PROTOCOL_VERSIONvalue changed"2025-11-25"→"2026-07-28"; code that meant "the version.initialize()offers" should switch toHANDSHAKE_PROTOCOL_VERSIONS[-1]Client.send_progress_notification/ClientSession.send_progress_notificationdeprecated (client-to-server progress is server-to-client only at 2026-07-28)Outbound.notifyProtocol grew anopts: CallOptions | None = NoneparameterServerMessageMetadata.protocol_versionremoved (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.