Add a client extension API (#3034)

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