Max Isbey
1b74b06753
Cut comment and docstring volume roughly in half across src, tests, examples, and docs_src: removed comments that restate the adjacent code, leftover development narration, section banners, and self-evident Args/Returns blocks, and compressed the remaining docstrings to a Google-style summary line plus only the detail that earns its place. Kept (and tightened) the load-bearing content: Raises sections, deprecation and version-availability notes, spec/RFC/issue references, why-comments for non-obvious decisions, and all coverage pragmas. The generated mcp_types.v* wire modules are untouched.
custom-methods
Register and call a vendor-prefixed JSON-RPC method that is not part of the
MCP spec. The server uses the low-level Server.add_request_handler (there is
no MCPServer surface for this, so server.py is lowlevel-native and there is
no server_lowlevel.py sibling); the client drops to client.session to send
it.
Run it
# stdio (default — the client spawns the server as a subprocess)
uv run python -m stories.custom_methods.client
# HTTP — the client self-hosts the server on a free port, runs, then tears it down
uv run python -m stories.custom_methods.client --http
What to look at
client.pymain— the body opens withClient(target, mode=mode). The vendor request rides whichever protocol eramodeselects; nothing else in the story changes between eras.server.pySearchParams— subclassestypes.RequestParamsso_meta(and on a 2026-07-28 connection, the reservedio.modelcontextprotocol/*envelope keys) parse uniformly without extra code.server.pyadd_request_handler("acme/search", SearchParams, search)— the method string is the wiremethod; use a vendor prefix so it can never collide with a future spec method.client.pyclient.session.send_request(...)—Clientonly exposes spec verbs, so vendor methods go through the underlyingClientSession. Thecast("types.ClientRequest", ...)is needed becausesend_request'srequestparameter is currently typed as the closed spec union; widening it (or addingClient.send_request) is tracked for beta.
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 noset_notification_handleranalogue. That half is omitted here.
Spec
Requests — basic protocol (JSON-RPC request shape; vendor method names live outside the spec's reserved set).
See also
serve_one/ (the per-exchange driver that runs registered handlers),
middleware/ (wrapping every registered handler, including vendor methods).