Add the client-side subscriptions/listen driver (#3047)
This commit is contained in:
Max
GitHub
parent
6d2e908f2b
commit
9bdc03d54e
1 changed files with 2587 additions and 295 deletions
|
|
@ -1,94 +1,146 @@
|
|||
# Subscriptions
|
||||
|
||||
A server's catalog is not fixed. Tools get registered at runtime, resources change behind their URIs. The client side of that story is a subscription: on the 2026-07-28 protocol, a client that wants to hear about changes sends one `subscriptions/listen` request, and the response to that request *is* the stream — it stays open, carrying exactly the notification kinds the client asked for.
|
||||
A server's catalog is not fixed. Tools appear at runtime, and the content behind a resource URI changes.
|
||||
|
||||
**Subscriptions** are how a client hears about it. The client sends one `subscriptions/listen` request, and the response to that request *is* the stream: it stays open and carries the change notifications the client asked for.
|
||||
|
||||
## Publish it from the tool
|
||||
|
||||
Your side of it is one line: publish the change.
|
||||
|
||||
```python title="server.py" hl_lines="16 27"
|
||||
```python title="server.py" hl_lines="20 32"
|
||||
--8<-- "docs_src/subscriptions/tutorial001.py"
|
||||
```
|
||||
|
||||
* `await ctx.notify_resource_updated("note://todo")` delivers `notifications/resources/updated` to every open listen stream that subscribed to that URI. Not to anyone else.
|
||||
* `await ctx.notify_tools_changed()` delivers `notifications/tools/list_changed` to every stream that asked for tool-list changes. A client that receives it calls `tools/list` again — and now sees `search`.
|
||||
* The siblings are `notify_prompts_changed()` and `notify_resources_changed()`, for the other two list-changed kinds.
|
||||
* No subscribers, no work: publishing to an idle server is a no-op. You don't check whether anyone is listening; you state what changed.
|
||||
* `await ctx.notify_resource_updated("board://sprint")` reaches every open stream that subscribed to that URI. Nobody else.
|
||||
* `await ctx.notify_tools_changed()` reaches every stream that asked for tool-list changes. A client that receives it calls `tools/list` again, and now sees `sprint_report`.
|
||||
* The siblings are `notify_prompts_changed()` and `notify_resources_changed()`.
|
||||
* No subscribers, no work. Publishing to an idle server is a no-op, so you never check whether anyone is listening. You state what changed.
|
||||
|
||||
The SDK serves `subscriptions/listen` for you — `MCPServer` registers the handler at construction, and the wire obligations (the acknowledgment as the first frame, the per-stream filtering, the subscription id tagged onto every frame) are its job, not yours.
|
||||
`MCPServer` serves `subscriptions/listen` for you. The wire obligations (the acknowledgment as the first frame, per-stream filtering, the subscription id on every frame) are the SDK's job.
|
||||
|
||||
!!! check
|
||||
On the wire, a stream whose filter named `note://todo` looks like this after `edit_note` runs:
|
||||
On the wire, a stream whose filter named `board://sprint` looks like this after `complete_task` runs:
|
||||
|
||||
```json
|
||||
{"method": "notifications/subscriptions/acknowledged",
|
||||
"params": {"notifications": {"resourceSubscriptions": ["note://todo"]}, "_meta": {"io.modelcontextprotocol/subscriptionId": 7}}}
|
||||
"params": {"notifications": {"resourceSubscriptions": ["board://sprint"]}, "_meta": {"io.modelcontextprotocol/subscriptionId": "listen-1"}}}
|
||||
|
||||
{"method": "notifications/resources/updated",
|
||||
"params": {"uri": "note://todo", "_meta": {"io.modelcontextprotocol/subscriptionId": 7}}}
|
||||
"params": {"uri": "board://sprint", "_meta": {"io.modelcontextprotocol/subscriptionId": "listen-1"}}}
|
||||
```
|
||||
|
||||
The acknowledgment echoes the filter the server agreed to honor, and every frame carries the
|
||||
listen request's JSON-RPC id under `_meta` — that id *is* the subscription id.
|
||||
Note what the update does *not* carry: the board. Every frame carries the listen request's JSON-RPC id under `_meta`, and that id is the subscription id. The client mints it: the Python `Client` uses strings like `"listen-1"`; other clients may use integers.
|
||||
|
||||
## Only what was asked for
|
||||
|
||||
The filter is a contract. A stream that requested tool-list changes and one resource URI receives those two kinds and nothing else — publish a prompt change and that stream stays silent. Resource URIs are matched as exact strings: `note://todo` does not cover `note://todo/draft`.
|
||||
The filter is a contract. A stream that requested tool-list changes and one resource URI receives those two kinds and nothing else. Publish a prompt change and that stream stays silent.
|
||||
|
||||
`MCPServer` matches resource URIs as exact strings, so a stream that named `board://sprint` hears nothing about `board://sprint/tasks/1`. The spec lets a server report a change on a sub-resource of a subscribed URI; `MCPServer` never does, but clients are built to expect it.
|
||||
|
||||
Two things the stream is *not*:
|
||||
|
||||
* **It is not a replay log.** A dropped stream is gone, and events published while nobody was connected are not queued. Clients re-listen and refetch.
|
||||
* **It is not the 2025 path.** Clients that called `resources/subscribe` are served by `ctx.session.send_resource_updated(uri)`. The `notify_*` methods reach `subscriptions/listen` streams only.
|
||||
|
||||
!!! warning
|
||||
Filters are honored without per-client authorization: any client may name any URI —
|
||||
including one it cannot read — and will receive update notifications for it (resource
|
||||
existence and change timing, never content). On a multi-tenant server, don't publish
|
||||
sensitive per-user URIs through `notify_resource_updated`, or serve the method with
|
||||
your own handler on the low-level `Server` and narrow the filter there before acking —
|
||||
the honored subset exists in the protocol precisely so servers can do this.
|
||||
|
||||
Two more things the stream is *not*:
|
||||
|
||||
* **It is not a replay log.** A dropped stream is gone; events published while nobody was connected are not queued. The client's contract is to re-listen and re-fetch what it cares about.
|
||||
* **It is not the 2025 path.** Clients on earlier protocol versions that called `resources/subscribe` are served by `ctx.session.send_resource_updated(uri)` — the `notify_*` methods reach `subscriptions/listen` streams only.
|
||||
Don't publish sensitive per-user URIs through `notify_resource_updated` on a multi-tenant
|
||||
server. Any client may name any URI in its filter, and `MCPServer` honors it. The exposure
|
||||
is narrow but real: a subscriber learns that a URI it can guess changed, and when. It never
|
||||
learns content, and it cannot probe what exists, because an unknown URI is honored too and
|
||||
simply never fires. To narrow the filter per client today, serve the method with your own
|
||||
handler on the low-level `Server` and acknowledge a smaller filter than the client asked
|
||||
for; the acknowledgment is how the client learns what it actually got.
|
||||
|
||||
!!! warning "Streamable HTTP only, for now"
|
||||
`subscriptions/listen` is served on the streamable-HTTP transport. Over stdio (and other
|
||||
stream-pair transports) a 2026-07-28 connection rejects it with METHOD_NOT_FOUND — the
|
||||
open-stream semantics haven't been built for that transport yet, even though
|
||||
`server/discover` still advertises the subscription capabilities there.
|
||||
`subscriptions/listen` needs a transport that can stream a request's response, which today
|
||||
means streamable HTTP. Over stdio a 2026-07-28 connection rejects the method with
|
||||
METHOD_NOT_FOUND, even though `server/discover` advertises the subscription capabilities
|
||||
there. Serving it over stdio is planned; the open-stream semantics for that transport are
|
||||
not built yet.
|
||||
|
||||
## One process is the default. More takes a bus
|
||||
## The client end
|
||||
|
||||
Publishes travel from your handler to the open streams over a `SubscriptionBus`. The default is in-memory: one process, every stream in it. That is the right answer until you run replicas behind a load balancer — then a client's stream is pinned to one replica, and a publish on another replica has to reach it.
|
||||
Here is a client on the other side of that stream, following the board:
|
||||
|
||||
```python title="client.py" hl_lines="16"
|
||||
--8<-- "docs_src/subscriptions/tutorial003.py"
|
||||
```
|
||||
|
||||
Entering `client.listen(...)` sends the request and waits for your acknowledgment, so the stream is live when the block starts, and each typed event is a cue to refetch, never a payload. That is the whole contract in one screen. Everything else about the client end lives on its own page: watching beside a main flow, stream endings, and re-listening. See **[Subscriptions](../client/subscriptions.md)** under *Clients*.
|
||||
|
||||
## Scaling past one process
|
||||
|
||||
Publishes travel from your handler to the open streams over a `SubscriptionBus`. The default is in-memory: one process, every stream in it. That is the right answer until you run replicas behind a load balancer, because then a client's stream is pinned to one replica, and a publish on another replica has to reach it.
|
||||
|
||||
That seam is yours to implement: two methods over your pub/sub backend.
|
||||
|
||||
```python
|
||||
from collections.abc import Callable
|
||||
|
||||
from redis.asyncio import Redis
|
||||
|
||||
from mcp.server.mcpserver import MCPServer
|
||||
from mcp.server.subscriptions import ServerEvent # SubscriptionBus is a Protocol: no base class
|
||||
|
||||
|
||||
class RedisSubscriptionBus:
|
||||
def __init__(self, redis: Redis) -> None:
|
||||
self._redis = redis
|
||||
self._listeners: dict[object, Callable[[ServerEvent], None]] = {}
|
||||
|
||||
async def publish(self, event: ServerEvent) -> None:
|
||||
await self.redis.publish("mcp-events", encode(event)) # to every replica
|
||||
await self._redis.publish("mcp-events", encode(event)) # to every replica
|
||||
|
||||
def subscribe(self, listener: Callable[[ServerEvent], None]) -> Callable[[], None]:
|
||||
... # register the local listener; a reader task calls it for arriving events
|
||||
token = object()
|
||||
self._listeners[token] = listener
|
||||
|
||||
def unsubscribe() -> None:
|
||||
self._listeners.pop(token, None)
|
||||
|
||||
return unsubscribe
|
||||
|
||||
|
||||
mcp = MCPServer("Sprint Board", subscriptions=RedisSubscriptionBus(redis))
|
||||
```
|
||||
|
||||
`encode` is yours, and so is the reader task on each replica that decodes arriving messages and calls every registered listener. Listeners are synchronous, must not raise, and run on the server's event loop.
|
||||
|
||||
The bus carries typed `ServerEvent` values, four small dataclasses, never JSON-RPC. Stamping, filtering, and stream lifecycles stay in the SDK, so a bus implementation cannot break the protocol. It can only move events between processes.
|
||||
|
||||
To publish from outside a request, construct the bus yourself so you hold the reference. `MCPServer` builds one internally when you pass nothing, and does not expose it.
|
||||
|
||||
```python
|
||||
mcp = MCPServer("Notebook", subscriptions=RedisSubscriptionBus(...))
|
||||
```
|
||||
from mcp.server.subscriptions import InMemorySubscriptionBus, ToolsListChanged
|
||||
|
||||
The bus carries typed `ServerEvent` values — four small dataclasses — never JSON-RPC. Stamping, filtering, and stream lifecycles stay in the SDK, so a bus implementation cannot break the protocol; it can only move events between processes. To publish from outside a request, keep a reference to the bus you constructed and `await bus.publish(ToolsListChanged())` — the server holds the same instance.
|
||||
bus = InMemorySubscriptionBus()
|
||||
mcp = MCPServer("Sprint Board", subscriptions=bus)
|
||||
|
||||
|
||||
async def tools_reloaded() -> None:
|
||||
await bus.publish(ToolsListChanged()) # from a lifespan task, a webhook, anywhere
|
||||
```
|
||||
|
||||
## The low-level composition
|
||||
|
||||
Down on the low-level `Server` there is no pre-wired anything — and the same parts assemble in three lines:
|
||||
Down on the low-level `Server` there is no pre-wired anything, and the same parts assemble in three lines:
|
||||
|
||||
```python title="server.py" hl_lines="9 31 39"
|
||||
```python title="server.py" hl_lines="9-10 48"
|
||||
--8<-- "docs_src/subscriptions/tutorial002.py"
|
||||
```
|
||||
|
||||
* You own the bus, so you publish to it directly: `await bus.publish(ResourceUpdated(uri=...))`. Put it wherever your handlers can reach it — module scope here, the lifespan in a bigger app.
|
||||
* `ListenHandler(bus)` is the same handler `MCPServer` registers; `on_subscriptions_listen=` is an ordinary handler slot. Don't want the SDK's semantics? Write your own handler for the slot — the spec obligations come with it.
|
||||
* `ListenHandler.close()` gracefully ends every open stream: each one receives the listen request's result as its final frame, the spec's signal that the server ended the subscription deliberately — a clean end, as opposed to the abrupt drop a client may treat as a cue to reconnect. Without it, streams end when the client disconnects.
|
||||
* You own the bus, so you publish to it directly: `await bus.publish(ResourceUpdated(uri=...))`. Put it wherever your handlers can reach it: module scope here, the lifespan in a bigger app.
|
||||
* `ListenHandler(bus)` is the same handler `MCPServer` registers, and `on_subscriptions_listen=` is an ordinary handler slot. Put your own callable in that slot for different semantics, and the spec obligations move to you: acknowledge first, stamp every frame with the subscription id, deliver nothing outside the filter.
|
||||
* `ListenHandler.close()` ends every open stream gracefully. Each one receives the listen request's result as its final frame, which is the spec's way of saying the server ended the subscription deliberately. It returns before those streams finish flushing, so give them a moment before you tear the transport down. Without it, streams end when the client disconnects.
|
||||
|
||||
## Recap
|
||||
|
||||
* A client opts in with one `subscriptions/listen` request; the response is the stream. There is nothing to configure server-side — serving it is built in.
|
||||
* You publish: `await ctx.notify_resource_updated(uri)`, `notify_tools_changed()`, `notify_prompts_changed()`, `notify_resources_changed()`. Idle servers make these free.
|
||||
* Streams receive only what their filter requested; URIs match exactly; nothing is replayed.
|
||||
* Scaling out means implementing `SubscriptionBus` — two methods — over your own pub/sub, and passing it as `MCPServer(subscriptions=...)`.
|
||||
* The low-level spelling is the same machinery held in your hands: a bus, `ListenHandler(bus)`, one constructor argument.
|
||||
* A client opts in with one `subscriptions/listen` request, and the response is the stream. Serving it is built in.
|
||||
* You publish with `ctx.notify_*`, and the SDK does the stamping, filtering, and lifecycle work.
|
||||
* Events are cues, not payloads. Both ends refetch.
|
||||
* The client end is `async with client.listen(...)`: **[Subscriptions](../client/subscriptions.md)** under *Clients* is that story.
|
||||
* On the low-level `Server` you assemble the same parts yourself: a bus, `ListenHandler(bus)`, the `on_subscriptions_listen` slot.
|
||||
* Scaling out means implementing `SubscriptionBus`, two methods, and passing it as `MCPServer(subscriptions=...)`.
|
||||
|
||||
Running the server that serves all this, behind one replica or twenty, is **[Deploy & scale](../run/deploy.md)**.
|
||||
|
|
|
|||
Loading…
Reference in a new issue