Rewrite the subscriptions docs around a worked example

Replace the notes domain with a task board whose text rendering makes 'the
event is a cue, refetch to see what changed' visible in the output. Add a
client-side walkthrough: follow the stream and act on events, run a watcher
beside the main flow (asyncio, trio and anyio tabs), and keep it alive across
stream endings.

Corrections found while writing:

- sub.honored echoes every kind MCPServer was asked for, so the page no longer
  claims an unsupported kind is dropped from it.
- The lowlevel example published resource updates for a resource it never
  served, and did not keep a handle on its ListenHandler.
- The watcher tabs previously blocked on an Event the watcher set after
  subscribing, which deadlocked if listen() raised. Opening the subscription in
  main() and handing the handle to the task removes the deadlock and the
  machinery both.
- The client admits any resource update once URI subscriptions are honored, so
  the page tells readers to dispatch on event.uri.
- Unconsumed events coalesce only when identical, and a consumer that falls
  1024 events behind loses the subscription. Both are now stated.

Also: no em-dashes, shorter paragraphs, and a heading for the server half, to
match the other handler pages.

Author: maxisbey

docs/handlers/subscriptions.md

@@ -2065,8 +2065,8 @@ One behavioral caveat when moving progress-reporting handlers onto `Client(serve
 They keep working against 2025-era servers; a 2026-07-28 server answers them with `-32601` (method not found). Migrate to the listen driver:
 
 ```python
