Merge branch 'main' into shttp-native-dispatch

Brings in "Stop answering cancelled requests" and reapplies its policy
onto the rebuilt seam instead of the code it targeted:

- The cancelled-request answer policy now lives at the correlator's
  single site: a peer-cancelled request is never answered by the dispatch
  layer, its late result or error is dropped, and it settles through a
  transport-supplied hook. The dispatcher forwards the hook it receives in
  message metadata; the streamable HTTP transport supplies its own, which
  ends the request's stream with the REQUEST_CANCELLED terminal error
  written through the request's ordered channel (so a resuming client's
  replay terminates too).
- Hook containment happens once, in the correlator.

Author: maxisbey

.github/workflows/shared.yml

@@ -51,7 +51,7 @@ jobs:
       - name: mcp-types installs and imports standalone
         run: |
           uv run --isolated --no-project --with ./src/mcp-types python -c \
-            "import mcp_types, mcp_types.jsonrpc, mcp_types.methods, mcp_types.version, mcp_types.v2025_11_25, mcp_types.v2026_07_28"
+            "import mcp_types, mcp_types.jsonrpc, mcp_types.methods, mcp_types.version, mcp_types._v2025_11_25, mcp_types._v2026_07_28"
 
   test:
     name: test (${{ matrix.python-version }}, ${{ matrix.dep-resolution.name }}, ${{ matrix.os }})

docs/advanced/apps.md

@@ -20,7 +20,7 @@ then come back.
 
 ## A clock with a face
 
-```python title="server.py" hl_lines="18 21 29 31"
+```python title="server.py" hl_lines="19 22 30 32"
 --8<-- "docs_src/apps/tutorial001.py"
 ```
 
@@ -51,7 +51,7 @@ The model reads `content`; the iframe is for humans. A UI-capable host still fee
 the text result to the model, and a text-only client gets *only* that. So the
 canonical pattern is one tool, two answers. Look at `get_time` again:
 
-```python title="server.py" hl_lines="22-26"
+```python title="server.py" hl_lines="23-27"
 --8<-- "docs_src/apps/tutorial001.py"
 ```
 

docs/advanced/extensions.md

@@ -128,7 +128,7 @@ The same file's `main()` is the whole client story, both halves of it:
 The one interceptive hook. Override `intercept_tool_call` to observe, short-circuit,
 or veto a tool call:
 
-```python title="server.py" hl_lines="18-25"
+```python title="server.py" hl_lines="17-24"
 --8<-- "docs_src/extensions/tutorial005.py"
 ```
 
@@ -158,7 +158,7 @@ A **client extension** is the same contract from the consuming side: a bundle of
 client-side behaviour behind one identifier. Pass instances to
 `Client(extensions=[...])` and call tools normally:
 
-```python title="client.py" hl_lines="67-69"
+```python title="client.py" hl_lines="66-68"
 --8<-- "docs_src/extensions/tutorial006.py"
 ```
 
@@ -188,7 +188,7 @@ client = Client(mcp, extensions=[advertise("com.example/search")])
 Subclass `ClientExtension` and override only what you need. Three contribution
 kinds, each with a default: `settings()`, `claims()`, and `notifications()`.
 
-```python title="client.py" hl_lines="18-19 44-45 47-48"
+```python title="client.py" hl_lines="17-18 43-44 46-47"
 --8<-- "docs_src/extensions/tutorial006.py"
 ```
 
@@ -226,12 +226,12 @@ claimed shape reaching a session-tier caller raises `UnexpectedClaimedResult`.
 ### Extension verbs
 
 An extension's own request methods need no client-side registration. A vendor request
-type subclasses `mcp_types.Request` and goes through `client.session.send_request`,
+type subclasses `mcp.types.Request` and goes through `client.session.send_request`,
 as in [Serving your own methods](#serving-your-own-methods). One addition: when a
 params key must ride the `Mcp-Name` header (extension specs such as tasks require
 this for their verbs), the request type declares `name_param`:
 
-```python title="client.py" hl_lines="23-26 47-48"
+```python title="client.py" hl_lines="22-25 46-47"
 --8<-- "docs_src/extensions/tutorial007.py"
 ```
 

