René's URL Explorer Experiment

Title: Client-side 2026-07-28 support: .discover()/.adopt() + Client(mode=); request-metadata green by maxisbey · Pull Request #2950 · modelcontextprotocol/python-sdk · GitHub

Open Graph Title: Client-side 2026-07-28 support: .discover()/.adopt() + Client(mode=); request-metadata green by maxisbey · Pull Request #2950 · modelcontextprotocol/python-sdk

X Title: Client-side 2026-07-28 support: .discover()/.adopt() + Client(mode=); request-metadata green by maxisbey · Pull Request #2950 · modelcontextprotocol/python-sdk

Description: Client-side support for the 2026-07-28 per-request-envelope path: ClientSession gains .discover() and .adopt() alongside .initialize(); Client gains mode='legacy'|'auto'| 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

Open Graph Description: 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...

X Description: Client-side support for the 2026-07-28 per-request-envelope path: ClientSession gains .discover() and .adopt() alongside .initialize(); Client gains mode=&#39;legacy&#39;|&#39;auto&...

Opengraph URL: https://github.com/modelcontextprotocol/python-sdk/pull/2950

X: @github

direct link

Domain: github.com

Links:

Viewport: width=device-width