Document client extensions and prove the loop in the interaction suite

docs/advanced/extensions.md gains the client half: using an extension
(construct, pass extensions=[...], call tools normally), writing one
(identifier, claims with a resolver doing real follow-up sends,
notifications, read-once settings), and extension verbs via Request
subclasses with name_param. Two runnable tutorials back the page.
Interaction tests prove the five-sentence story over the real harness:
the both-ends claimed-result loop with a resolver follow-up, the
off-switch (undeclared shape fails validation; legacy ad drops
claim-bearing identifiers), per-request capability gating with -32021
refusal, and Mcp-Name from name_param observed on the modern HTTP
wire.

Author: maxisbey

docs/advanced/extensions.md

@@ -2,9 +2,10 @@
 
 An **extension** is an opt-in bundle of MCP behaviour behind one identifier.
 
-It can contribute tools, resources, and new request methods, and it can wrap `tools/call`.
-The server advertises it under `capabilities.extensions`, the client opts in the same way,
-and nothing changes for anyone who didn't ask for it. That is the contract ([SEP-2133](https://github.com/modelcontextprotocol/modelcontextprotocol/pull/2133)), and
+On a server it can contribute tools, resources, and new request methods, and it can wrap
+`tools/call`. On a client it can claim extra `tools/call` result shapes and observe vendor
+notifications. Each side advertises under its own `capabilities.extensions`, and nothing
+changes for anyone who didn't ask for it. That is the contract ([SEP-2133](https://github.com/modelcontextprotocol/modelcontextprotocol/pull/2133)), and
 it has one golden rule: **extensions are off by default**.
 
 ## Using an extension
@@ -79,7 +80,7 @@ And `main()` is the proof, an in-memory client straight against `mcp`:
 An extension can register **new request methods**: its own verbs, served next to the
 spec's:
 
-```python title="server.py" hl_lines="15-21 30 39-47"
+```python title="server.py" hl_lines="16-22 31 40-48"
 --8<-- "docs_src/extensions/tutorial004.py"
 ```
 
@@ -108,15 +109,15 @@ runtime:
 
 The same file's `main()` is the whole client story, both halves of it:
 
-```python title="server.py" hl_lines="53-57"
+```python title="server.py" hl_lines="54-58"
 --8<-- "docs_src/extensions/tutorial004.py"
 ```
 
-* `Client(..., extensions={EXTENSION_ID: {}})` declares the extension. That map
-  becomes `ClientCapabilities.extensions`: on a 2026-07-28 connection it travels in
-  the per-request `_meta` envelope, so the server sees it on **every** request; on
-  a legacy connection it rides the `initialize` handshake. Server code doesn't care
-  which: `require_client_extension(ctx, ...)` and
+* `Client(..., extensions=[advertise(EXTENSION_ID)])` declares the extension. The
+  declarations become `ClientCapabilities.extensions`: on a 2026-07-28 connection
+  the map travels in the per-request `_meta` envelope, so the server sees it on
+  **every** request; on a legacy connection it rides the `initialize` handshake.
+  Server code doesn't care which: `require_client_extension(ctx, ...)` and
   `ctx.session.check_client_capability(...)` read the right source on both paths.
 * Vendor methods drop one layer to `client.session.send_request(...)`; `Client`
   only grows first-class methods for spec verbs. `send_request` accepts any
@@ -144,15 +145,103 @@ or veto a tool call:
 The hook wraps `tools/call` and nothing else. For every-message concerns, use
 [Middleware](middleware.md). That is what it is for.
 
