Add a client extension API (#3034)

examples/stories/apps/README.md

@@ -26,7 +26,7 @@ uv run python -m stories.apps.client --http
   `text/html;profile=mcp-app`.
 - `server.py` `client_supports_apps(ctx)` — SEP-2133 graceful degradation: a
   client that did not negotiate Apps gets a text-only result.
-- `client.py` `Client(target, extensions={...})` — the client advertises Apps
+- `client.py` `Client(target, extensions=[advertise(...)])` — the client advertises Apps
   support so the server returns the UI-enabled result, then reads the tool's
   `_meta.ui.resourceUri` and fetches that resource.
 

examples/stories/apps/client.py

@@ -2,7 +2,7 @@
 
 from mcp_types import TextContent, TextResourceContents
 
-from mcp.client import Client
+from mcp.client import Client, advertise
 from mcp.server.apps import APP_MIME_TYPE, EXTENSION_ID
 from stories._harness import Target, run_client
 
@@ -10,7 +10,9 @@ from stories._harness import Target, run_client
 async def main(target: Target, *, mode: str = "auto") -> None:
     # Advertise MCP Apps support so the server returns the UI-enabled result; a
     # client that omits this gets the text-only fallback (graceful degradation).
-    async with Client(target, mode=mode, extensions={EXTENSION_ID: {"mimeTypes": [APP_MIME_TYPE]}}) as client:
+    async with Client(
+        target, mode=mode, extensions=[advertise(EXTENSION_ID, {"mimeTypes": [APP_MIME_TYPE]})]
+    ) as client:
         # The extensions capability map rides `server/discover` (modern only). On a
         # legacy connection (today's stdio) it is absent, so assert it only when present.
         if client.server_capabilities.extensions is not None:

examples/stories/custom_methods/README.md

@@ -28,18 +28,16 @@ uv run python -m stories.custom_methods.client --http
   method string is the wire `method`; use a vendor prefix so it can never
   collide with a future spec method.
 - `client.py` `client.session.send_request(...)` — `Client` only exposes spec
-  verbs, so vendor methods go through the underlying `ClientSession`. The
-  `cast("types.ClientRequest", ...)` is needed because `send_request`'s
-  `request` parameter is currently typed as the closed spec union; widening it
-  (or adding `Client.send_request`) is tracked for beta.
+  verbs, so vendor methods go through the underlying `ClientSession`.
+  `send_request` accepts any `types.Request` subclass.
 
 ## Caveats
 
 - The TypeScript SDK's equivalent example also shows a custom server→client
-  **notification** (`acme/searchProgress`). The Python client currently drops
-  any notification whose method is not in the spec registry
-  (`ClientSession._on_notify` → `KeyError` → silent drop), and there is no
-  `set_notification_handler` analogue. That half is omitted here.
+  **notification** (`acme/searchProgress`). The Python client can observe
+  vendor notifications via `NotificationBinding` (see
+  `docs/advanced/extensions.md`). That half is omitted here because the
+  lowlevel server has no surface for emitting vendor notifications yet.
 
 ## Spec
 

examples/stories/custom_methods/client.py

@@ -1,6 +1,6 @@
 """Send a vendor-prefixed request via the `client.session` escape hatch."""
 
-from typing import Literal, cast
+from typing import Literal
 
 import mcp_types as types
 
@@ -26,12 +26,10 @@ async def main(target: Target, *, mode: str = "auto") -> None:
     async with Client(target, mode=mode) as client:
         # `Client` only exposes spec-defined verbs, so vendor methods have to drop one
         # layer to `client.session` today — there is no `Client`-level API for them
-        # yet, and whether `.session` stays public is undecided. `send_request` is
-        # typed against the closed `ClientRequest` union, hence the cast; at runtime
-        # the body only calls `.model_dump()` and the unknown method skips the
-        # per-spec result-validation registry.
+        # yet, and whether `.session` stays public is undecided. `send_request`
+        # accepts any `Request` subclass.
         request = SearchRequest(params=SearchParams(query="mcp", limit=3))
-        result = await client.session.send_request(cast("types.ClientRequest", request), SearchResult)
+        result = await client.session.send_request(request, SearchResult)
         assert result.items == ["mcp-0", "mcp-1", "mcp-2"], result
 
 

examples/stories/extensions/README.md

@@ -24,7 +24,7 @@ uv run python -m stories.extensions.client --http
   rejects clients that did not declare the extension with `-32021` (missing
   required client capability) and a machine-readable `requiredCapabilities`
   payload.
-- `client.py` `Client(target, extensions={EXTENSION_ID: {}})` — the client-side
+- `client.py` `Client(target, extensions=[advertise(EXTENSION_ID)])` — the client-side
   half of the negotiation; on 2026-07-28 it travels in the per-request `_meta`
   envelope.
 - `client.py` `client.session.send_request(...)` — vendor methods have no

examples/stories/extensions/client.py

@@ -1,11 +1,11 @@
 """Discover an extension's capability entry, call its tool, then send its vendor method."""
 
-from typing import Literal, cast
+from typing import Literal
 
 import mcp_types as types
 from mcp_types import TextContent
 
-from mcp.client import Client
+from mcp.client import Client, advertise
 from stories._harness import Target, run_client
 
 EXTENSION_ID = "com.example/catalog"
@@ -28,7 +28,7 @@ class SearchResult(types.Result):
 async def main(target: Target, *, mode: str = "auto") -> None:
     # Declare the extension client-side so the server's `require_client_extension`
     # gate on `com.example/search` passes.
-    async with Client(target, mode=mode, extensions={EXTENSION_ID: {}}) as client:
+    async with Client(target, mode=mode, extensions=[advertise(EXTENSION_ID)]) as client:
         # The extensions capability map rides `server/discover` (modern only). On a
         # legacy connection it is absent, so assert it only when present.
         if client.server_capabilities.extensions is not None:
@@ -43,10 +43,9 @@ async def main(target: Target, *, mode: str = "auto") -> None:
         assert isinstance(result.content[0], TextContent)
         assert result.content[0].text == "mcp-suggestion", result.content[0].text
 
-        # Vendor methods drop one layer to `client.session` (see custom_methods/);
-        # the cast is needed because `send_request` is typed against the spec union.
+        # Vendor methods drop one layer to `client.session` (see custom_methods/).
         request = SearchRequest(params=SearchParams(query="mcp", limit=3))
-        found = await client.session.send_request(cast("types.ClientRequest", request), SearchResult)
+        found = await client.session.send_request(request, SearchResult)
         assert found.items == ["mcp-0", "mcp-1", "mcp-2"], found