Connect the subscription examples over HTTP

Real clients connect over streamable HTTP (or stdio, once served); the
in-memory client is a maintainer tool for tests and stays there. The examples
now construct Client("http://localhost:8000/mcp") themselves, and the tests
drive the example functions through an in-memory client instead of main().

Author: maxisbey

docs/handlers/subscriptions.md

@@ -50,29 +50,21 @@ Two things the stream is *not*:
     its content. To narrow that, serve the method with your own handler on the low-level
     `Server` and acknowledge a smaller filter than the client asked for.
 
-!!! warning "Not every transport serves the stream"
-    `subscriptions/listen` needs a transport that can stream a request's response: streamable
-    HTTP, or the in-process `Client(server)` the examples below use. Over stdio (and other
-    stream-pair transports) a 2026-07-28 connection rejects it with METHOD_NOT_FOUND, even
-    though `server/discover` still advertises the subscription capabilities there. The
-    open-stream semantics haven't been built for that transport yet.
+!!! warning "Streamable HTTP only, for now"
+    `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.
 
 ## Watching the stream
 
 On the client, a subscription is one context manager. Entering it sends the request and waits for the server's acknowledgment, so the stream is live by the time the block starts.
 
-```python title="client.py" hl_lines="16 20 22"
+```python title="client.py" hl_lines="16 19 29"
 --8<-- "docs_src/subscriptions/tutorial003.py"
 ```
 
-The examples connect in-process with `Client(mcp)`. Against a running server, pass its URL:
-
-```python
-async def main() -> None:
-    async with Client("http://localhost:8000/mcp") as client:
-        await follow_board(client)
-```
-
 Iteration yields four typed events: `ToolsListChanged`, `PromptsListChanged`, `ResourcesListChanged`, and `ResourceUpdated(uri=...)`.
 
 An event says *what* changed, never *how*. That is why `follow_board` calls `read_resource` and `list_tools`: the event is a cue to refetch. Read `event.uri` rather than assuming which resource moved, because once you subscribe to any URI the client delivers every `ResourceUpdated` on the stream.
@@ -90,23 +82,23 @@ Two more properties of the handle:
 
 Open the subscription first, then start the watcher and get on with your work.
 
-`app.py` imports `mcp` and `read_board` from the two files above, which live on disk as `tutorial001.py` and `tutorial003.py`. If you save the three side by side instead, drop the leading dot from those imports.
+`app.py` imports `BOARD` and `read_board` from `client.py` above. If you save the files side by side rather than as a package, drop the leading dot from that import.
 
 === "asyncio"
 
-    ```python title="app.py" hl_lines="20 22"
+    ```python title="app.py" hl_lines="18 20"
     --8<-- "docs_src/subscriptions/tutorial004_asyncio.py"
     ```
 
 === "trio"
 
-    ```python title="app.py" hl_lines="20 23"
+    ```python title="app.py" hl_lines="18 21"
     --8<-- "docs_src/subscriptions/tutorial004_trio.py"
     ```
 
 === "anyio"
 
-    ```python title="app.py" hl_lines="20 23"
+    ```python title="app.py" hl_lines="18 21"
     --8<-- "docs_src/subscriptions/tutorial004_anyio.py"
     ```
 

docs_src/subscriptions/tutorial003.py

@@ -23,3 +23,8 @@ async def follow_board(client: Client) -> None:
                     print("tools:", [tool.name for tool in tools.tools])
                 case _:
                     pass  # kinds the filter did not ask for never arrive
+
+
+async def main() -> None:
+    async with Client("http://localhost:8000/mcp") as client:
+        await follow_board(client)

docs_src/subscriptions/tutorial004_anyio.py

@@ -3,26 +3,29 @@
 from mcp import Client
 from mcp.client.subscriptions import Subscription
 
-from .tutorial001 import mcp
-from .tutorial003 import read_board
+from .tutorial003 import BOARD, 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
+            return  # sprint finished: the stream closes when run_sprint leaves the block
+
+
+async def run_sprint(client: Client) -> None:
+    async with client.listen(resource_subscriptions=[BOARD]) 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})
 
 
 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})
+    async with Client("http://localhost:8000/mcp") as client:
+        await run_sprint(client)
 
 
 if __name__ == "__main__":

docs_src/subscriptions/tutorial004_asyncio.py

@@ -3,26 +3,29 @@
 from mcp import Client
 from mcp.client.subscriptions import Subscription
 
-from .tutorial001 import mcp
-from .tutorial003 import read_board
+from .tutorial003 import BOARD, 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
+            return  # sprint finished: the stream closes when run_sprint leaves the block
+
+
+async def run_sprint(client: Client) -> None:
+    async with client.listen(resource_subscriptions=[BOARD]) 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
 
 
 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
+    async with Client("http://localhost:8000/mcp") as client:
+        await run_sprint(client)
 
 
 if __name__ == "__main__":

docs_src/subscriptions/tutorial004_trio.py

@@ -3,26 +3,29 @@
 from mcp import Client
 from mcp.client.subscriptions import Subscription
 
-from .tutorial001 import mcp
-from .tutorial003 import read_board
+from .tutorial003 import BOARD, 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
+            return  # sprint finished: the stream closes when run_sprint leaves the block
+
+
+async def run_sprint(client: Client) -> None:
+    async with client.listen(resource_subscriptions=[BOARD]) 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})
 
 
 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})
+    async with Client("http://localhost:8000/mcp") as client:
+        await run_sprint(client)
 
 
 if __name__ == "__main__":

tests/docs_src/test_subscriptions.py

@@ -234,22 +234,27 @@ def _assert_snapshot_then_current_board(printed: str) -> None:
 
 
 async def test_the_asyncio_watcher_runs_beside_the_main_flow(capsys: pytest.CaptureFixture[str]) -> None:
-    """tutorial004 (asyncio tab): main() opens the subscription, snapshots the board, then a watcher
-    task reprints it while main() keeps calling tools."""
-    await tutorial004_asyncio.main()
+    """tutorial004 (asyncio tab): run_sprint opens the subscription, snapshots the board, then a watcher
+    task reprints it while the main flow keeps calling tools.
+
+    The example connects over HTTP; the in-memory client here is the maintainer-side stand-in."""
+    async with Client(tutorial001.mcp) as client:
+        await tutorial004_asyncio.run_sprint(client)
     _assert_snapshot_then_current_board(capsys.readouterr().out)
 
 
 @pytest.mark.parametrize("anyio_backend", [pytest.param("trio", id="trio")])
 async def test_the_trio_watcher_runs_beside_the_main_flow(capsys: pytest.CaptureFixture[str]) -> None:
     """tutorial004 (trio tab): the same shape as the asyncio tab, with a nursery owning the watcher."""
-    await tutorial004_trio.main()
+    async with Client(tutorial001.mcp) as client:
+        await tutorial004_trio.run_sprint(client)
     _assert_snapshot_then_current_board(capsys.readouterr().out)
 
 
 async def test_the_anyio_watcher_runs_beside_the_main_flow(capsys: pytest.CaptureFixture[str]) -> None:
     """tutorial004 (anyio tab): the same shape again, with a task group owning the watcher."""
-    await tutorial004_anyio.main()
+    async with Client(tutorial001.mcp) as client:
+        await tutorial004_anyio.run_sprint(client)
     _assert_snapshot_then_current_board(capsys.readouterr().out)