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

[maxisbey]

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}

[claude]

🟡 This PR removes the module-level MCP_PROTOCOL_VERSION = 'mcp-protocol-version' constant from mcp.client.streamable_http (it now lives as MCP_PROTOCOL_VERSION_HEADER in mcp.shared.inbound), but unlike the other v1→v2 breaks in this PR the removal isn't covered in docs/migration.md and no deprecated alias is left, so external code importing it from the old location gets an ImportError. The constant exists on v1.x and was imported cross-module by the SDK's own auth code until this PR, so a one-line migration.md note (or a deprecated re-export) for MCP_PROTOCOL_VERSION would close the gap; MCP_METHOD/MCP_NAME were never on v1.x and need no note.

Extended reasoning...

What changed

The diff for src/mcp/client/streamable_http.py deletes the module-level constants MCP_PROTOCOL_VERSION = 'mcp-protocol-version', MCP_METHOD, and MCP_NAME. Their replacements (MCP_PROTOCOL_VERSION_HEADER, MCP_METHOD_HEADER, MCP_NAME_HEADER) live in mcp.shared.inbound, and no alias is left behind in the old module. Of these, only MCP_PROTOCOL_VERSION is a v1→v2 break: it is defined at module level in the v1.x streamable_http.py (alongside MCP_SESSION_ID and LAST_EVENT_ID, which both survive this PR), whereas MCP_METHOD/MCP_NAME were added on main during the v2 cycle and never shipped on v1.x — so per the stated migration.md scope (v1→v2 only), only the protocol-version constant needs documenting.

Why this is plausibly user-visible

The SDK's own code treated this as a cross-module symbol until this very PR: src/mcp/client/auth/oauth2.py and src/mcp/client/auth/utils.py both did from mcp.client.streamable_http import MCP_PROTOCOL_VERSION and are repointed to mcp.shared.inbound.MCP_PROTOCOL_VERSION_HEADER in this diff. External code that sets or reads the MCP-Protocol-Version header manually (custom auth flows, middleware, raw httpx wrappers) plausibly imports it from the same place. After this PR that import raises ImportError with no migration breadcrumb.

Step-by-step