docs/advanced/low-level-server.md

@@ -14,7 +14,7 @@ For everything else, stay on `MCPServer`.
 
 This is the `search_books` tool that **[Tools](../servers/tools.md)** writes in nine lines of `@mcp.tool()`, with the sugar removed:
 
-```python title="server.py" hl_lines="23 27 33"
+```python title="server.py" hl_lines="22 26 32"
 --8<-- "docs_src/lowlevel/tutorial001.py"
 ```
 
@@ -80,7 +80,7 @@ That generalises. An exception raised from a low-level handler is **always** a p
 
 `on_call_tool` is the single entry point for every tool on the server. You route on `params.name`:
 
-```python title="server.py" hl_lines="39-44"
+```python title="server.py" hl_lines="38-43"
 --8<-- "docs_src/lowlevel/tutorial002.py"
 ```
 
@@ -91,7 +91,7 @@ That generalises. An exception raised from a low-level handler is **always** a p
 
 Declare `output_schema` on the `Tool` and put `structured_content` on the result. Both are yours:
 
-```python title="server.py" hl_lines="20-24 37"
+```python title="server.py" hl_lines="19-23 36"
 --8<-- "docs_src/lowlevel/tutorial003.py"
 ```
 
@@ -117,7 +117,7 @@ The server never compares the two fields. This SDK's `Client` does: return `stru
 
 Use it for record IDs, trace IDs, anything your UI needs and your prompt doesn't:
 
-```python title="server.py" hl_lines="38"
+```python title="server.py" hl_lines="37"
 --8<-- "docs_src/lowlevel/tutorial004.py"
 ```
 
@@ -144,7 +144,7 @@ No `resources`, no `prompts`: there is nothing to back them. Pass `on_list_promp
 
 `Server` is generic in the type its lifespan yields. Annotate it once and the object is typed everywhere it surfaces:
 
-```python title="server.py" hl_lines="25-27 45-46 51"
+```python title="server.py" hl_lines="24-26 44-45 50"
 --8<-- "docs_src/lowlevel/tutorial005.py"
 ```
 

docs/advanced/middleware.md

@@ -16,7 +16,7 @@ If `Server(name, on_call_tool=...)` is new to you, read **[The low-level Server]
 
 One server, one tool, one middleware that logs how long each message took:
 
-```python title="server.py" hl_lines="40-46 50"
+```python title="server.py" hl_lines="39-45 49"
 --8<-- "docs_src/middleware/tutorial001.py"
 ```
 

docs/advanced/pagination.md

@@ -10,7 +10,7 @@ Pagination is for the server whose resource list is really a database: thousands
 
 ## A server that pages
 
-```python title="server.py" hl_lines="13 16-17"
+```python title="server.py" hl_lines="12 15-16"
 --8<-- "docs_src/pagination/tutorial001.py"
 ```
 
@@ -38,7 +38,7 @@ The tenth page comes back with `next_cursor` set to `None`. Done.
 
 Every `list_*` method on `Client` (`list_tools`, `list_resources`, `list_resource_templates`, `list_prompts`) takes a `cursor=` keyword. Draining a paged list is one `while True`:
 
-```python title="client.py" hl_lines="27-33"
+```python title="client.py" hl_lines="26-32"
 --8<-- "docs_src/pagination/tutorial002.py"
 ```
 

docs/client/caching.md

@@ -25,7 +25,7 @@ Out of the box every result says `ttlMs: 0, cacheScope: "private"`: immediately
 
 On the low-level `Server`, handlers build their results by hand, and `ttl_ms` / `cache_scope` are just fields on the result models. A handler that sets them explicitly always wins over the constructor map, field by field:
 