+## Using a client extension
+
+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="66-68"
+--8<-- "docs_src/extensions/tutorial006.py"
+```
+
+`call_tool("buy", ...)` returns a plain `CallToolResult`, like every other call. What
+the extension changed: the server may now answer `buy` with a `receipt` **result
+shape** instead of a final result, and `Receipts` finishes it — here by redeeming the
+receipt with a follow-up call — before `call_tool` returns. Nothing about the call
+site moves.
+
+Drop the extension and none of this exists: a `receipt` shape arriving at a client
+that didn't declare it fails validation, exactly as the spec requires for an
+unrecognized `resultType`. Off by default, on both ends of the wire.
+
+To advertise an identifier with **no** client-side behaviour — the server gates on
+the capability, the client does nothing, as in the search client above — use
+`advertise()`:
+
+```python
+from mcp.client import advertise
+
+client = Client(mcp, extensions=[advertise("com.example/search")])
+```
+
+## Writing a client extension
+
+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 43-44 46-47"
+--8<-- "docs_src/extensions/tutorial006.py"
+```
+
+* The identifier follows the same grammar as the server's, validated when the class
+  is defined.
+* `claims()` returns `ResultClaim`s: a wire tag, the model that parses it, and the
+  resolver that finishes it. The model must pin the tag with
+  `result_type: Literal["receipt"]` and must not subclass a core result type — both
+  enforced when the claim is constructed. (The payload rides `requestState` here
+  because an `MCPServer` substituting a claimed shape serializes only the core
+  `tools/call` surface fields; a server on another SDK may send richer shapes.)
+* The resolver receives the parsed model and a `ClaimContext`; `ctx.session` is the
+  same public handle as `client.session`, so follow-ups are ordinary session calls.
+  It returns the verb's normal `CallToolResult`.
+* `settings()` is the value advertised at `ClientCapabilities.extensions[identifier]`,
+  read once at `Client` construction.
+
+`notifications()` declares vendor server notifications to observe:
+
+```python
+def notifications(self) -> Sequence[NotificationBinding[Any]]:
+    return [NotificationBinding(method="notifications/receipts", params_type=ReceiptEvent, handler=self.on_receipt)]
+```
+
+The handler receives validated params, in arrival order. It observes; it cannot veto
+or reply.
+
+Two quiet rules. Claims are active on 2026-07-28 connections only, and the capability
+ad follows them: on a legacy connection the claims dissolve and the identifier drops
+out of the ad in the same breath, so the client never advertises an extension whose
+shapes it would reject. And when you want the claimed shape yourself instead of the
+resolver, call `client.session.call_tool(..., allow_claimed=True)` — the escape hatch
+`UnexpectedClaimedResult` names when a claimed shape reaches a session-tier caller
+that didn't opt in.
+
+### 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`,
+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"
+--8<-- "docs_src/extensions/tutorial007.py"
+```
+
+The session mirrors `params["jobId"]` into `Mcp-Name` on every send path, and a
+missing value fails loudly rather than silently omitting a required header.
+
 ## What an extension cannot do
 
-The contribution surface is **closed** on purpose: settings, tools, resources,
-methods, one `tools/call` interceptor. An extension cannot:
+The contribution surface is **closed** on purpose — on the server: settings, tools,
+resources, methods, one `tools/call` interceptor; on the client: settings, result
+claims, notification bindings. An extension cannot:
 
-* **Reach into the server.** It declares data; it holds no server reference.
+* **Reach into the host.** It declares data; it holds no server or client reference.
 * **Replace core behaviour.** Spec methods are rejected at construction, and
   `initialize` is reserved by the runner outright.
-* **Register late.** After `MCPServer(...)` returns, the extension set is what it is.
+* **Register late.** After `MCPServer(...)` or `Client(...)` returns, the extension
+  set is what it is.
 
 If you are fighting these walls, you are not writing an extension. You are writing
 a fork. The walls are the feature: a user reading `extensions=[Apps(), Stamps()]`

docs_src/extensions/tutorial006.py

@@ -0,0 +1,69 @@
+from collections.abc import Sequence
+from typing import Any, Literal
+
+import mcp_types as types
+
+from mcp import Client
+from mcp.client import ClaimContext, ClientExtension, ResultClaim
+from mcp.server.context import CallNext, HandlerResult, ServerRequestContext
+from mcp.server.extension import Extension
+from mcp.server.mcpserver import MCPServer
+
+EXTENSION_ID = "com.example/receipts"
+
+
+class ReceiptResult(types.Result):
+    """The claimed result shape; `result_type` pins the wire tag."""
+
+    result_type: Literal["receipt"] = "receipt"
+    request_state: str
+
+
+class ReceiptIssuer(Extension):
+    """Server half: answers `buy` with a receipt instead of a final result."""
+
+    identifier = EXTENSION_ID
+
+    async def intercept_tool_call(
+        self,
+        params: types.CallToolRequestParams,
+        ctx: ServerRequestContext[Any, Any],
+        call_next: CallNext,
+    ) -> HandlerResult:
+        if params.name != "buy":
+            return await call_next(ctx)
+        return {"resultType": "receipt", "requestState": "r-117"}
+
+
+class Receipts(ClientExtension):
+    """Client half: claims the `receipt` shape and supplies the code that finishes it."""
+
+    identifier = EXTENSION_ID
+
+    def claims(self) -> Sequence[ResultClaim[Any]]:
+        return [ResultClaim(result_type="receipt", model=ReceiptResult, resolve=self._redeem)]
+
+    async def _redeem(self, claimed: ReceiptResult, ctx: ClaimContext) -> types.CallToolResult:
+        return await ctx.session.call_tool("redeem", {"token": claimed.request_state})
+
+
+mcp = MCPServer("shop", extensions=[ReceiptIssuer()])
+
+
+@mcp.tool()
+def buy(item: str) -> types.CallToolResult:
+    """Buy an item."""
+    raise NotImplementedError  # ReceiptIssuer answers `buy` before the tool runs
+
+
+@mcp.tool()
+def redeem(token: str) -> str:
+    """Exchange a receipt token for the goods."""
+    return f"goods for {token}"
+
+
+async def main() -> None:
+    async with Client(mcp, extensions=[Receipts()]) as client:
+        result = await client.call_tool("buy", {"item": "lamp"})
+        print(result.content)
+        # [TextContent(text='goods for r-117')]

docs_src/extensions/tutorial007.py

@@ -0,0 +1,50 @@
+from collections.abc import Sequence
+from typing import Any, Literal
+
+import mcp_types as types
+
+from mcp import Client
+from mcp.client import advertise
+from mcp.server.context import ServerRequestContext
+from mcp.server.extension import Extension, MethodBinding
+from mcp.server.mcpserver import MCPServer
+
+EXTENSION_ID = "com.example/jobs"
+
+
+class JobParams(types.RequestParams):
+    job_id: str
+
+
+class JobStatus(types.Result):
+    status: str
+
+
+class JobStatusRequest(types.Request[JobParams, Literal["com.example/jobs.status"]]):
+    method: Literal["com.example/jobs.status"] = "com.example/jobs.status"
+    params: JobParams
+    name_param = "jobId"  # params["jobId"] rides the Mcp-Name header
+
+
+async def job_status(ctx: ServerRequestContext[Any, Any], params: JobParams) -> JobStatus:
+    return JobStatus(status=f"{params.job_id} is running")
+
+
+class Jobs(Extension):
+    """An extension whose verb names its subject, so the header can route on it."""
+
+    identifier = EXTENSION_ID
+
+    def methods(self) -> Sequence[MethodBinding]:
+        return [MethodBinding("com.example/jobs.status", JobParams, job_status)]
+
+
+mcp = MCPServer("worker", extensions=[Jobs()])
+
+
+async def main() -> None:
+    async with Client(mcp, extensions=[advertise(EXTENSION_ID)]) as client:
+        request = JobStatusRequest(params=JobParams(job_id="job-7"))
+        result = await client.session.send_request(request, JobStatus)
+        print(result.status)
+        # job-7 is running

tests/docs_src/test_extensions.py

@@ -5,8 +5,17 @@
 import pytest
 from inline_snapshot import snapshot
 from mcp_types import METHOD_NOT_FOUND, MISSING_REQUIRED_CLIENT_CAPABILITY, TextContent
-
-from docs_src.extensions import tutorial001, tutorial002, tutorial003, tutorial004, tutorial005
+from pydantic import ValidationError
+
+from docs_src.extensions import (
+    tutorial001,
+    tutorial002,
+    tutorial003,
+    tutorial004,
+    tutorial005,
+    tutorial006,
+    tutorial007,
+)
 from mcp import Client, MCPError
 from mcp.client import advertise
 from mcp.server.extension import Extension
@@ -94,3 +103,34 @@ async def test_interceptor_observes_the_call_and_passes_the_result_through(
     assert result.structured_content == {"result": 5}
     messages = [record.getMessage() for record in caplog.records if record.name == tutorial005.logger.name]
     assert messages == ["tool 'add' called"]
+
+
+async def test_the_receipts_client_program_runs_as_shown(capsys: pytest.CaptureFixture[str]) -> None:
+    """tutorial006: `main()` is the literal client program on the page — the claimed
+    `receipt` shape never surfaces, and the printed content is the redeemed result."""
+    await tutorial006.main()
+    assert "goods for r-117" in capsys.readouterr().out
+
+
+async def test_a_claimed_shape_fails_validation_without_the_extension() -> None:
+    """The page's off-by-default claim: a client that does not construct `Receipts`
+    rejects the `receipt` shape as invalid (spec: an unrecognized resultType is invalid)."""
+    async with Client(tutorial006.mcp) as client:
+        with pytest.raises(ValidationError):
+            await client.call_tool("buy", {"item": "lamp"})
+
+
+async def test_session_tier_allow_claimed_returns_the_raw_shape() -> None:
+    """The page's escape hatch: `client.session.call_tool(..., allow_claimed=True)` hands
+    back the parsed claim model instead of running the resolver."""
+    async with Client(tutorial006.mcp, extensions=[tutorial006.Receipts()]) as client:
+        result = await client.session.call_tool("buy", {"item": "lamp"}, allow_claimed=True)
+    assert isinstance(result, tutorial006.ReceiptResult)
+    assert result.request_state == "r-117"
+
+
+async def test_the_jobs_client_program_runs_as_shown(capsys: pytest.CaptureFixture[str]) -> None:
+    """tutorial007: a vendor request type with `name_param` goes through
+    `client.session.send_request` with no registration and returns its typed result."""
+    await tutorial007.main()
+    assert "job-7 is running" in capsys.readouterr().out