Serve subscriptions/listen with a pluggable event bus (SEP-2575) (#3035)

examples/servers/everything-server/mcp_everything_server/server.py

@@ -13,7 +13,7 @@ from typing import Annotated, Any
 import click
 from mcp.server import ServerRequestContext
 from mcp.server.mcpserver import Context, MCPServer, RequestStateSecurity
-from mcp.server.mcpserver.prompts.base import UserMessage
+from mcp.server.mcpserver.prompts.base import Prompt, UserMessage
 from mcp.server.streamable_http import EventCallback, EventMessage, EventStore
 from mcp.shared.exceptions import MCPError
 from mcp_types import (
@@ -585,6 +585,34 @@ async def test_reconnection(ctx: Context) -> str:
     return "Reconnection test completed"
 
 
+def _dynamic_tool() -> str:
+    """A tool registered and removed by test_trigger_tool_change."""
+    return "dynamic"
+
+
+def _dynamic_prompt() -> str:
+    """A prompt registered and removed by test_trigger_prompt_change."""
+    return "dynamic"
+
+
+@mcp.tool()
+async def test_trigger_tool_change(ctx: Context) -> str:
+    """Mutates the tool list and announces it to subscriptions/listen streams (SEP-2575)"""
+    mcp.add_tool(_dynamic_tool, name="test_dynamic_tool")
+    mcp.remove_tool("test_dynamic_tool")
+    await ctx.notify_tools_changed()
+    return "tool list changed"
+
+
+@mcp.tool()
+async def test_trigger_prompt_change(ctx: Context) -> str:
+    """Mutates the prompt list and announces it to subscriptions/listen streams (SEP-2575)"""
+    mcp.add_prompt(Prompt.from_function(_dynamic_prompt, name="test_dynamic_prompt", description="dynamic"))
+    mcp.remove_prompt("test_dynamic_prompt")
+    await ctx.notify_prompts_changed()
+    return "prompt list changed"
+
+
 # Resources
 @mcp.resource("test://static-text")
 def static_text_resource() -> str:

examples/stories/README.md

@@ -148,6 +148,7 @@ opens with a banner saying what replaces it.
 | [`starlette_mount`](starlette_mount/) | mounting `streamable_http_app()` under a Starlette/FastAPI sub-path | current |
 | [`sse_polling`](sse_polling/) | SEP-1699 `closeSSE()` + `Last-Event-ID` resume via `EventStore` | legacy |
 | [`standalone_get`](standalone_get/) | server-initiated `list_changed` over the sessionful GET stream | legacy |
+| [`subscriptions`](subscriptions/) | `subscriptions/listen` streams: `ctx.notify_*`, `SubscriptionBus`, `ListenHandler` | current |
 | [`reconnect`](reconnect/) | explicit `discover()`, persist `DiscoverResult`, zero-RTT reconnect | current |
 | [`bearer_auth`](bearer_auth/) | `TokenVerifier` + `AuthSettings` bearer gate, PRM metadata, `get_access_token()` | current |
 | [`oauth`](oauth/) | full `authorization_code` grant against an in-process AS | current |
@@ -155,7 +156,6 @@ opens with a banner saying what replaces it.
 | [`identity_assertion`](identity_assertion/) | SEP-990 enterprise IdP flow: present an ID-JAG under the `jwt-bearer` grant | current |
 | **— deferred (README only) —** | | |
 | [`caching`](caching/) | `CacheableResult` ttl/scope hints; client honouring | not yet implemented |
-| [`subscriptions`](subscriptions/) | `subscriptions/listen`, `ServerEventBus`, `Client.listen()` | not yet implemented — [#2901](https://github.com/modelcontextprotocol/python-sdk/issues/2901) |
 | [`tasks`](tasks/) | `io.modelcontextprotocol/tasks` extension | not yet implemented |
 | [`apps`](apps/) | MCP Apps: `ui://` resource + `_meta.ui` | not yet implemented — [#2896](https://github.com/modelcontextprotocol/python-sdk/issues/2896) |
 | [`skills`](skills/) | SEP-2640 skills extension | not yet implemented — [#2896](https://github.com/modelcontextprotocol/python-sdk/issues/2896) |

examples/stories/manifest.toml

@@ -68,6 +68,12 @@ lowlevel   = false
 transports = ["in-memory", "http-asgi"]
 era        = "dual-in-body"
 
+[story.subscriptions]
+# subscriptions/listen exists only on the 2026 wire, so there is no legacy leg.
+# The listen request parks for the stream's lifetime; the client ends it by
+# cancelling the awaiting scope (the spec's client-side close).
+era = "modern"
+
 [story.schema_validators]
 
 [story.middleware]
@@ -166,7 +172,6 @@ fixed_port    = 8000                            # issuer/PRM metadata bake in :8
 
 [deferred]
 caching       = "client honouring + per-result override unlanded"
-subscriptions = "#2901 — Client.listen / ServerEventBus"
 tasks         = "SEP-2663 — tasks extension runtime (server-decided augmentation, CreateTaskResult)"
 skills        = "#2896 — SEP-2640"
 events        = "#2901 + #2896"

examples/stories/subscriptions/README.md

@@ -1,27 +1,60 @@
 # subscriptions
 
-The 2026-era `subscriptions/listen` channel: the server publishes change events
-through a `ServerEventBus`, and `Client.listen()` opens an async iterator over
-them. Replaces the handshake-era `resources/subscribe` + standalone-GET
-notification path.
+Server-originated change notifications on the 2026-07-28 protocol. A client
+opens one `subscriptions/listen` request whose response **is** the stream; the
+server publishes with `ctx.notify_resource_updated(uri)` /
+`ctx.notify_tools_changed()` and the SDK does the wire work (ack-first,
+per-stream filtering, subscription-id tagging). Replaces the handshake-era
+`resources/subscribe` + standalone-GET notification path.
 
-**Status: not yet implemented** ([#2901](https://github.com/modelcontextprotocol/python-sdk/issues/2901)).
-The lowlevel registration surface is in this base —
-[#2967](https://github.com/modelcontextprotocol/python-sdk/pull/2967)
-(`ae13ede`) added the lowlevel `on_subscriptions_listen` handler slot — but
-there is no `Client.listen()` or `ServerEventBus` yet. The runnable story is
-deliberately a follow-up PR to keep this one reviewable.
+The client edits a note it did not subscribe to (silence), edits the one it
+did (a tagged `notifications/resources/updated`), registers a tool at runtime
+(`notifications/tools/list_changed`, then re-lists and calls it), and finally
+stops listening - cancelling the parked request releases the local task, and
+closing the connection ends the stream server-side.
+
+## Run it
+
+```bash
+# HTTP — the client self-hosts the server on a free port, runs, then tears it
+# down (subscriptions/listen is 2026-era only)
+uv run python -m stories.subscriptions.client --http
+# same, against the lowlevel-API server variant
+uv run python -m stories.subscriptions.client --http --server server_lowlevel
+```
+
+## What to look at
+
+- `client.py` — stream frames arrive as ordinary server notifications via the
+  constructor-only `message_handler=`. There is no client-side listen API yet,
+  so opening the stream drops to the `client.session` escape hatch; the request
+  parks for the stream's lifetime. Cancelling it releases the local task; over
+  HTTP the server-side stream ends when the connection closes. Every frame's
+  `_meta["io.modelcontextprotocol/subscriptionId"]` is the listen request's
+  JSON-RPC id.
+- `server.py` — publishing is one `await ctx.notify_*()` line per change; the
+  filter, the tagging, and the ack ordering are the SDK's job. Publishing with
+  no subscribers is a no-op.
+- `server_lowlevel.py` — the same machinery held by hand: an
+  `InMemorySubscriptionBus`, handlers that `await bus.publish(...)`, and
+  `ListenHandler(bus)` passed as `on_subscriptions_listen=`. A multi-replica
+  deployment swaps the bus for one backed by its own pub/sub
+  (`MCPServer(subscriptions=...)` on the high-level server).
+
+## Caveats
+
+- 2026-era only: on a 2025 connection the method does not exist (clients there
+  use `resources/subscribe` and unsolicited notifications instead), so the
+  story pins the modern era and has no legacy leg.
+- No replay: events published while no stream is open are not queued. The
+  contract after a dropped stream is re-listen and re-fetch.
 
 ## Spec
 
 [Subscriptions — basic utilities](https://modelcontextprotocol.io/specification/draft/basic/utilities/subscriptions)
 
-## Working example elsewhere
-
-The TypeScript SDK ships a runnable `subscriptions` story:
-[typescript-sdk/examples/subscriptions](https://github.com/modelcontextprotocol/typescript-sdk/tree/main/examples/subscriptions).
-
 ## See also
 
-`standalone_get/` (handshake-era server-initiated notifications), `resources/`
-(legacy `subscribe` deliberately omitted).
+`streaming/` (request-scoped notifications), `events/` (the events extension
+on top of this channel, deferred), and `docs/advanced/subscriptions.md` (the
+narrative version).

examples/stories/subscriptions/client.py

@@ -0,0 +1,97 @@
+"""Open a `subscriptions/listen` stream, watch one URI and the tool list, then close it."""
+
+import anyio
+import mcp_types as types
+
+from mcp.client import Client
+from stories._harness import Target, run_client
+
+SUBSCRIPTION_ID = "io.modelcontextprotocol/subscriptionId"
+
+
+async def main(target: Target, *, mode: str = "auto") -> None:
+    # Stream frames arrive as ordinary server notifications; `message_handler`
+    # is constructor-only on `Client`, so the list it fills exists first.
+    received: list[types.ServerNotification] = []
+    arrival = anyio.Event()
+
+    async def on_message(message: object) -> None:
+        nonlocal arrival
+        if isinstance(
+            message,
+            types.SubscriptionsAcknowledgedNotification
+            | types.ResourceUpdatedNotification
+            | types.ToolListChangedNotification,
+        ):
+            received.append(message)
+            arrival.set()
+            arrival = anyio.Event()
+
+    async def wait_for(count: int) -> None:
+        with anyio.fail_after(10):
+            while len(received) < count:
+                await arrival.wait()
+
+    async with Client(target, mode=mode, message_handler=on_message) as client:
+        before = await client.list_tools()
+        assert "search" not in {tool.name for tool in before.tools}
+
+        async with anyio.create_task_group() as tg:
+            # There is no client-side listen API yet, so the story drops to the
+            # `client.session` escape hatch. The request parks for the stream's
+            # lifetime, so it runs as a task; cancelling it releases the local
+            # awaiting scope. In-memory that also ends the server's stream; over
+            # HTTP today nothing aborts the POST, so the server-side stream ends
+            # when the connection closes (the `Client` exit right below).
+            async def listen() -> None:
+                request = types.SubscriptionsListenRequest(
+                    params=types.SubscriptionsListenRequestParams(
+                        notifications=types.SubscriptionFilter(
+                            tools_list_changed=True, resource_subscriptions=["note://todo"]
+                        )
+                    )
+                )
+                await client.session.send_request(request, types.SubscriptionsListenResult)
+
+            tg.start_soon(listen)
+
+            # ── the ack is the first frame: it echoes the honored filter, tagged ──
+            await wait_for(1)
+            ack = received[0]
+            assert isinstance(ack, types.SubscriptionsAcknowledgedNotification), ack
+            assert ack.params.notifications.tools_list_changed is True
+            assert ack.params.notifications.resource_subscriptions == ["note://todo"]
+            assert ack.params.meta is not None and SUBSCRIPTION_ID in ack.params.meta
+
+            # ── exact-URI filtering: an unsubscribed note edit stays silent ──
+            await client.call_tool("edit_note", {"name": "journal", "text": "day two"})
+            # ── the subscribed URI delivers, carrying the same subscription id ──
+            await client.call_tool("edit_note", {"name": "todo", "text": "water plants"})
+            await wait_for(2)
+            updated = received[1]
+            assert isinstance(updated, types.ResourceUpdatedNotification), updated
+            assert updated.params.uri == "note://todo"
+            assert updated.params.meta is not None
+            assert updated.params.meta[SUBSCRIPTION_ID] == ack.params.meta[SUBSCRIPTION_ID]
+            assert len(received) == 2, "the journal edit must not have been delivered"
+
+            # ── a runtime tool registration announces itself ──
+            await client.call_tool("enable_search", {})
+            await wait_for(3)
+            assert isinstance(received[2], types.ToolListChangedNotification), received[2]
+
+            # The client is done listening: cancel the parked request and let
+            # the connection teardown below end the stream server-side.
+            tg.cancel_scope.cancel()
+
+        # list_changed told us to re-fetch - the new tool is callable, and the
+        # session outlives the closed stream.
+        tools = await client.list_tools()
+        assert "search" in {tool.name for tool in tools.tools}
+        result = await client.call_tool("search", {"query": "water"})
+        content = result.content[0]
+        assert isinstance(content, types.TextContent) and content.text == "todo", result
+
+
+if __name__ == "__main__":
+    run_client(main)

examples/stories/subscriptions/server.py

@@ -0,0 +1,41 @@
+"""A notebook whose edits and tool changes reach `subscriptions/listen` streams."""
+
+from mcp.server.mcpserver import Context, MCPServer
+from stories._hosting import run_server_from_args
+
+
+def build_server() -> MCPServer:
+    mcp = MCPServer("subscriptions-example")
+    notes = {"todo": "buy milk", "journal": "day one"}
+
+    @mcp.resource("note://{name}")
+    def note(name: str) -> str:
+        return notes[name]
+
+    @mcp.tool()
+    async def edit_note(name: str, text: str, ctx: Context) -> str:
+        """Replace a note's text and tell subscribers that URI changed."""
+        notes[name] = text
+        await ctx.notify_resource_updated(f"note://{name}")
+        return "saved"
+
+    def search(query: str) -> list[str]:
+        return [name for name, text in notes.items() if query in text]
+
+    enabled = False
+
+    @mcp.tool()
+    async def enable_search(ctx: Context) -> str:
+        """Register the `search` tool at runtime and tell subscribers the list changed."""
+        nonlocal enabled
+        if not enabled:
+            enabled = True
+            mcp.add_tool(search)
+            await ctx.notify_tools_changed()
+        return "search is live"
+
+    return mcp
+
+
+if __name__ == "__main__":
+    run_server_from_args(build_server)

examples/stories/subscriptions/server_lowlevel.py

@@ -0,0 +1,72 @@
+"""The same notebook against the low-level Server: an explicit bus + ListenHandler."""
+
+from typing import Any
+
+import mcp_types as types
+
+from mcp.server.context import ServerRequestContext
+from mcp.server.lowlevel import Server
+from mcp.server.subscriptions import (
+    InMemorySubscriptionBus,
+    ListenHandler,
+    ResourceUpdated,
+    ToolsListChanged,
+)
+from stories._hosting import run_server_from_args
+
+EDIT_NOTE_SCHEMA: dict[str, Any] = {
+    "type": "object",
+    "properties": {"name": {"type": "string"}, "text": {"type": "string"}},
+    "required": ["name", "text"],
+}
+EMPTY_SCHEMA: dict[str, Any] = {"type": "object", "properties": {}}
+SEARCH_SCHEMA: dict[str, Any] = {
+    "type": "object",
+    "properties": {"query": {"type": "string"}},
+    "required": ["query"],
+}
+
+
+def build_server() -> Server[Any]:
+    # The bus lives wherever your handlers can reach it; the lifespan is the
+    # natural home in a bigger app. The closure is enough here.
+    bus = InMemorySubscriptionBus()
+    notes = {"todo": "buy milk", "journal": "day one"}
+    search_enabled = False
+
+    async def list_tools(
+        ctx: ServerRequestContext[Any], params: types.PaginatedRequestParams | None
+    ) -> types.ListToolsResult:
+        tools = [
+            types.Tool(name="edit_note", description="Replace a note's text.", input_schema=EDIT_NOTE_SCHEMA),
+            types.Tool(name="enable_search", description="Register the search tool.", input_schema=EMPTY_SCHEMA),
+        ]
+        if search_enabled:
+            tools.append(types.Tool(name="search", description="Find notes.", input_schema=SEARCH_SCHEMA))
+        return types.ListToolsResult(tools=tools)
+
+    async def call_tool(ctx: ServerRequestContext[Any], params: types.CallToolRequestParams) -> types.CallToolResult:
+        nonlocal search_enabled
+        args = params.arguments or {}
+        if params.name == "edit_note":
+            notes[args["name"]] = args["text"]
+            await bus.publish(ResourceUpdated(uri=f"note://{args['name']}"))
+            return types.CallToolResult(content=[types.TextContent(text="saved")])
+        if params.name == "enable_search":
+            search_enabled = True
+            await bus.publish(ToolsListChanged())
+            return types.CallToolResult(content=[types.TextContent(text="search is live")])
+        assert params.name == "search" and search_enabled
+        matches = [name for name, text in notes.items() if args["query"] in text]
+        return types.CallToolResult(content=[types.TextContent(text=", ".join(matches))])
+
+    return Server(
+        "subscriptions-example",
+        on_list_tools=list_tools,
+        on_call_tool=call_tool,
+        on_subscriptions_listen=ListenHandler(bus),
+    )
+
+
+if __name__ == "__main__":
+    run_server_from_args(build_server)