Merge remote-tracking branch 'origin/main' into 3174-client-span-error-status

Author: maxisbey

docs/handlers/cancellation.md

@@ -0,0 +1,55 @@
+# Cancellation
+
+A client can give up on a call: the user pressed stop, or a timeout ran out.
+
+When it does, the SDK **cancels your handler**. The `await` it is waiting on raises, the function unwinds, and nothing it returns is sent. Most handlers need to do nothing about that.
+
+Two kinds do: a handler with something to clean up, and a handler that is a plain `def`.
+
+## Clean up in an `async def` tool
+
+Put the cleanup in a `finally`:
+
+```python title="server.py" hl_lines="23 26-28"
+--8<-- "docs_src/cancellation/tutorial001.py"
+```
+
+* The `finally` runs however the tool ends: it returned, it raised, or it was cancelled.
+* Cleanup that has to `await` needs `shield=True`. In a cancelled handler every further `await` raises too, so without the shield `release_hold` would stop at its first line.
+* Nothing can cancel a shielded block, so give it a time limit. Here that is `5` seconds.
+
+!!! tip
+    Reach for `finally`, not `except`. The cancellation has to keep travelling up once your cleanup
+    is done, and a `finally` lets it.
+
+## Stop early in a plain `def` tool
+
+A plain `def` tool runs in a thread, and nothing can interrupt a thread from outside. The tool has to ask:
+
+```python title="server.py" hl_lines="22 25-26"
+--8<-- "docs_src/cancellation/tutorial002.py"
+```
+
+* `anyio.from_thread.check_cancelled()` does nothing while the call is live, and raises once it has been cancelled. Call it between units of work.
+* Cleanup goes in a `finally` here too. Nothing in a thread awaits, so it needs no shield.
+* A `def` tool that never asks runs to the end, and its result is thrown away.
+
+## Where it applies
+
+Prompt and resource functions are cancelled exactly like tools.
+
+It works the same over stdio and Streamable HTTP. With this SDK's `Client`, giving up means cancelling the task that awaits `call_tool`, or letting its `read_timeout_seconds` run out.
+
+!!! warning
+    Two Streamable HTTP options keep the news from your handler: `json_response=True` on a
+    `2026-07-28` connection, and `stateless_http=True` on a legacy one. There the handler runs to
+    the end whatever the client did.
+
+## Recap
+
+* When the client gives up on a call, the SDK cancels the handler: tool, prompt or resource.
+* `async def`: clean up in a `finally`, and put cleanup that awaits inside `anyio.move_on_after(seconds, shield=True)`.
+* Plain `def`: call `anyio.from_thread.check_cancelled()` between units of work, or the tool runs to the end. A plain `finally` cleans up.
+* `json_response=True` (modern connections) and `stateless_http=True` (legacy ones) switch cancellation off.
+
+Progress and cancellation are between a running tool and its *caller*. The lines it logs for *you*, the person operating the server, are a different channel: **[Logging](logging.md)**.

docs/handlers/index.md

@@ -22,6 +22,8 @@ What it can do while it runs:
   **[Sampling and roots](sampling-and-roots.md)**, deprecated but still
   served.
 * Report **[Progress](progress.md)** on something slow.
+* Clean up, or stop early, when the client gives up on the call, with
+  **[Cancellation](cancellation.md)**.
 * Write logs (to standard error, for whoever operates the server) with
   **[Logging](logging.md)**.
 * Tell subscribed clients that something changed with

docs/handlers/progress.md

