Document the drain helpers in the pagination guide

Add a Draining in one call section to docs/advanced/pagination.md covering
list_all_*/iter_all_*, the ClientSessionGroup behavior, and the
non-advancing cursor guard. Backed by a runnable tutorial003 snippet and
matching tests, in keeping with the page proving every claim.

Author: CJGjr

docs/advanced/pagination.md

@@ -50,6 +50,26 @@ Run its `main()` and it prints `100 resources`: ten pages of ten, stitched toget
 
 This is the same loop **[The Client](../client/index.md)** chapter showed you, and it costs nothing against a server that doesn't page: `next_cursor` is `None` on the first response and the loop runs once.
 
+## Draining in one call
+
+That loop is the same one in every client that pages, so `Client` ships it. The server here is the bookshop from before; only the client changed:
+
+```python title="client.py" hl_lines="27 31"
+--8<-- "docs_src/pagination/tutorial003.py"
+```
+
+* `list_all_resources()` walks `next_cursor` for you and hands back every page stitched into one list. There is one per pageable list: `list_all_tools`, `list_all_prompts`, `list_all_resources`, `list_all_resource_templates`.
+* `iter_all_resources()` yields one resource at a time and only fetches the next page when you ask for it, so you can stop early without dragging down the whole catalog. Same four: `iter_all_tools`, `iter_all_prompts`, and so on.
+* The single-page `list_*` methods are unchanged. Use them when you want one page and the cursor; use the drains when you want everything and don't want to own the loop.
+
+`ClientSessionGroup` aggregation drains the same way, so a group fronting several servers reports the full collection instead of each server's first page. That aggregator is **[Session groups](session-groups.md)**.
+
+!!! warning
+    A drain trusts the server to advance the cursor. A server that keeps returning the same
+    `next_cursor` it was handed would page forever, so the drains stop and raise `RuntimeError`
+    the moment a cursor fails to move. A page that does not advance is a broken server, and a
+    loud failure beats a silent hang or a half-read list.
+
 ## The three rules
 
 **Cursors are opaque.** A client must never parse, build, or guess one. The only legal source of a cursor is the previous page's `next_cursor`, verbatim.

docs_src/pagination/tutorial003.py

@@ -0,0 +1,33 @@
+from typing import Any
+
+from mcp_types import ListResourcesResult, PaginatedRequestParams, Resource
+
+from mcp import Client
+from mcp.server import Server, ServerRequestContext
+
+BOOKS = [f"book-{n}" for n in range(1, 101)]
+
+PAGE_SIZE = 10
+
+
+async def list_books(ctx: ServerRequestContext[Any], params: PaginatedRequestParams | None) -> ListResourcesResult:
+    start = 0 if params is None or params.cursor is None else int(params.cursor)
+    end = start + PAGE_SIZE
+    page = [Resource(uri=f"books://catalog/{name}", name=name) for name in BOOKS[start:end]]
+    next_cursor = str(end) if end < len(BOOKS) else None
+    return ListResourcesResult(resources=page, next_cursor=next_cursor)
+
+
+server = Server("Bookshop", on_list_resources=list_books)
+
+
+async def main() -> None:
+    async with Client(server) as client:
+        # Every page, stitched into one list.
+        resources = await client.list_all_resources()
+        print(f"{len(resources)} resources")
+
+        # Or stream them, and stop as soon as you have what you need.
+        async for resource in client.iter_all_resources():
+            print(f"first: {resource.name}")
+            break

tests/docs_src/test_pagination.py

@@ -3,7 +3,7 @@
 import pytest
 from mcp_types import Resource
 
-from docs_src.pagination import tutorial001, tutorial002
+from docs_src.pagination import tutorial001, tutorial002, tutorial003
 from mcp import Client, MCPError
 from mcp.server import MCPServer
 from mcp.server.mcpserver.resources import TextResource
@@ -71,6 +71,21 @@ async def test_the_client_program_on_the_page_runs(capsys: pytest.CaptureFixture
     assert capsys.readouterr().out == "100 resources\n"
 
 
+async def test_list_all_stitches_the_whole_catalog() -> None:
+    """tutorial003: `list_all_resources` drains every page into one list, no cursor handling."""
+    async with Client(tutorial003.server) as client:
+        resources = await client.list_all_resources()
+        assert len(resources) == 100
+        assert resources[0].name == "book-1"
+        assert resources[-1].name == "book-100"
+
+
+async def test_the_drain_helpers_program_runs(capsys: pytest.CaptureFixture[str]) -> None:
+    """tutorial003: `main()` stitches all pages, then streams and stops at the first."""
+    await tutorial003.main()
+    assert capsys.readouterr().out == "100 resources\nfirst: book-1\n"
+
+
 async def test_an_invented_cursor_is_an_error() -> None:
     """Cursors are opaque: a string the server never minted blows up inside the handler."""
     async with Client(tutorial001.server) as client: