Refresh the first page when draining paginated listings

The SEP-2549 response cache (2026-07-28) can serve a list verb's first
page from cache, while continuation pages always go to the wire. A drain
that started from a cached first page would pair that page's stale cursor
with freshly fetched later pages and return a listing the server never
served, which is the same silent-wrong-list failure the drains exist to
prevent.

The four list_all_* / iter_all_* pairs now take cache_mode and default it
to "refresh" rather than inheriting the single-page "use", so a drain
always starts from a current first page. "refresh" still writes that page
back to the cache, so single-page callers keep the freshness-hint benefit.
Pass cache_mode="use" to accept a cached first page instead.

The existing drain tests run with mode="legacy", where the ttlMs hint is
stripped on the wire and nothing is ever cached, so the two new tests run
on the default 2026-07-28 path.

AI disclosure: developed with AI assistance (Claude, Opus 5).

Author: CJGjr

docs/advanced/pagination.md

@@ -71,6 +71,27 @@ That loop is the same one in every client that pages, so `Client` ships it. The
     repeats. A repeated cursor is a broken server, and a loud failure beats a silent hang or a
     half-read list.
 
+### Drains and the response cache
+
+A server may attach a `ttlMs` freshness hint to a list result (**[Caching](../client/caching.md)**), and the
+client will serve a later `list_*` call for that method from cache instead of going back to the
+server. Only the first page is ever cached; a call carrying a cursor always goes to the wire.
+
+That split matters for a drain. If it started from a cached first page, it would take that
+page's `next_cursor` — minted against a listing that may since have changed — and pair it with
+freshly fetched later pages, returning a stitched-together listing the server never served. So
+the drains default to `cache_mode="refresh"`: the first page is re-fetched, and the fresh copy
+is written back to the cache for later single-page callers.
+
+```python
+async def list_the_tools(client: Client) -> None:
+    fresh = await client.list_all_tools()  # re-fetches the first page: always current
+    saved = await client.list_all_tools(cache_mode="use")  # one fewer request, may be stale
+```
+
+Pass `cache_mode="use"` when you would rather have the saved copy than the current one. The
+single-page `list_*` methods still default to `"use"`, unchanged.
+
 ## 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.

src/mcp/client/client.py

@@ -964,20 +964,31 @@ async def list_tools(
             ),
         )
 
-    async def iter_all_tools(self, *, meta: RequestParamsMeta | None = None) -> AsyncIterator[Tool]:
+    async def iter_all_tools(
+        self, *, meta: RequestParamsMeta | None = None, cache_mode: CacheMode = "refresh"
+    ) -> AsyncIterator[Tool]:
         """Yield every tool from the server, paging through `next_cursor`.
 
         Useful for streaming consumers that want to process tools without
         materializing the full list in memory.
 
+        Args:
+            meta: Additional metadata for the request.
+            cache_mode: Cache behavior for the first page (see `CacheMode`).
+                Defaults to `"refresh"`, unlike the single-page `list_tools`:
+                continuation pages bypass the cache unconditionally, so a
+                cached first page would pair a stale cursor with freshly
+                fetched later pages and silently return a listing the server
+                never served. Pass `"use"` to accept a cached first page.
+
         Raises:
             RuntimeError: The server returned a pagination cursor it already
                 returned, which would page forever.
         """
         seen_cursors: set[str] = set()
         cursor: str | None = None
         while True:
-            result = await self.list_tools(cursor=cursor, meta=meta)
+            result = await self.list_tools(cursor=cursor, meta=meta, cache_mode=cache_mode)
             for tool in result.tools:
                 yield tool
             if result.next_cursor is None:
@@ -987,30 +998,44 @@ async def iter_all_tools(self, *, meta: RequestParamsMeta | None = None) -> Asyn
             seen_cursors.add(result.next_cursor)
             cursor = result.next_cursor
 
-    async def list_all_tools(self, *, meta: RequestParamsMeta | None = None) -> list[Tool]:
+    async def list_all_tools(
+        self, *, meta: RequestParamsMeta | None = None, cache_mode: CacheMode = "refresh"
+    ) -> list[Tool]:
         """List every tool from the server, draining `next_cursor` across pages.
 
         Unlike `list_tools`, which returns one page, this walks pagination
         until the server reports no further pages and returns the combined
         list.
 
+        Args:
+            meta: Additional metadata for the request.
+            cache_mode: Cache behavior for the first page (see
+                `iter_all_tools`); defaults to `"refresh"`.
+
         Raises:
             RuntimeError: The server returned a pagination cursor it already
                 returned, which would page forever.
         """
-        return [tool async for tool in self.iter_all_tools(meta=meta)]
+        return [tool async for tool in self.iter_all_tools(meta=meta, cache_mode=cache_mode)]
 