-```python title="server.py" hl_lines="11 17"
+```python title="server.py" hl_lines="10 16"
 --8<-- "docs_src/caching/tutorial002.py"
 ```
 
@@ -39,7 +39,7 @@ One caveat on paginated lists: the protocol requires the **same `cacheScope` on
 
 On a 2026-07-28 session, `Client` honors the hints for you: it has a built-in response cache, on by default. A result that arrives carrying a `ttlMs` is stored, and an identical call within that TTL is served from the cache with no round trip. A result that carries *no* hint is not cached: hint-less results get `CacheConfig.default_ttl_ms`, which defaults to `0` (immediately stale), so a server that declares nothing sees exactly the call-for-call traffic it always did.
 
-```python title="client.py" hl_lines="34 36 39"
+```python title="client.py" hl_lines="33 35 38"
 --8<-- "docs_src/caching/tutorial003.py"
 ```
 

docs/client/callbacks.md

@@ -19,7 +19,7 @@ That is the server half, and the **[Elicitation](../handlers/elicitation.md)** p
 
 ## The elicitation callback
 
-```python title="client.py" hl_lines="7-11 17-18"
+```python title="client.py" hl_lines="6-10 16-17"
 --8<-- "docs_src/client_callbacks/tutorial002.py"
 ```
 
@@ -55,7 +55,7 @@ result.content  # [TextContent(type='text', text='Card issued to Ada Lovelace.')
 One `tools/call` from you, one `elicitation/create` back from the server, answered by your function, all inside a single tool call.
 
 !!! info
-    `mode="legacy"` on line 17 is doing real work. By default `Client(...)` negotiates the modern
+    `mode="legacy"` on the `Client(...)` call is doing real work. By default `Client(...)` negotiates the modern
     protocol path, and that path has no back-channel for server-to-client requests: `ctx.elicit`
     fails before your callback ever runs. The transport doesn't decide that; the negotiated
     protocol does, in-memory and over a URL alike. Pin `mode="legacy"` whenever your client has

docs/client/index.md

@@ -135,7 +135,7 @@ A tool that raises does **not** raise in your client. It comes back as an ordina
 
 The resource verbs come in pairs: two ways to list, one way to read.
 
-```python title="client.py" hl_lines="23-32"
+```python title="client.py" hl_lines="22-31"
 --8<-- "docs_src/client/tutorial004.py"
 ```
 
@@ -174,7 +174,7 @@ A host hands those messages straight to the model. That is the whole feature.
 
 A server with a completion handler can autocomplete prompt and resource-template arguments as the user types.
 
-```python title="client.py" hl_lines="28-32"
+```python title="client.py" hl_lines="27-31"
 --8<-- "docs_src/client/tutorial006.py"
 ```
 
@@ -187,7 +187,7 @@ The answer is in `result.completion.values`. Type `"p"` and the server comes bac
 
 Every `list_*` method takes a `cursor=` keyword and every result carries a `next_cursor`. When `next_cursor` is `None`, you have everything.
 
-```python title="client.py" hl_lines="23-31"
+```python title="client.py" hl_lines="22-30"
 --8<-- "docs_src/client/tutorial007.py"
 ```
 

docs/client/oauth-clients.md

@@ -131,7 +131,7 @@ There is one more no-human situation: the client belongs to an enterprise whose
 
 ## When it fails
 
-When the OAuth flow goes wrong, the provider raises an `OAuthFlowError` from `mcp.client.auth`. It has two subclasses. `OAuthRegistrationError` means the authorization server refused to register you. `OAuthTokenError` means the token endpoint said no. One `except OAuthFlowError:` covers discovery, registration, authorization, and exchange.
+When the OAuth flow goes wrong, the provider raises an `OAuthFlowError` from `mcp.client.auth`. It has two subclasses. `OAuthRegistrationError` means registration did not yield a client you can use: the authorization server refused to register you, or it did register you but with credentials this flow cannot use (for instance an authentication method it does not implement). `OAuthTokenError` means a token could not be obtained: the token endpoint said no, or a stored client record carries an authentication method this client cannot apply, which is reported while building the token request rather than sent. One `except OAuthFlowError:` covers discovery, registration, authorization, and exchange.
 
 Not everything is a flow error. The network can still fail; those are ordinary `httpx2` exceptions and pass through untouched.