Merge remote-tracking branch 'origin/main' into perf/cache-tool-output-schema-validators

# Conflicts:
#	src/mcp/client/session.py

Author: maxisbey

.github/actions/conformance/expected-failures.yml

@@ -10,7 +10,24 @@
 # scenarios start passing and MUST be removed from this list (the runner fails
 # on stale entries), so the baseline burns down per milestone.
 
-client: []
+client:
+  # SEP-1932 (DPoP): the SDK's OAuth client does not implement DPoP proofs.
+  # These scenarios are new in the da56f663 referee pin. The entries are
+  # per-check (conformance #406) because both scenarios pass their
+  # non-DPoP checks (discovery, token acquisition, request flow) live.
+  - auth/dpop:sep-1932-client-token-request-proof
+  - auth/dpop:sep-1932-client-dpop-auth-scheme
+  - auth/dpop:sep-1932-client-fresh-proof
+  - auth/dpop-nonce:sep-1932-client-token-request-proof
+  - auth/dpop-nonce:sep-1932-client-dpop-auth-scheme
+  - auth/dpop-nonce:sep-1932-client-fresh-proof
+  - auth/dpop-nonce:sep-1932-client-as-nonce
+  - auth/dpop-nonce:sep-1932-client-rs-nonce
+  # Workload identity federation: the OAuth client does not implement the
+  # urn:ietf:params:oauth:grant-type:jwt-bearer grant (it answers with
+  # authorization_code). Also new in the da56f663 referee pin; per-check for
+  # the same reason.
+  - auth/wif-jwt-bearer:wif-grant-type
 
 server:
   # SEP-2663 (io.modelcontextprotocol/tasks): the SDK does not implement the

.github/workflows/conformance.yml

@@ -19,17 +19,19 @@ env:
   # Bump deliberately and reconcile both
   # .github/actions/conformance/expected-failures*.yml files in the same change.
   #
-  # Temporarily pinned to the pkg.pr.new build of conformance main@4944b268
-  # (0.2.0-alpha.8, which includes #372: fail checks whose prerequisite is
-  # missing instead of skipping them) — alpha.8 is not published to npm yet.
-  # Pinned by commit SHA so the tarball cannot move under us;
+  # Temporarily pinned to the pkg.pr.new build of conformance main@da56f663,
+  # which includes #403 (sep-2575 checks flipped to the post-spec-#3002 shape:
+  # clientInfo optional on requests, serverInfo in result _meta instead of the
+  # discover body) and #406 (per-check expected-failures granularity) — the
+  # last published npm release (0.2.0-alpha.9) still enforces the pre-#3002
+  # shape. Pinned by commit SHA so the tarball cannot move under us;
   # CONFORMANCE_PKG_SHA256 pins the bytes and the fetch-and-verify step below
   # downloads, checks the digest, and repoints CONFORMANCE_PKG at the
   # verified local copy. Repin to the next published @modelcontextprotocol/
-  # conformance release (>=0.2.0-alpha.8) once it ships, then drop
+  # conformance release (>=0.2.0-alpha.10) once it ships, then drop
   # CONFORMANCE_PKG_SHA256 and the fetch-and-verify steps.
-  CONFORMANCE_PKG: "https://pkg.pr.new/@modelcontextprotocol/conformance@4944b268"
-  CONFORMANCE_PKG_SHA256: "0f70c035782d319d72ab427653c5275db5c50429d59fae0241a645b33aeda1a7"
+  CONFORMANCE_PKG: "https://pkg.pr.new/@modelcontextprotocol/conformance@da56f663"
+  CONFORMANCE_PKG_SHA256: "bbc94678033071df4bc9851ce2054f9dff918f4501661d1d60e2d09d8c515e6d"
 
 jobs:
   server-conformance:

README.md