-    async def iter_all_prompts(self, *, meta: RequestParamsMeta | None = None) -> AsyncIterator[Prompt]:
+    async def iter_all_prompts(
+        self, *, meta: RequestParamsMeta | None = None, cache_mode: CacheMode = "refresh"
+    ) -> AsyncIterator[Prompt]:
         """Yield every prompt from the server, paging through `next_cursor`.
 
+        Args:
+            meta: Additional metadata for the request.
+            cache_mode: Cache behavior for the first page (see
+                `iter_all_tools`); defaults to `"refresh"`.
+
         Raises:
             RuntimeError: The server returned a pagination cursor it already
                 returned, which would page forever.
         """
         seen_cursors: set[str] = set()
         cursor: str | None = None
         while True:
-            result = await self.list_prompts(cursor=cursor, meta=meta)
+            result = await self.list_prompts(cursor=cursor, meta=meta, cache_mode=cache_mode)
             for prompt in result.prompts:
                 yield prompt
             if result.next_cursor is None:
@@ -1020,26 +1045,40 @@ async def iter_all_prompts(self, *, meta: RequestParamsMeta | None = None) -> As
             seen_cursors.add(result.next_cursor)
             cursor = result.next_cursor
 
-    async def list_all_prompts(self, *, meta: RequestParamsMeta | None = None) -> list[Prompt]:
+    async def list_all_prompts(
+        self, *, meta: RequestParamsMeta | None = None, cache_mode: CacheMode = "refresh"
+    ) -> list[Prompt]:
         """List every prompt from the server, draining `next_cursor` across pages.
 
+        Args:
+            meta: Additional metadata for the request.
+            cache_mode: Cache behavior for the first page (see
+                `iter_all_tools`); defaults to `"refresh"`.
+
         Raises:
             RuntimeError: The server returned a pagination cursor it already
                 returned, which would page forever.
         """
-        return [prompt async for prompt in self.iter_all_prompts(meta=meta)]
+        return [prompt async for prompt in self.iter_all_prompts(meta=meta, cache_mode=cache_mode)]
 
-    async def iter_all_resources(self, *, meta: RequestParamsMeta | None = None) -> AsyncIterator[Resource]:
+    async def iter_all_resources(
+        self, *, meta: RequestParamsMeta | None = None, cache_mode: CacheMode = "refresh"
+    ) -> AsyncIterator[Resource]:
         """Yield every resource from the server, paging through `next_cursor`.
 
+        Args:
+            meta: Additional metadata for the request.
+            cache_mode: Cache behavior for the first page (see
+                `iter_all_tools`); defaults to `"refresh"`.
+
         Raises:
             RuntimeError: The server returned a pagination cursor it already
                 returned, which would page forever.
         """
         seen_cursors: set[str] = set()
         cursor: str | None = None
         while True:
-            result = await self.list_resources(cursor=cursor, meta=meta)
+            result = await self.list_resources(cursor=cursor, meta=meta, cache_mode=cache_mode)
             for resource in result.resources:
                 yield resource
             if result.next_cursor is None:
@@ -1049,28 +1088,40 @@ async def iter_all_resources(self, *, meta: RequestParamsMeta | None = None) ->
             seen_cursors.add(result.next_cursor)
             cursor = result.next_cursor
 
-    async def list_all_resources(self, *, meta: RequestParamsMeta | None = None) -> list[Resource]:
+    async def list_all_resources(
+        self, *, meta: RequestParamsMeta | None = None, cache_mode: CacheMode = "refresh"
+    ) -> list[Resource]:
         """List every resource from the server, draining `next_cursor` across pages.
 
+        Args:
+            meta: Additional metadata for the request.
+            cache_mode: Cache behavior for the first page (see
+                `iter_all_tools`); defaults to `"refresh"`.
+
         Raises:
             RuntimeError: The server returned a pagination cursor it already
                 returned, which would page forever.
         """
-        return [resource async for resource in self.iter_all_resources(meta=meta)]
+        return [resource async for resource in self.iter_all_resources(meta=meta, cache_mode=cache_mode)]
 
     async def iter_all_resource_templates(
-        self, *, meta: RequestParamsMeta | None = None
+        self, *, meta: RequestParamsMeta | None = None, cache_mode: CacheMode = "refresh"
     ) -> AsyncIterator[ResourceTemplate]:
         """Yield every resource template from the server, paging through `next_cursor`.
 
+        Args:
+            meta: Additional metadata for the request.
+            cache_mode: Cache behavior for the first page (see
+                `iter_all_tools`); defaults to `"refresh"`.
+
         Raises:
             RuntimeError: The server returned a pagination cursor it already
                 returned, which would page forever.
         """
         seen_cursors: set[str] = set()
         cursor: str | None = None
         while True:
-            result = await self.list_resource_templates(cursor=cursor, meta=meta)
+            result = await self.list_resource_templates(cursor=cursor, meta=meta, cache_mode=cache_mode)
             for template in result.resource_templates:
                 yield template
             if result.next_cursor is None:
@@ -1080,14 +1131,21 @@ async def iter_all_resource_templates(
             seen_cursors.add(result.next_cursor)
             cursor = result.next_cursor
 
-    async def list_all_resource_templates(self, *, meta: RequestParamsMeta | None = None) -> list[ResourceTemplate]:
+    async def list_all_resource_templates(
+        self, *, meta: RequestParamsMeta | None = None, cache_mode: CacheMode = "refresh"
+    ) -> list[ResourceTemplate]:
         """List every resource template from the server, draining `next_cursor` across pages.
 
+        Args:
+            meta: Additional metadata for the request.
+            cache_mode: Cache behavior for the first page (see
+                `iter_all_tools`); defaults to `"refresh"`.
+
         Raises:
             RuntimeError: The server returned a pagination cursor it already
                 returned, which would page forever.
         """
-        return [template async for template in self.iter_all_resource_templates(meta=meta)]
+        return [template async for template in self.iter_all_resource_templates(meta=meta, cache_mode=cache_mode)]
 
     @deprecated("The roots capability is deprecated as of 2026-07-28 (SEP-2577).", category=MCPDeprecationWarning)
     async def send_roots_list_changed(self) -> None:

tests/client/test_list_all_pagination.py

@@ -306,3 +306,72 @@ async def test_drain_raises_when_cursors_cycle():
     async with Client(server) as client:
         with pytest.raises(RuntimeError, match="already returned"):
             await client.list_all_tools()
+
+
+# ---- interaction with the SEP-2549 response cache --------------------------
+#
+# These run on the default (2026-07-28) client path rather than `mode="legacy"`
+# used above: `ttlMs` is a 2026-07-28 field, so the legacy wire path strips the
+# server's freshness hint and nothing is ever cached.
+
+
+def _relisting_tools_server(state: dict[str, int]) -> Server[Any]:
+    """Build a server whose tool listing is replaced when `state["version"]` flips to 2.
+
+    Version 1 serves [a, b] with cursor "1"; version 2 serves [x, y] -> [z].
+    Version 2 still honors version 1's cursor, so a drain that starts from a
+    stale first page gets a plausible answer rather than an error. Both tests
+    flip to version 2 before draining, so version 1 only ever serves page one.
+    """
+    # A freshness hint is what makes the client cache the first page at all (SEP-2549).
+    hint: dict[str, Any] = {"ttl_ms": 60_000, "cache_scope": "private"}
+
+    async def handle_list_tools(
+        _ctx: ServerRequestContext, params: types.PaginatedRequestParams | None
+    ) -> types.ListToolsResult:
+        cursor = params.cursor if params else None
+        if state["version"] == 1:
+            assert cursor is None
+            return types.ListToolsResult(tools=[_make_tool("a"), _make_tool("b")], next_cursor="1", **hint)
+        if cursor is None:
+            return types.ListToolsResult(tools=[_make_tool("x"), _make_tool("y")], next_cursor="2", **hint)
+        if cursor == "1":  # version 1's cursor, carried over on a stale first page
+            return types.ListToolsResult(tools=[_make_tool("c")], **hint)
+        assert cursor == "2"
+        return types.ListToolsResult(tools=[_make_tool("z")], **hint)
+
+    return Server("relisting-tools", on_list_tools=handle_list_tools)
+
+
+async def test_drain_refetches_a_cached_first_page():
+    """A drain returns the current listing even when the first page is already cached.
+
+    Continuation pages bypass the response cache, so serving a cached first page
+    would pair its stale cursor with freshly fetched later pages and return a
+    listing the server never served. SDK-defined: the drains default to
+    `cache_mode="refresh"` to avoid that.
+    """
+    state = {"version": 1}
+    server = _relisting_tools_server(state)
+
+    async with Client(server) as client:
+        await client.list_tools()  # caches page 0 of the first listing
+        state["version"] = 2
+
+        assert [t.name for t in await client.list_all_tools()] == ["x", "y", "z"]
+
+
+async def test_drain_reuses_a_cached_first_page_when_asked():
+    """`cache_mode="use"` opts back into serving the drain's first page from cache.
+
+    SDK-defined escape hatch: the caller accepts a stale first page (and the
+    stale cursor it carries) in exchange for one fewer request.
+    """
+    state = {"version": 1}
+    server = _relisting_tools_server(state)
+
+    async with Client(server) as client:
+        await client.list_tools()  # caches page 0 of the first listing
+        state["version"] = 2
+
+        assert [t.name for t in await client.list_all_tools(cache_mode="use")] == ["a", "b", "c"]