1. A v1.x user has from mcp.client.streamable_http import MCP_PROTOCOL_VERSION (the same import the SDK's auth code used).
2. They upgrade to v2 with this PR merged. The name no longer exists in mcp.client.streamable_http — ImportError: cannot import name 'MCP_PROTOCOL_VERSION'.
3. They check docs/migration.md. The new sections added by this PR cover the StreamableHTTPTransport.protocol_version attribute removal and the SUPPORTED_PROTOCOL_VERSIONS/LATEST_PROTOCOL_VERSION changes, but say nothing about the header-name constant or where it moved (mcp.shared.inbound.MCP_PROTOCOL_VERSION_HEADER).

Why existing docs/code don't cover it

AGENTS.md requires breaking changes — including ones softened by a shim — to be documented in docs/migration.md, and this PR already follows that rule for the closely-related StreamableHTTPTransport.protocol_version attribute (documented precisely because it existed on v1.x). The same criterion applies to this constant, but the entry was not added, and there is no deprecated alias to soften the break either.

Impact and fix

Impact is small: the constant is a plain header-name string that is trivially reconstructable, it isn't exported via mcp.__init__, and most users never import it directly — hence nit, not blocking. The fix is a one-line addition to the migration guide (e.g. under the streamable-HTTP section: "MCP_PROTOCOL_VERSION constant moved — import MCP_PROTOCOL_VERSION_HEADER from mcp.shared.inbound instead"), or alternatively a deprecated re-export alias in mcp.client.streamable_http. MCP_METHOD/MCP_NAME need neither, since they never existed on v1.x.

[claude]

🟡 Every request stamped before initialize()/discover()/adopt() now gets cancel_on_abandon=False from _preconnect_stamp, so a lowlevel ClientSession user who skips the handshake (a pattern this PR's migration.md explicitly preserves) silently loses the courtesy notifications/cancelled when a request times out or is abandoned — pre-PR only initialize was suppressed. Consider gating the suppression on the method (initialize/server/discover) inside _preconnect_stamp instead of suppressing unconditionally.

Extended reasoning...

What the bug is

ClientSession.__init__ installs _preconnect_stamp as the default outbound stamp (src/mcp/client/session.py:54-56), and that closure unconditionally sets opts['cancel_on_abandon'] = False for every request and notification stamped before one of initialize(), discover(), or adopt() swaps it out. The comment in the closure — "Only initialize/discover go out before connect; both forbid cancellation" — is true for the high-level Client (which always handshakes in __aenter__), but it is not true for the lowlevel ClientSession, which still allows feature methods to be called without any handshake. This PR's own docs/migration.md addition says so explicitly: "(The lowlevel ClientSession still lets you call methods before any handshake, as in v1; …)", and the author re-affirms the skip-init path "works exactly as in v1" in the review thread (the 2025 unofficial-stateless-server pattern).

The code path

In jsonrpc_dispatcher.py, _plan_outbound reads cancel_on_abandon and gates the courtesy notifications/cancelled on both abandonment paths — when the per-request timeout fires and when the caller's scope is cancelled while the request is in flight. Pre-PR, send_request only set cancel_on_abandon=False for method == 'initialize' (and the now-removed stateless pin), so any other request abandoned by timeout or caller cancellation emitted the spec-recommended courtesy cancel. Post-PR, the suppression applies to every pre-handshake request, because the stamp is method-blind.

Step-by-step proof

1. A lowlevel user constructs ClientSession(read, write) against a 2025-era server that doesn't require the handshake (the documented skip-init pattern) and never calls initialize()/discover()/adopt(). self._stamp remains _preconnect_stamp.
2. They call session.call_tool('slow_tool', {...}, read_timeout_seconds=5). send_request builds opts = {} and calls self._stamp(data, opts), which sets opts['cancel_on_abandon'] = False.
3. The tool takes longer than 5 s. The dispatcher's timeout path consults plan.cancel_on_abandon, finds it False, and does not send notifications/cancelled.
4. On main (pre-PR), the same sequence sends notifications/cancelled, letting the server stop the abandoned work. The dispatcher's own docstring notes that a request that is neither resumable nor cancelled "would leak the peer's work" — which is exactly what now happens.

Why nothing else prevents it

The stamp is only replaced by the three connect-time entry points; a session that never connects keeps _preconnect_stamp for its whole lifetime. No other layer re-enables cancel_on_abandon, and no test covers an abandoned pre-handshake feature request, so the regression is silent.

Impact and fix

The impact is narrow: it requires the lowlevel skip-handshake pattern and an abandoned/timed-out request, the dropped notification is a best-effort courtesy (a SHOULD, not a MUST), and the client-side outcome is unchanged — hence a nit rather than a blocker. But it is an unintended wire-behavior change for a path the PR documents as unchanged from v1. The fix is one line: gate the suppression on the method inside _preconnect_stamp, e.g.

def _preconnect_stamp(data: dict[str, Any], opts: CallOptions) -> None:
    # initialize/discover forbid cancellation; other pre-handshake requests keep the courtesy cancel.
    if data["method"] in ("initialize", "server/discover"):
        opts["cancel_on_abandon"] = False

[claude]

🟡 The new send_discover() docstring's Raises section lists ProbeNotRecognized, but no exception class with that name exists anywhere in the codebase — a caller writing except ProbeNotRecognized would get a NameError. In reality a bare HTTP 4xx is synthesized into a JSONRPCError by the streamable-HTTP transport (e.g. the new pre-session 404 → METHOD_NOT_FOUND mapping) and surfaces as MCPError, which is already covered by the first Raises entry; drop this entry or describe the actual MCPError code used for transport-level rejections.

Extended reasoning...

What the bug is

The Raises: section of the new ClientSession.send_discover() docstring (src/mcp/client/session.py:404-407) documents two exception types:

Raises:
    MCPError: The server returned a JSON-RPC error.
    ProbeNotRecognized: The transport bounced the request at its own
        layer (HTTP 4xx without a JSON-RPC error body).

ProbeNotRecognized does not exist. A repo-wide grep finds exactly one occurrence of the name — this docstring line. There is no class definition, import, export, or raise of any such exception in src/ or tests/; mcp.shared.exceptions defines only MCPError, NoBackChannelError, and UrlElicitationRequiredError.

What actually happens on a transport-level 4xx

When the server/discover probe is bounced at the HTTP layer without a JSON-RPC error body, the streamable-HTTP transport synthesizes a JSONRPCError itself: _handle_post_request in src/mcp/client/streamable_http.py maps a pre-session bare 404 to METHOD_NOT_FOUND (the new mapping added in this PR) and other non-2xx statuses to INTERNAL_ERROR. That synthesized error flows through JSONRPCDispatcher, which raises it to the caller as MCPError. So the second Raises entry is both fictitious (the class doesn't exist) and redundant (the behavior it describes is already covered by the first entry, MCPError).

Step-by-step proof

1. A caller follows the docstring and writes:

   try:
       raw = await session.send_discover("2026-07-28")
   except ProbeNotRecognized:
       ...

2. There is nothing to import — from mcp.shared.exceptions import ProbeNotRecognized raises ImportError, and an unqualified reference raises NameError: name 'ProbeNotRecognized' is not defined the first time the except clause is evaluated.
3. Meanwhile, the actual transport-level 4xx case (e.g. a gateway 404 with no JSON-RPC body) arrives at the caller as MCPError(METHOD_NOT_FOUND), which the caller's handler — written per the docstring — does not catch as intended.

Why this matters / impact

This is a documentation-only defect introduced by this PR (the docstring is new in this diff and survived the follow-up commits through HEAD a7d1275). It has no runtime impact on the SDK itself, but send_discover() is a public method on ClientSession, and the project's convention (per the review thread, Raises sections were added at the reviewer's request) is that public-method docstrings list the exceptions a caller would reasonably catch — documenting a class that doesn't exist actively misleads.

How to fix

Either drop the second Raises entry (the first MCPError line already covers all failure modes), or fold the transport-level detail into it, e.g.:

Raises:
    MCPError: The server returned a JSON-RPC error, or the transport bounced
        the request at its own layer (a bare HTTP 4xx is synthesized into a
        JSON-RPC error — pre-session 404 maps to METHOD_NOT_FOUND).

[maxisbey]

why do we need to synthesize discover? we should probably just handle the case properly.

like there's two distinct states:

• calling a tool without first calling discover
• first calling discover and then calling tool

but if we synthesize discover then the ClientSession will think it has called discover yet it hasn't, need to think about the implications to client represation here

[maxisbey]

why not use the actual types here?

[Kludex]

call it options: please