Add a client extension API (#3034)

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