-async with client.listen(resource_subscriptions=["note://todo"]) as sub:
-    async for event in sub:  # ResourceUpdated(uri="note://todo")
+async with client.listen(resource_subscriptions=["board://sprint"]) as sub:
+    async for event in sub:  # ResourceUpdated(uri="board://sprint")
         ...
 ```
 

docs/migration.md

@@ -1,28 +1,33 @@
 from mcp.server.mcpserver import Context, MCPServer
 
-mcp = MCPServer("Notebook")
+mcp = MCPServer("Sprint Board")
 
-NOTES = {"todo": "buy milk", "journal": "day one"}
+BOARDS = {
+    "sprint": {"design": False, "build": False, "ship": False},
+    "backlog": {"tidy docs": False},
+}
 
 
-@mcp.resource("note://{name}")
-def note(name: str) -> str:
-    return NOTES[name]
+@mcp.resource("board://{name}")
+def board(name: str) -> str:
+    tasks = BOARDS[name]
+    return "\n".join(f"[{'x' if done else ' '}] {task}" for task, done in tasks.items())
 
 
 @mcp.tool()
-async def edit_note(name: str, text: str, ctx: Context) -> str:
-    NOTES[name] = text
-    await ctx.notify_resource_updated(f"note://{name}")
-    return "saved"
+async def complete_task(board: str, task: str, ctx: Context) -> str:
+    BOARDS[board][task] = True
+    await ctx.notify_resource_updated(f"board://{board}")
+    return f"{task}: done"
 
 
-def search(query: str) -> list[str]:
-    return [name for name, text in NOTES.items() if query in text]
+def sprint_report() -> str:
+    done = sum(done for tasks in BOARDS.values() for done in tasks.values())
+    return f"{done} task(s) done"
 
 
 @mcp.tool()
-async def enable_search(ctx: Context) -> str:
-    mcp.add_tool(search)
+async def enable_reports(ctx: Context) -> str:
+    mcp.add_tool(sprint_report)
     await ctx.notify_tools_changed()
-    return "search is live"
+    return "reporting is live"

docs_src/subscriptions/tutorial001.py

@@ -7,34 +7,43 @@
 from mcp.server.subscriptions import InMemorySubscriptionBus, ListenHandler, ResourceUpdated
 
 bus = InMemorySubscriptionBus()
+listen_handler = ListenHandler(bus)
 
-NOTES = {"todo": "buy milk"}
+BOARD = {"design": False, "build": False}
 
-EDIT_NOTE_SCHEMA: dict[str, Any] = {
+COMPLETE_TASK_SCHEMA: dict[str, Any] = {
     "type": "object",
-    "properties": {"name": {"type": "string"}, "text": {"type": "string"}},
-    "required": ["name", "text"],
+    "properties": {"task": {"type": "string"}},
+    "required": ["task"],
 }
 
 
+async def read_resource(
+    ctx: ServerRequestContext[Any], params: types.ReadResourceRequestParams
+) -> types.ReadResourceResult:
+    board = "\n".join(f"[{'x' if done else ' '}] {task}" for task, done in BOARD.items())
+    return types.ReadResourceResult(contents=[types.TextResourceContents(uri=params.uri, text=board)])
+
+
 async def list_tools(
     ctx: ServerRequestContext[Any], params: types.PaginatedRequestParams | None
 ) -> types.ListToolsResult:
     return types.ListToolsResult(
-        tools=[types.Tool(name="edit_note", description="Replace a note's text.", input_schema=EDIT_NOTE_SCHEMA)]
+        tools=[types.Tool(name="complete_task", description="Mark a task done.", input_schema=COMPLETE_TASK_SCHEMA)]
     )
 
 
 async def call_tool(ctx: ServerRequestContext[Any], params: types.CallToolRequestParams) -> types.CallToolResult:
     args = params.arguments or {}
-    NOTES[args["name"]] = args["text"]
-    await bus.publish(ResourceUpdated(uri=f"note://{args['name']}"))
-    return types.CallToolResult(content=[types.TextContent(type="text", text="saved")])
+    BOARD[args["task"]] = True
+    await bus.publish(ResourceUpdated(uri="board://sprint"))
+    return types.CallToolResult(content=[types.TextContent(type="text", text="done")])
 
 
 server = Server(
-    "notebook",
+    "sprint-board",
+    on_read_resource=read_resource,
     on_list_tools=list_tools,
     on_call_tool=call_tool,
-    on_subscriptions_listen=ListenHandler(bus),
+    on_subscriptions_listen=listen_handler,
 )

docs_src/subscriptions/tutorial002.py

@@ -1,14 +1,25 @@
+from mcp_types import TextResourceContents
+
 from mcp import Client
-from mcp.client.subscriptions import ResourceUpdated
+from mcp.client.subscriptions import ResourceUpdated, ToolsListChanged
+
+BOARD = "board://sprint"
+
 
-from .tutorial001 import mcp
+async def read_board(client: Client, uri: str = BOARD) -> str:
+    [contents] = (await client.read_resource(uri)).contents
+    assert isinstance(contents, TextResourceContents)
+    return contents.text
 
 
-async def watch_todo() -> str:
-    """Wait for the todo note to change once, then stop listening."""
-    async with Client(mcp) as client:
-        async with client.listen(resource_subscriptions=["note://todo"]) as sub:
-            async for event in sub:
-                assert isinstance(event, ResourceUpdated)
-                return f"changed: {event.uri}"
-    return "the server closed the stream before any change"
+async def follow_board(client: Client) -> None:
+    async with client.listen(tools_list_changed=True, resource_subscriptions=[BOARD]) as sub:
+        async for event in sub:
+            match event:
+                case ResourceUpdated(uri=uri):
+                    print(await read_board(client, uri))
+                case ToolsListChanged():
+                    tools = await client.list_tools()
+                    print("tools:", [tool.name for tool in tools.tools])
+                case _:
+                    pass  # kinds the filter did not ask for never arrive

docs_src/subscriptions/tutorial003.py

@@ -0,0 +1,29 @@
+import anyio
+
+from mcp import Client
+from mcp.client.subscriptions import Subscription
+
+from .tutorial001 import mcp
+from .tutorial003 import read_board
+
+
+async def watch(client: Client, sub: Subscription) -> None:
+    async for _event in sub:
+        board = await read_board(client)
+        print(board)
+        if "[ ]" not in board:
+            return  # sprint finished: the stream closes when main() leaves the block
+
+
+async def main() -> None:
+    async with Client(mcp) as client:
+        async with client.listen(resource_subscriptions=["board://sprint"]) as sub:
+            print(await read_board(client))  # snapshot: acknowledged, so nothing after this is missed
+            async with anyio.create_task_group() as tg:
+                tg.start_soon(watch, client, sub)
+                for task in ("design", "build", "ship"):
+                    await client.call_tool("complete_task", {"board": "sprint", "task": task})
+
+
+if __name__ == "__main__":
+    anyio.run(main)

docs_src/subscriptions/tutorial004.py

@@ -0,0 +1,29 @@
+import asyncio
+
+from mcp import Client
+from mcp.client.subscriptions import Subscription
+
+from .tutorial001 import mcp
+from .tutorial003 import read_board
+
+
+async def watch(client: Client, sub: Subscription) -> None:
+    async for _event in sub:
+        board = await read_board(client)
+        print(board)
+        if "[ ]" not in board:
+            return  # sprint finished: the stream closes when main() leaves the block
+
+
+async def main() -> None:
+    async with Client(mcp) as client:
+        async with client.listen(resource_subscriptions=["board://sprint"]) as sub:
+            print(await read_board(client))  # snapshot: acknowledged, so nothing after this is missed
+            watcher = asyncio.create_task(watch(client, sub))
+            for task in ("design", "build", "ship"):
+                await client.call_tool("complete_task", {"board": "sprint", "task": task})
+            await watcher  # returns once the watcher has seen the finished board
+
+
+if __name__ == "__main__":
+    asyncio.run(main())

docs_src/subscriptions/tutorial004_anyio.py

@@ -0,0 +1,29 @@
+import trio
+
+from mcp import Client
+from mcp.client.subscriptions import Subscription
+
+from .tutorial001 import mcp
+from .tutorial003 import read_board
+
+
+async def watch(client: Client, sub: Subscription) -> None:
+    async for _event in sub:
+        board = await read_board(client)
+        print(board)
+        if "[ ]" not in board:
+            return  # sprint finished: the stream closes when main() leaves the block
+
+
+async def main() -> None:
+    async with Client(mcp) as client:
+        async with client.listen(resource_subscriptions=["board://sprint"]) as sub:
+            print(await read_board(client))  # snapshot: acknowledged, so nothing after this is missed
+            async with trio.open_nursery() as nursery:
+                nursery.start_soon(watch, client, sub)
+                for task in ("design", "build", "ship"):
+                    await client.call_tool("complete_task", {"board": "sprint", "task": task})
+
+
+if __name__ == "__main__":
+    trio.run(main)

docs_src/subscriptions/tutorial004_asyncio.py

@@ -0,0 +1,20 @@
+import anyio
+
+from mcp import Client
+from mcp.client.subscriptions import SubscriptionLost
+
+from .tutorial003 import read_board
+
+
+async def keep_following(client: Client) -> None:
+    while True:
+        try:
+            async with client.listen(resource_subscriptions=["board://sprint"]) as sub:
+                print(await read_board(client))  # refetch: no replay across streams
+                async for _event in sub:
+                    print(await read_board(client))
+        except SubscriptionLost:
+            pass
+        # Either ending means the stream is gone. Back off before re-listening:
+        # a graceful close may be the server shedding load.
+        await anyio.sleep(1)