@@ -115,4 +115,4 @@ The callback receives `total=None`. A client can still show *activity* ("3 impor
 * No callback on the call means `report_progress` does nothing. Report unconditionally.
 * Omit `total` when you don't know it; the callback gets `None`.
 
-Progress is what a running tool shows the *user*. The lines it logs for *you*, the person operating the server, are a different channel: **[Logging](logging.md)**.
+Progress is for a client that is still waiting. What your tool sees when the client stops waiting is **[Cancellation](cancellation.md)**.

docs/migration.md

@@ -97,7 +97,7 @@ dependencies = [
 ]
 ```
 
-Relax or bump any conflicting pins when upgrading. sse-starlette jumps two majors, so a project that imports `sse_starlette` itself must also work through that library's own breaking changes to co-install with mcp v2. `opentelemetry-api` is a new hard dependency because every outbound request now carries a `_meta` envelope used for OpenTelemetry trace propagation; see [Every outbound request now carries a `_meta` envelope](#every-outbound-request-now-carries-a-_meta-envelope-opentelemetry-is-on-by-default). `mcp-types` is exact-pinned to the SDK version; nothing in a v1 tree can conflict with it, but do not pin `mcp-types` independently of `mcp`.
+Relax or bump any conflicting pins when upgrading. sse-starlette jumps two majors, so a project that imports `sse_starlette` itself must also work through that library's own breaking changes to co-install with mcp v2. `opentelemetry-api` is a new hard dependency because OpenTelemetry trace propagation now ships enabled; see [OpenTelemetry is on by default](#opentelemetry-is-on-by-default). `mcp-types` is exact-pinned to the SDK version; nothing in a v1 tree can conflict with it, but do not pin `mcp-types` independently of `mcp`.
 
 ### `httpx` and `httpx-sse` replaced by `httpx2`
 
@@ -1789,7 +1789,7 @@ Positional callers (`session.elicit_form(message, schema)`) are unaffected, and
 
 ### `Client` defaults to `mode='auto'`
 
-In v1, connecting to a server always performed the `initialize` handshake. In v2, `Client` defaults to `mode='auto'`: on enter it probes `server/discover` and, if the server doesn't support it, falls back to the `initialize` handshake. Pass `mode='legacy'` to force the initialize handshake and reproduce v1's pre-2026 connection sequence (the per-request wire shape still differs from v1; see [Every outbound request now carries a `_meta` envelope](#every-outbound-request-now-carries-a-_meta-envelope-opentelemetry-is-on-by-default)), or pass a modern protocol-version string (e.g. `mode='2026-07-28'`) to pin a version without probing.
+In v1, connecting to a server always performed the `initialize` handshake. In v2, `Client` defaults to `mode='auto'`: on enter it probes `server/discover` and, if the server doesn't support it, falls back to the `initialize` handshake. Pass `mode='legacy'` to force the initialize handshake and reproduce v1's pre-2026 connection sequence, or pass a modern protocol-version string (e.g. `mode='2026-07-28'`) to pin a version without probing.
 
 The probe is transport-independent: v2 servers answer it over stdio (and any other stream-pair transport) as well as streamable HTTP, so `mode='auto'` lands on `2026-07-28` against a v2 server on every transport. If your stdio workflow relies on server-initiated requests (sampling, push elicitation, roots), pass `mode='legacy'` — a 2026-07-28 connection refuses them on every transport with `NoBackChannelError` (see [Server-initiated sampling, elicitation, and roots raise `NoBackChannelError`](#server-initiated-sampling-elicitation-and-roots-raise-nobackchannelerror)).
 
@@ -2659,25 +2659,9 @@ Validation runs when the result is serialized onto the wire, not when the model
 
 In v1, a request for a method the SDK didn't recognize failed request-union validation and was answered with `-32602` (`"Invalid request parameters"`, empty `data`). Any method the receiver doesn't serve — unrecognized on either side, or a spec method the server has no registered handler for — is now answered with the JSON-RPC-specified `-32601` (`"Method not found"`), with the method name in `data`, in every initialization state. Clients still decline sampling, elicitation, and roots requests with `-32600` when no callback is registered, as in v1. Update anything that matched on the old code for this case.
 
-### Every outbound request now carries a `_meta` envelope; OpenTelemetry is on by default
+### OpenTelemetry is on by default
 
-v2 sends `"_meta": {}` in the params of every request it emits, at every negotiated protocol version. Requests that had no params in v1, such as `ping` and `tools/list`, now carry `"params": {"_meta": {}}`; server-initiated requests get the same envelope. This is spec-valid and accepted by all peers, but wire traffic differs from v1 on every call, and no configuration restores the v1 wire shape. Update any test or tooling that asserts on raw outbound request bytes.
-
-**Before (v1):** same client code, 2025-11-25 peer:
-
-```text
-{"method":"ping","jsonrpc":"2.0","id":1}
-{"method":"tools/list","jsonrpc":"2.0","id":2}
-```
-
-**After (v2):**
-
-```text
-{"jsonrpc":"2.0","id":2,"method":"ping","params":{"_meta":{}}}
-{"jsonrpc":"2.0","id":3,"method":"tools/list","params":{"_meta":{}}}
-```
-
-The envelope exists for OpenTelemetry trace propagation ([SEP-414](https://github.com/modelcontextprotocol/modelcontextprotocol/pull/414)), which now ships enabled: every server installs a tracing middleware and the client opens a span per outbound request. With no OpenTelemetry SDK configured these are no-ops and only the empty envelope is visible. If your application already configures a global tracer provider, it starts recording MCP client and server spans with no code change, and a W3C `traceparent` field is injected into outbound `_meta`, propagating your trace ids to the servers you call. To suppress the spans, filter the `mcp-python-sdk` tracer in your pipeline; [OpenTelemetry](run/opentelemetry.md) has the recipe for removing the server middleware. There is no public switch for the client-side span and `traceparent` injection.
+OpenTelemetry trace propagation ([SEP-414](https://github.com/modelcontextprotocol/modelcontextprotocol/pull/414)) now ships enabled: every server installs a tracing middleware and the client opens a span per outbound request. With no OpenTelemetry SDK configured these are no-ops and nothing is added to outbound requests. If your application already configures a global tracer provider, it starts recording MCP client and server spans with no code change, and a W3C `traceparent` field is injected into outbound `_meta`, propagating your trace ids to the servers you call. To suppress the spans, filter the `mcp-python-sdk` tracer in your pipeline; [OpenTelemetry](run/opentelemetry.md) has the recipe for removing the server middleware. There is no public switch for the client-side span and `traceparent` injection.
 
 The SDK's new `opentelemetry-api` runtime dependency is covered under [Packaging, dependencies, and CLI](#packaging-dependencies-and-cli).
 

docs/servers/tools.md

@@ -136,7 +136,7 @@ You can mix and match: plain parameters next to model parameters, nested models,
 
 If a tool does I/O (calls an API, reads a file, queries a database), declare it `async def` and `await` inside it. The SDK awaits it.
 
-A plain `def` tool works too: the SDK runs it in a thread so it never blocks the server.
+A plain `def` tool works too: the SDK runs it in a thread so it never blocks the server. A long one can check whether the client is still waiting; see **[Cancellation](../handlers/cancellation.md)**.
 
 There is nothing else to configure.
 

docs_src/cancellation/__init__.py

@@ -0,0 +1,28 @@
+import anyio
+
+from mcp.server import MCPServer
+
+mcp = MCPServer("Bookshop")
+
+holds: set[str] = set()
+
+
+async def take_payment(title: str) -> None:
+    await anyio.sleep(30)  # the customer is typing a card number
+
+
+async def release_hold(title: str) -> None:
+    await anyio.sleep(0.1)  # a round trip to the stock system
+    holds.discard(title)
+
+
+@mcp.tool()
+async def order_book(title: str) -> str:
+    """Hold a copy of a book while the customer pays for it."""
+    holds.add(title)
+    try:
+        await take_payment(title)
+        return f"Ordered {title!r}."
+    finally:
+        with anyio.move_on_after(5, shield=True):
+            await release_hold(title)

docs_src/cancellation/tutorial001.py

@@ -0,0 +1,26 @@
+import time
+
+import anyio.from_thread
+
+from mcp.server import MCPServer
+
+mcp = MCPServer("Bookshop")
+
+offline: set[str] = set()
+
+
+def index_book(title: str) -> None:
+    time.sleep(1)  # slow work with nothing to await
+
+
+@mcp.tool()
+def rebuild_index(titles: list[str]) -> str:
+    """Take search offline and rebuild its index, one book at a time."""
+    offline.add("search")
+    try:
+        for title in titles:
+            anyio.from_thread.check_cancelled()
+            index_book(title)
+        return f"Indexed {len(titles)} books."
+    finally:
+        offline.discard("search")

docs_src/cancellation/tutorial002.py

@@ -40,6 +40,7 @@ nav:
       - Multi-round-trip requests: handlers/multi-round-trip.md
       - Sampling and roots: handlers/sampling-and-roots.md
       - Progress: handlers/progress.md
+      - Cancellation: handlers/cancellation.md
       - Logging: handlers/logging.md
       - Subscriptions: handlers/subscriptions.md
   - Running your server:

mkdocs.yml

@@ -362,7 +362,6 @@ async def send_raw_request(
         if on_progress is not None:
             # The request id doubles as the progress token, so `_pending[token]` finds `on_progress` directly.
             out_meta["progressToken"] = request_id
-        out_params["_meta"] = out_meta
 
         # buffer=1: a close signal can arrive before the waiter parks in receive();
         # a WouldBlock later just means the waiter already has its one outcome.
@@ -389,9 +388,18 @@ async def send_raw_request(
                 kind=SpanKind.CLIENT,
                 attributes={"mcp.method.name": method, "jsonrpc.request.id": str(request_id)},
             ) as span:
-                # SEP-414: inject W3C trace context; `_meta` stays on the wire even with a no-op tracer.
+                # SEP-414: inject W3C trace context.
                 inject_trace_context(out_meta)
-                msg = JSONRPCRequest(jsonrpc="2.0", id=request_id, method=method, params=out_params)
+                if out_meta:
+                    out_params["_meta"] = out_meta
+                else:
+                    out_params.pop("_meta", None)
+                # Leave `params` unset when empty: with `exclude_unset=True` an explicit
+                # None would serialize as `"params": null`, which JSON-RPC 2.0 forbids.
+                if out_params:
+                    msg = JSONRPCRequest(jsonrpc="2.0", id=request_id, method=method, params=out_params)
+                else:
+                    msg = JSONRPCRequest(jsonrpc="2.0", id=request_id, method=method)
                 # Surface a pre-existing cancellation while the request provably
                 # never started; past this point a cancelled write counts as issued.
                 await anyio.lowlevel.checkpoint_if_cancelled()