Guard the drain loops against a non-advancing cursor

A server that returns the same next_cursor it was given would make the
list_all_*/iter_all_* loops page forever. Raise RuntimeError when the
cursor does not advance instead of silently looping or truncating, and
document it in the Raises section of each helper. Covered by a
parametrized test across tools, prompts, resources, and templates.

Author: CJGjr

src/mcp/client/client.py

@@ -953,6 +953,9 @@ async def iter_all_tools(self, *, meta: RequestParamsMeta | None = None) -> Asyn
 
         Useful for streaming consumers that want to process tools without
         materializing the full list in memory.
+
+        Raises:
+            RuntimeError: The server returned a pagination cursor that did not advance.
         """
         cursor: str | None = None
         while True:
@@ -961,6 +964,10 @@ async def iter_all_tools(self, *, meta: RequestParamsMeta | None = None) -> Asyn
                 yield tool
             if result.next_cursor is None:
                 return
+            if result.next_cursor == cursor:
+                raise RuntimeError(
+                    "Server returned a pagination cursor that did not advance; refusing to page forever."
+                )
             cursor = result.next_cursor
 
     async def list_all_tools(self, *, meta: RequestParamsMeta | None = None) -> list[Tool]:
@@ -969,54 +976,93 @@ async def list_all_tools(self, *, meta: RequestParamsMeta | None = None) -> list
         Unlike `list_tools`, which returns one page, this walks pagination
         until the server reports no further pages and returns the combined
         list.
+
+        Raises:
+            RuntimeError: The server returned a pagination cursor that did not advance.
         """
         return [tool async for tool in self.iter_all_tools(meta=meta)]
 
     async def iter_all_prompts(self, *, meta: RequestParamsMeta | None = None) -> AsyncIterator[Prompt]:
-        """Yield every prompt from the server, paging through `next_cursor`."""
+        """Yield every prompt from the server, paging through `next_cursor`.
+
+        Raises:
+            RuntimeError: The server returned a pagination cursor that did not advance.
+        """
         cursor: str | None = None
         while True:
             result = await self.list_prompts(cursor=cursor, meta=meta)
             for prompt in result.prompts:
                 yield prompt
             if result.next_cursor is None:
                 return
+            if result.next_cursor == cursor:
+                raise RuntimeError(
+                    "Server returned a pagination cursor that did not advance; refusing to page forever."
+                )
             cursor = result.next_cursor
 
     async def list_all_prompts(self, *, meta: RequestParamsMeta | None = None) -> list[Prompt]:
-        """List every prompt from the server, draining `next_cursor` across pages."""
+        """List every prompt from the server, draining `next_cursor` across pages.
+
+        Raises:
+            RuntimeError: The server returned a pagination cursor that did not advance.
+        """
         return [prompt async for prompt in self.iter_all_prompts(meta=meta)]
 
     async def iter_all_resources(self, *, meta: RequestParamsMeta | None = None) -> AsyncIterator[Resource]:
-        """Yield every resource from the server, paging through `next_cursor`."""
+        """Yield every resource from the server, paging through `next_cursor`.
+
+        Raises:
+            RuntimeError: The server returned a pagination cursor that did not advance.
+        """
         cursor: str | None = None
         while True:
             result = await self.list_resources(cursor=cursor, meta=meta)
             for resource in result.resources:
                 yield resource
             if result.next_cursor is None:
                 return
+            if result.next_cursor == cursor:
+                raise RuntimeError(
+                    "Server returned a pagination cursor that did not advance; refusing to page forever."
+                )
             cursor = result.next_cursor
 
     async def list_all_resources(self, *, meta: RequestParamsMeta | None = None) -> list[Resource]:
-        """List every resource from the server, draining `next_cursor` across pages."""
+        """List every resource from the server, draining `next_cursor` across pages.
+
+        Raises:
+            RuntimeError: The server returned a pagination cursor that did not advance.
+        """
         return [resource async for resource in self.iter_all_resources(meta=meta)]
 
     async def iter_all_resource_templates(
         self, *, meta: RequestParamsMeta | None = None
     ) -> AsyncIterator[ResourceTemplate]:
-        """Yield every resource template from the server, paging through `next_cursor`."""
+        """Yield every resource template from the server, paging through `next_cursor`.
+
+        Raises:
+            RuntimeError: The server returned a pagination cursor that did not advance.
+        """
         cursor: str | None = None
         while True:
             result = await self.list_resource_templates(cursor=cursor, meta=meta)
             for template in result.resource_templates:
                 yield template
             if result.next_cursor is None:
                 return
+            if result.next_cursor == cursor:
+                raise RuntimeError(
+                    "Server returned a pagination cursor that did not advance; refusing to page forever."
+                )
             cursor = result.next_cursor
 
     async def list_all_resource_templates(self, *, meta: RequestParamsMeta | None = None) -> list[ResourceTemplate]:
-        """List every resource template from the server, draining `next_cursor` across pages."""
+        """List every resource template from the server, draining `next_cursor` across pages.
+
+        Raises:
+            RuntimeError: The server returned a pagination cursor that did not advance.
+        """
         return [template async for template in self.iter_all_resource_templates(meta=meta)]
 
     @deprecated("The roots capability is deprecated as of 2026-07-28 (SEP-2577).", category=MCPDeprecationWarning)

tests/client/test_list_all_pagination.py

@@ -8,7 +8,7 @@
 """
 
 from collections.abc import Awaitable, Callable
-from typing import TypeVar
+from typing import Any, TypeVar
 
 import mcp_types as types
 import pytest
@@ -54,6 +54,22 @@ async def handler(_ctx: ServerRequestContext, params: types.PaginatedRequestPara
     return handler
 
 
+def _stuck_cursor_handler(
+    make_item: Callable[[str], ItemT],
+    result_cls: Callable[..., ResultT],
+    items_field: str,
+) -> Callable[[ServerRequestContext, types.PaginatedRequestParams | None], Awaitable[ResultT]]:
+    """Build a malformed handler that always returns the same non-null cursor.
+
+    A drain loop that trusts the cursor would page forever against this server.
+    """
+
+    async def handler(_ctx: ServerRequestContext, _params: types.PaginatedRequestParams | None) -> ResultT:
+        return result_cls(**{items_field: [make_item("x")]}, next_cursor="stuck")
+
+    return handler
+
+
 def _make_tool(name: str) -> types.Tool:
     return types.Tool(name=name, input_schema={"type": "object"})
 
@@ -205,3 +221,53 @@ async def test_list_all_resource_templates_drains_all_pages(
         templates = await client.list_all_resource_templates()
         assert [t.name for t in templates] == ["t1", "t2", "t3"]
         assert len(spies.get_client_requests(method="resources/templates/list")) == 2
+
+
+# ---- malformed server: non-advancing cursor --------------------------------
+
+
+@pytest.mark.parametrize(
+    "build_server,client_method",
+    [
+        (
+            lambda: Server(
+                "stuck-tools",
+                on_list_tools=_stuck_cursor_handler(_make_tool, types.ListToolsResult, "tools"),
+            ),
+            "list_all_tools",
+        ),
+        (
+            lambda: Server(
+                "stuck-prompts",
+                on_list_prompts=_stuck_cursor_handler(_make_prompt, types.ListPromptsResult, "prompts"),
+            ),
+            "list_all_prompts",
+        ),
+        (
+            lambda: Server(
+                "stuck-resources",
+                on_list_resources=_stuck_cursor_handler(_make_resource, types.ListResourcesResult, "resources"),
+            ),
+            "list_all_resources",
+        ),
+        (
+            lambda: Server(
+                "stuck-templates",
+                on_list_resource_templates=_stuck_cursor_handler(
+                    _make_resource_template, types.ListResourceTemplatesResult, "resource_templates"
+                ),
+            ),
+            "list_all_resource_templates",
+        ),
+    ],
+)
+async def test_drain_raises_when_cursor_does_not_advance(
+    build_server: Callable[[], Server[Any]],
+    client_method: str,
+):
+    """A server that keeps returning the same cursor must fail loudly, not loop forever."""
+    server = build_server()
+
+    async with Client(server) as client:
+        with pytest.raises(RuntimeError, match="did not advance"):
+            await getattr(client, client_method)()