@@ -18,7 +18,7 @@
 >
 > **v1.x is the only stable release line and remains recommended for production.** It lives on the [`v1.x` branch](https://github.com/modelcontextprotocol/python-sdk/tree/v1.x) and continues to receive critical bug fixes and security patches; see [the v1.x README](https://github.com/modelcontextprotocol/python-sdk/blob/v1.x/README.md) for its documentation. `pip` and `uv` don't select a pre-release unless you explicitly request one, so existing installs are unaffected. **If your package depends on `mcp`, add a `<2` upper bound to your version constraint (for example `mcp>=1.27,<2`) before the stable release lands.**
 >
-> v2 is a major rework of the SDK, both to support the [2026-07-28 MCP specification release](https://blog.modelcontextprotocol.io/posts/2026-07-28-release-candidate/) and to fix long-standing architectural issues. See [What's new in v2](https://py.sdk.modelcontextprotocol.io/v2/whats-new/) for the tour of what changed, and the [migration guide](https://py.sdk.modelcontextprotocol.io/v2/migration/) for every breaking change. Stable v2 is targeted for 2026-07-27, alongside the spec release. Try the pre-releases and [tell us what breaks](https://github.com/modelcontextprotocol/python-sdk/issues/new?template=v2-feedback.yaml), or discuss in [#python-sdk-dev on the MCP Contributors Discord](https://discord.gg/6CSzBmMkjX).
+> v2 is a major rework of the SDK, both to support the [2026-07-28 MCP specification release](https://blog.modelcontextprotocol.io/posts/2026-07-28-release-candidate/) and to fix long-standing architectural issues. See [What's new in v2](https://py.sdk.modelcontextprotocol.io/v2/whats-new/) for the tour of what changed, and the [migration guide](https://py.sdk.modelcontextprotocol.io/v2/migration/) for every breaking change. Stable v2 is targeted for 2026-07-28, alongside the spec release. Try the pre-releases and [tell us what breaks](https://github.com/modelcontextprotocol/python-sdk/issues/new?template=v2-feedback.yaml), or discuss in [#python-sdk-dev on the MCP Contributors Discord](https://discord.gg/6CSzBmMkjX).
 
 ## Documentation
 

docs/advanced/extensions.md

@@ -133,14 +133,21 @@ or veto a tool call:
 ```
 
 * `params` is the validated `CallToolRequestParams`: you get `params.name` and
-  `params.arguments` without touching raw JSON.
-* `call_next(ctx)` runs the rest of the chain. Return its result unchanged (observe),
-  return something else (replace), or raise an `MCPError` (refuse).
+  `params.arguments` without touching raw JSON. It is also what decides which
+  tool call runs: passing a rewritten context through `call_next` changes what
+  the handler observes on `ctx`, not the tool invocation. Wire-level request
+  rewriting belongs to [Middleware](middleware.md).
+* `call_next(ctx)` runs the rest of the chain and returns the handler's result.
+  Return it unchanged (observe), return something else (replace), or raise an
+  `MCPError` (refuse). Whatever you return is serialized like any handler
+  result, including the 2026-era `serverInfo` identity stamp, so a
+  short-circuiting interceptor never produces an anonymous or off-schema
+  response.
 * With several extensions, interceptors nest in registration order: the first
   extension in `extensions=[...]` is outermost.
 * The default implementation is a pass-through, and a server whose extensions never
-  override this hook installs **no** middleware at all. You don't pay for what
-  you don't use.
+  override this hook keeps the bare `tools/call` handler untouched. You don't
+  pay for what you don't use.
 
 The hook wraps `tools/call` and nothing else. For every-message concerns, use
 [Middleware](middleware.md). That is what it is for.

docs/advanced/low-level-server.md

@@ -102,10 +102,13 @@ Call it and the result carries both representations:
   "content": [{"type": "text", "text": "Found 3 books matching 'dune'."}],
   "structuredContent": {"matches": 3, "query": "dune"},
   "isError": false,
-  "resultType": "complete"
+  "resultType": "complete",
+  "_meta": {"io.modelcontextprotocol/serverInfo": {"name": "Bookshop", "version": "2.0.0"}}
 }
 ```
 
+The `_meta` block is the server's identity stamp: the SDK adds it to every 2026-era result, with the `version` from the constructor (a server that sets none reports an empty string). A server that must not identify itself can strip the key with a middleware, which owns the results it returns.
+
 The server never compares the two fields. This SDK's `Client` does: return `structured_content` that doesn't satisfy the `output_schema` you declared and `call_tool` raises a `RuntimeError` that starts with `Invalid structured content returned by tool search_books` and goes on to quote the `jsonschema` failure. Promising a schema is cheap; keeping it is on you. The whole ladder of return types and schemas is in **[Structured Output](../servers/structured-output.md)**.
 
 ## `_meta`: for the application, not the model

docs/advanced/middleware.md

@@ -63,6 +63,10 @@ In increasing order of how much you should hesitate:
   `initialize`: the result the client gets back is built from your rewritten params, but the
   server commits its connection state from the original wire params. The two sides can finish
   the handshake disagreeing about what they negotiated.
+* **Answer.** Return a result without calling `call_next(ctx)` and it goes to the client as
+  your response. `call_next` hands you the finished wire form, and the pipeline never patches
+  what you return, so the whole envelope is yours: on a 2026-era connection that includes the
+  `serverInfo` `_meta` stamp, which the SDK adds to handler results but not to yours.
 
 !!! check
     `initialize` is one of the things middleware wraps, and it is the *only* hook you get

docs/client/caching.md

@@ -51,7 +51,7 @@ Four calls, three fetches. The second call found a fresh entry and never reached
 
 One rule sits above `"use"`: **calls carrying `meta` always reach the server.** A request with `meta` set (a progress token, tracing fields) expects a wire request, so under `cache_mode="use"` it is treated as `"refresh"`: the cache read is skipped, and the fetched result still replaces the cached entry. `"bypass"` and an explicit `"refresh"` behave as they always do.
 
-To turn caching off entirely, construct with `Client(server, cache=False)`: every call is a round trip again, and `cache_mode`, while still accepted, does nothing.
+To turn caching off entirely, construct with `Client(server, cache=None)`: every call is a round trip again, and `cache_mode`, while still accepted, does nothing.
 
 Scope is honored automatically too: `"private"` entries are keyed to the cache's *partition* (below), while `"public"` ones may opt into wider sharing. And **notifications beat TTL** for the exact entries they name: a `list_changed` notification evicts the matching cached listing, and `resources/updated` evicts the cached read stored under exactly its URI, however fresh they were. On a 2026-07-28 connection those notifications arrive on a `subscriptions/listen` stream you open with `client.listen(...)`, and eviction completes before your watcher sees the event; **[Subscriptions](subscriptions.md)** is that page.
 
@@ -114,4 +114,4 @@ Clients on pre-2026 protocol versions never see either field; the SDK strips the
 * A handler that sets the fields on its result overrides the map, per field.
 * `"public"` is a promise that the result is identical for every caller. It is not access control.
 * `Client` honors the hints automatically: its response cache is on by default, serves fresh entries instead of refetching, and caches nothing for servers (or sessions) that provide no hints.
-* Per call, `cache_mode="refresh"` refetches and `"bypass"` skips the cache; `cache=False` at construction turns it off entirely.
+* Per call, `cache_mode="refresh"` refetches and `"bypass"` skips the cache; `cache=None` at construction turns it off entirely.

docs/client/callbacks.md

@@ -135,7 +135,7 @@ Two more. Neither declares anything.
 
 `logging_callback` receives every `notifications/message` a server sends, as `LoggingMessageNotificationParams` (`level`, `logger`, `data`). Protocol logging is itself deprecated by the 2026-07-28 spec (**[Logging](../handlers/logging.md)** has what to do instead), so this callback exists for the servers that still emit it.
 
-`message_handler` is the catch-all: every server notification reaches it (as well as its specific callback), and on a stream-backed transport so does every transport-level `Exception`. The one pattern worth knowing is `if isinstance(message, Exception): raise message`, so a broken connection fails loudly instead of vanishing.
+`message_handler` is the catch-all: every server notification the session surfaces reaches it (as well as its specific callback), and on a stream-backed transport so does every transport-level `Exception`. Two never do: `notifications/cancelled` is applied by the SDK rather than surfaced, and a subscription acknowledgment for a live `listen()` stream is consumed by that stream. Annotate the parameter with `IncomingMessage` (`ServerNotification | Exception`, exported from `mcp.client`). The one pattern worth knowing is `if isinstance(message, Exception): raise message`, so a broken connection fails loudly instead of vanishing.
 
 ## Recap
 

docs/client/index.md

@@ -30,7 +30,7 @@ Everything else on this page is identical across all three. Headers, subprocesse
 
 Four read-only properties, populated the moment you enter the block:
 
-* `client.server_info`: the server's identity. `server_info.name` here is `"Bookshop"`, `server_info.version` is whatever the server reports.
+* `client.server_info`: the server's identity, or `None` for a 2026-era server that does not report one (python-sdk servers do by default). `server_info.name` here is `"Bookshop"`, `server_info.version` is whatever the server reports.
 * `client.server_capabilities`: what the server can do (`tools`, `resources`, `prompts`, `completions`, ...). A capability the server doesn't have is `None`.
 * `client.protocol_version`: the protocol version the two sides agreed on. Here it is `"2026-07-28"`.
 * `client.instructions`: the server's `instructions=` string, or `None` if it didn't set one.
@@ -202,7 +202,7 @@ There is one constructor flag built for that: `Client(mcp, raise_exceptions=True
 ## Recap
 
 * `Client(x)` connects in-memory to a server object, over Streamable HTTP to a URL string, and over anything else via a transport.
-* `async with` is the whole lifecycle. Inside it, `server_info`, `server_capabilities`, `protocol_version` and `instructions` are already populated.
+* `async with` is the whole lifecycle. Inside it, `server_capabilities` and `protocol_version` are already populated; `server_info` and `instructions` are too when the server provides them.
 * `list_tools()` gives you each tool's `name`, `title`, `description` and `input_schema`.
 * `call_tool()` returns `content` for the model, `structured_content` for your code, and `is_error`. A raising tool is a result, not an exception.
 * `content` is a union of block types; narrow with `isinstance` before reading.

docs/client/oauth-clients.md

@@ -83,7 +83,7 @@ The first time `Client` sends a request, the server answers `401`. The provider
 
 After that it is quiet. Tokens come out of storage, an expired access token is refreshed with the refresh token, and only when none of that works does it run the flow again.
 
-You wrote none of it. Three keyword arguments remain (`timeout`, `client_metadata_url` and `validate_resource_url`), and this file needs none of them. `client_metadata_url` is the one worth knowing about; it gets its own section below.
+You wrote none of it. Two keyword arguments remain (`client_metadata_url` and `validate_resource_url`), and this file needs neither. `client_metadata_url` is the one worth knowing about; it gets its own section below.
 
 ### Try it
 
@@ -112,7 +112,7 @@ A nightly job, a CI step, another service. There is no browser and nobody to cli
 What changed:
 
 * No `OAuthClientMetadata`, no handlers. You pass `client_id` and `client_secret`; the provider builds a minimal `client_credentials` registration around them and skips dynamic registration entirely.
-* `scopes` is a space-separated string, the OAuth wire format.
+* `scope` is a space-separated string, the OAuth wire format.
 * Everything downstream is identical: the same `TokenStorage`, the same `httpx2.AsyncClient(auth=...)`, the same `streamable_http_client`.
 
 By default the secret travels as HTTP Basic auth on the token request (`client_secret_basic`). Pass `token_endpoint_auth_method="client_secret_post"` to put it in the form body instead. Some authorization servers only accept one of the two.