π The fast, Pythonic way to build MCP servers and clients.
fix: guard client pagination loops against misbehaving servers (#3167)
Jeremiah Lowin175479f65fb8
diff --git a/docs/python-sdk/fastmcp-client-mixins-prompts.mdx b/docs/python-sdk/fastmcp-client-mixins-prompts.mdxindex 7e9c8e8f6..bf5303caf 100644--- a/docs/python-sdk/fastmcp-client-mixins-prompts.mdx+++ b/docs/python-sdk/fastmcp-client-mixins-prompts.mdx@@ -58,7 +58,7 @@ large result sets incrementally), use list_prompts_mcp() with the cursor paramet- `McpError`: If the request results in a TimeoutError | JSONRPCError-#### `get_prompt_mcp` <sup><a href="https://github.com/jlowin/fastmcp/blob/main/src/fastmcp/client/mixins/prompts.py#L84" target="_blank"><Icon icon="github" style="width: 14px; height: 14px;" /></a></sup>+#### `get_prompt_mcp` <sup><a href="https://github.com/jlowin/fastmcp/blob/main/src/fastmcp/client/mixins/prompts.py#L92" target="_blank"><Icon icon="github" style="width: 14px; height: 14px;" /></a></sup>```pythonget_prompt_mcp(self: Client, name: str, arguments: dict[str, Any] | None = None, meta: dict[str, Any] | None = None) -> mcp.types.GetPromptResult@@ -80,19 +80,19 @@ containing the prompt messages and any additional metadata.- `McpError`: If the request results in a TimeoutError | JSONRPCError-#### `get_prompt` <sup><a href="https://github.com/jlowin/fastmcp/blob/main/src/fastmcp/client/mixins/prompts.py#L153" target="_blank"><Icon icon="github" style="width: 14px; height: 14px;" /></a></sup>+#### `get_prompt` <sup><a href="https://github.com/jlowin/fastmcp/blob/main/src/fastmcp/client/mixins/prompts.py#L161" target="_blank"><Icon icon="github" style="width: 14px; height: 14px;" /></a></sup>```pythonget_prompt(self: Client, name: str, arguments: dict[str, Any] | None = None) -> mcp.types.GetPromptResult```-#### `get_prompt` <sup><a href="https://github.com/jlowin/fastmcp/blob/main/src/fastmcp/client/mixins/prompts.py#L164" target="_blank"><Icon icon="github" style="width: 14px; height: 14px;" /></a></sup>+#### `get_prompt` <sup><a href="https://github.com/jlowin/fastmcp/blob/main/src/fastmcp/client/mixins/prompts.py#L172" target="_blank"><Icon icon="github" style="width: 14px; height: 14px;" /></a></sup>```pythonget_prompt(self: Client, name: str, arguments: dict[str, Any] | None = None) -> PromptTask```-#### `get_prompt` <sup><a href="https://github.com/jlowin/fastmcp/blob/main/src/fastmcp/client/mixins/prompts.py#L176" target="_blank"><Icon icon="github" style="width: 14px; height: 14px;" /></a></sup>+#### `get_prompt` <sup><a href="https://github.com/jlowin/fastmcp/blob/main/src/fastmcp/client/mixins/prompts.py#L184" target="_blank"><Icon icon="github" style="width: 14px; height: 14px;" /></a></sup>```pythonget_prompt(self: Client, name: str, arguments: dict[str, Any] | None = None) -> mcp.types.GetPromptResult | PromptTaskdiff --git a/docs/python-sdk/fastmcp-client-mixins-resources.mdx b/docs/python-sdk/fastmcp-client-mixins-resources.mdxindex ab89913e9..64aaf5e04 100644--- a/docs/python-sdk/fastmcp-client-mixins-resources.mdx+++ b/docs/python-sdk/fastmcp-client-mixins-resources.mdx@@ -58,7 +58,7 @@ large result sets incrementally), use list_resources_mcp() with the cursor param- `McpError`: If the request results in a TimeoutError | JSONRPCError-#### `list_resource_templates_mcp` <sup><a href="https://github.com/jlowin/fastmcp/blob/main/src/fastmcp/client/mixins/resources.py#L82" target="_blank"><Icon icon="github" style="width: 14px; height: 14px;" /></a></sup>+#### `list_resource_templates_mcp` <sup><a href="https://github.com/jlowin/fastmcp/blob/main/src/fastmcp/client/mixins/resources.py#L90" target="_blank"><Icon icon="github" style="width: 14px; height: 14px;" /></a></sup>```pythonlist_resource_templates_mcp(self: Client) -> mcp.types.ListResourceTemplatesResult@@ -78,7 +78,7 @@ containing the list of resource templates and any additional metadata.- `McpError`: If the request results in a TimeoutError | JSONRPCError-#### `list_resource_templates` <sup><a href="https://github.com/jlowin/fastmcp/blob/main/src/fastmcp/client/mixins/resources.py#L105" target="_blank"><Icon icon="github" style="width: 14px; height: 14px;" /></a></sup>+#### `list_resource_templates` <sup><a href="https://github.com/jlowin/fastmcp/blob/main/src/fastmcp/client/mixins/resources.py#L113" target="_blank"><Icon icon="github" style="width: 14px; height: 14px;" /></a></sup>```pythonlist_resource_templates(self: Client) -> list[mcp.types.ResourceTemplate]@@ -99,7 +99,7 @@ cursor parameter.- `McpError`: If the request results in a TimeoutError | JSONRPCError-#### `read_resource_mcp` <sup><a href="https://github.com/jlowin/fastmcp/blob/main/src/fastmcp/client/mixins/resources.py#L132" target="_blank"><Icon icon="github" style="width: 14px; height: 14px;" /></a></sup>+#### `read_resource_mcp` <sup><a href="https://github.com/jlowin/fastmcp/blob/main/src/fastmcp/client/mixins/resources.py#L149" target="_blank"><Icon icon="github" style="width: 14px; height: 14px;" /></a></sup>```pythonread_resource_mcp(self: Client, uri: AnyUrl | str, meta: dict[str, Any] | None = None) -> mcp.types.ReadResourceResult@@ -120,19 +120,19 @@ containing the resource contents and any additional metadata.- `McpError`: If the request results in a TimeoutError | JSONRPCError-#### `read_resource` <sup><a href="https://github.com/jlowin/fastmcp/blob/main/src/fastmcp/client/mixins/resources.py#L188" target="_blank"><Icon icon="github" style="width: 14px; height: 14px;" /></a></sup>+#### `read_resource` <sup><a href="https://github.com/jlowin/fastmcp/blob/main/src/fastmcp/client/mixins/resources.py#L205" target="_blank"><Icon icon="github" style="width: 14px; height: 14px;" /></a></sup>```pythonread_resource(self: Client, uri: AnyUrl | str) -> list[mcp.types.TextResourceContents | mcp.types.BlobResourceContents]```-#### `read_resource` <sup><a href="https://github.com/jlowin/fastmcp/blob/main/src/fastmcp/client/mixins/resources.py#L198" target="_blank"><Icon icon="github" style="width: 14px; height: 14px;" /></a></sup>+#### `read_resource` <sup><a href="https://github.com/jlowin/fastmcp/blob/main/src/fastmcp/client/mixins/resources.py#L215" target="_blank"><Icon icon="github" style="width: 14px; height: 14px;" /></a></sup>```pythonread_resource(self: Client, uri: AnyUrl | str) -> ResourceTask```-#### `read_resource` <sup><a href="https://github.com/jlowin/fastmcp/blob/main/src/fastmcp/client/mixins/resources.py#L209" target="_blank"><Icon icon="github" style="width: 14px; height: 14px;" /></a></sup>+#### `read_resource` <sup><a href="https://github.com/jlowin/fastmcp/blob/main/src/fastmcp/client/mixins/resources.py#L226" target="_blank"><Icon icon="github" style="width: 14px; height: 14px;" /></a></sup>```pythonread_resource(self: Client, uri: AnyUrl | str) -> list[mcp.types.TextResourceContents | mcp.types.BlobResourceContents] | ResourceTaskdiff --git a/docs/python-sdk/fastmcp-client-mixins-tools.mdx b/docs/python-sdk/fastmcp-client-mixins-tools.mdxindex 769b267c2..eda72f44d 100644--- a/docs/python-sdk/fastmcp-client-mixins-tools.mdx+++ b/docs/python-sdk/fastmcp-client-mixins-tools.mdx@@ -58,7 +58,7 @@ large result sets incrementally), use list_tools_mcp() with the cursor parameter- `McpError`: If the request results in a TimeoutError | JSONRPCError-#### `call_tool_mcp` <sup><a href="https://github.com/jlowin/fastmcp/blob/main/src/fastmcp/client/mixins/tools.py#L88" target="_blank"><Icon icon="github" style="width: 14px; height: 14px;" /></a></sup>+#### `call_tool_mcp` <sup><a href="https://github.com/jlowin/fastmcp/blob/main/src/fastmcp/client/mixins/tools.py#L96" target="_blank"><Icon icon="github" style="width: 14px; height: 14px;" /></a></sup>```pythoncall_tool_mcp(self: Client, name: str, arguments: dict[str, Any], progress_handler: ProgressHandler | None = None, timeout: datetime.timedelta | float | int | None = None, meta: dict[str, Any] | None = None) -> mcp.types.CallToolResult@@ -88,19 +88,19 @@ containing the tool result and any additional metadata.- `McpError`: If the tool call requests results in a TimeoutError | JSONRPCError-#### `call_tool` <sup><a href="https://github.com/jlowin/fastmcp/blob/main/src/fastmcp/client/mixins/tools.py#L168" target="_blank"><Icon icon="github" style="width: 14px; height: 14px;" /></a></sup>+#### `call_tool` <sup><a href="https://github.com/jlowin/fastmcp/blob/main/src/fastmcp/client/mixins/tools.py#L176" target="_blank"><Icon icon="github" style="width: 14px; height: 14px;" /></a></sup>```pythoncall_tool(self: Client, name: str, arguments: dict[str, Any] | None = None) -> CallToolResult```-#### `call_tool` <sup><a href="https://github.com/jlowin/fastmcp/blob/main/src/fastmcp/client/mixins/tools.py#L182" target="_blank"><Icon icon="github" style="width: 14px; height: 14px;" /></a></sup>+#### `call_tool` <sup><a href="https://github.com/jlowin/fastmcp/blob/main/src/fastmcp/client/mixins/tools.py#L190" target="_blank"><Icon icon="github" style="width: 14px; height: 14px;" /></a></sup>```pythoncall_tool(self: Client, name: str, arguments: dict[str, Any] | None = None) -> ToolTask```-#### `call_tool` <sup><a href="https://github.com/jlowin/fastmcp/blob/main/src/fastmcp/client/mixins/tools.py#L197" target="_blank"><Icon icon="github" style="width: 14px; height: 14px;" /></a></sup>+#### `call_tool` <sup><a href="https://github.com/jlowin/fastmcp/blob/main/src/fastmcp/client/mixins/tools.py#L205" target="_blank"><Icon icon="github" style="width: 14px; height: 14px;" /></a></sup>```pythoncall_tool(self: Client, name: str, arguments: dict[str, Any] | None = None) -> CallToolResult | ToolTaskdiff --git a/docs/python-sdk/fastmcp-server-context.mdx b/docs/python-sdk/fastmcp-server-context.mdxindex a87096234..0defded51 100644--- a/docs/python-sdk/fastmcp-server-context.mdx+++ b/docs/python-sdk/fastmcp-server-context.mdx@@ -202,7 +202,7 @@ Works in both foreground (MCP progress notifications) and background- `message`: Optional status message describing current progress-#### `list_resources` <sup><a href="https://github.com/jlowin/fastmcp/blob/main/src/fastmcp/server/context.py#L435" target="_blank"><Icon icon="github" style="width: 14px; height: 14px;" /></a></sup>+#### `list_resources` <sup><a href="https://github.com/jlowin/fastmcp/blob/main/src/fastmcp/server/context.py#L439" target="_blank"><Icon icon="github" style="width: 14px; height: 14px;" /></a></sup>```pythonlist_resources(self) -> list[SDKResource]@@ -214,7 +214,7 @@ List all available resources from the server.- List of Resource objects available on the server-#### `list_prompts` <sup><a href="https://github.com/jlowin/fastmcp/blob/main/src/fastmcp/server/context.py#L451" target="_blank"><Icon icon="github" style="width: 14px; height: 14px;" /></a></sup>+#### `list_prompts` <sup><a href="https://github.com/jlowin/fastmcp/blob/main/src/fastmcp/server/context.py#L455" target="_blank"><Icon icon="github" style="width: 14px; height: 14px;" /></a></sup>```pythonlist_prompts(self) -> list[SDKPrompt]@@ -226,7 +226,7 @@ List all available prompts from the server.- List of Prompt objects available on the server-#### `get_prompt` <sup><a href="https://github.com/jlowin/fastmcp/blob/main/src/fastmcp/server/context.py#L467" target="_blank"><Icon icon="github" style="width: 14px; height: 14px;" /></a></sup>+#### `get_prompt` <sup><a href="https://github.com/jlowin/fastmcp/blob/main/src/fastmcp/server/context.py#L471" target="_blank"><Icon icon="github" style="width: 14px; height: 14px;" /></a></sup>```pythonget_prompt(self, name: str, arguments: dict[str, Any] | None = None) -> GetPromptResult@@ -242,7 +242,7 @@ Get a prompt by name with optional arguments.- The prompt result-#### `read_resource` <sup><a href="https://github.com/jlowin/fastmcp/blob/main/src/fastmcp/server/context.py#L486" target="_blank"><Icon icon="github" style="width: 14px; height: 14px;" /></a></sup>+#### `read_resource` <sup><a href="https://github.com/jlowin/fastmcp/blob/main/src/fastmcp/server/context.py#L490" target="_blank"><Icon icon="github" style="width: 14px; height: 14px;" /></a></sup>```pythonread_resource(self, uri: str | AnyUrl) -> ResourceResult@@ -257,7 +257,7 @@ Read a resource by URI.- ResourceResult with contents-#### `log` <sup><a href="https://github.com/jlowin/fastmcp/blob/main/src/fastmcp/server/context.py#L502" target="_blank"><Icon icon="github" style="width: 14px; height: 14px;" /></a></sup>+#### `log` <sup><a href="https://github.com/jlowin/fastmcp/blob/main/src/fastmcp/server/context.py#L506" target="_blank"><Icon icon="github" style="width: 14px; height: 14px;" /></a></sup>```pythonlog(self, message: str, level: LoggingLevel | None = None, logger_name: str | None = None, extra: Mapping[str, Any] | None = None) -> None@@ -275,7 +275,7 @@ Messages sent to Clients are also logged to the `fastmcp.server.context.to_clien- `extra`: Optional mapping for additional arguments-#### `transport` <sup><a href="https://github.com/jlowin/fastmcp/blob/main/src/fastmcp/server/context.py#L531" target="_blank"><Icon icon="github" style="width: 14px; height: 14px;" /></a></sup>+#### `transport` <sup><a href="https://github.com/jlowin/fastmcp/blob/main/src/fastmcp/server/context.py#L535" target="_blank"><Icon icon="github" style="width: 14px; height: 14px;" /></a></sup>```pythontransport(self) -> TransportType | None@@ -287,7 +287,7 @@ Returns the transport type used to run this server: "stdio", "sse",or "streamable-http". Returns None if called outside of a server context.-#### `client_supports_extension` <sup><a href="https://github.com/jlowin/fastmcp/blob/main/src/fastmcp/server/context.py#L539" target="_blank"><Icon icon="github" style="width: 14px; height: 14px;" /></a></sup>+#### `client_supports_extension` <sup><a href="https://github.com/jlowin/fastmcp/blob/main/src/fastmcp/server/context.py#L543" target="_blank"><Icon icon="github" style="width: 14px; height: 14px;" /></a></sup>```pythonclient_supports_extension(self, extension_id: str) -> bool@@ -312,7 +312,7 @@ Example::return "text-only client"-#### `client_id` <sup><a href="https://github.com/jlowin/fastmcp/blob/main/src/fastmcp/server/context.py#L567" target="_blank"><Icon icon="github" style="width: 14px; height: 14px;" /></a></sup>+#### `client_id` <sup><a href="https://github.com/jlowin/fastmcp/blob/main/src/fastmcp/server/context.py#L571" target="_blank"><Icon icon="github" style="width: 14px; height: 14px;" /></a></sup>```pythonclient_id(self) -> str | None@@ -321,7 +321,7 @@ client_id(self) -> str | NoneGet the client ID if available.-#### `request_id` <sup><a href="https://github.com/jlowin/fastmcp/blob/main/src/fastmcp/server/context.py#L576" target="_blank"><Icon icon="github" style="width: 14px; height: 14px;" /></a></sup>+#### `request_id` <sup><a href="https://github.com/jlowin/fastmcp/blob/main/src/fastmcp/server/context.py#L580" target="_blank"><Icon icon="github" style="width: 14px; height: 14px;" /></a></sup>```pythonrequest_id(self) -> str@@ -332,7 +332,7 @@ Get the unique ID for this request.Raises RuntimeError if MCP request context is not available.-#### `session_id` <sup><a href="https://github.com/jlowin/fastmcp/blob/main/src/fastmcp/server/context.py#L589" target="_blank"><Icon icon="github" style="width: 14px; height: 14px;" /></a></sup>+#### `session_id` <sup><a href="https://github.com/jlowin/fastmcp/blob/main/src/fastmcp/server/context.py#L593" target="_blank"><Icon icon="github" style="width: 14px; height: 14px;" /></a></sup>```pythonsession_id(self) -> str@@ -349,7 +349,7 @@ the same client session.- for other transports.-#### `session` <sup><a href="https://github.com/jlowin/fastmcp/blob/main/src/fastmcp/server/context.py#L646" target="_blank"><Icon icon="github" style="width: 14px; height: 14px;" /></a></sup>+#### `session` <sup><a href="https://github.com/jlowin/fastmcp/blob/main/src/fastmcp/server/context.py#L650" target="_blank"><Icon icon="github" style="width: 14px; height: 14px;" /></a></sup>```pythonsession(self) -> ServerSession@@ -363,7 +363,7 @@ In background task mode: Returns the session stored at Context creation.Raises RuntimeError if no session is available.-#### `debug` <sup><a href="https://github.com/jlowin/fastmcp/blob/main/src/fastmcp/server/context.py#L672" target="_blank"><Icon icon="github" style="width: 14px; height: 14px;" /></a></sup>+#### `debug` <sup><a href="https://github.com/jlowin/fastmcp/blob/main/src/fastmcp/server/context.py#L676" target="_blank"><Icon icon="github" style="width: 14px; height: 14px;" /></a></sup>```pythondebug(self, message: str, logger_name: str | None = None, extra: Mapping[str, Any] | None = None) -> None@@ -374,7 +374,7 @@ Send a `DEBUG`-level message to the connected MCP Client.Messages sent to Clients are also logged to the `fastmcp.server.context.to_client` logger with a level of `DEBUG`.-#### `info` <sup><a href="https://github.com/jlowin/fastmcp/blob/main/src/fastmcp/server/context.py#L688" target="_blank"><Icon icon="github" style="width: 14px; height: 14px;" /></a></sup>+#### `info` <sup><a href="https://github.com/jlowin/fastmcp/blob/main/src/fastmcp/server/context.py#L692" target="_blank"><Icon icon="github" style="width: 14px; height: 14px;" /></a></sup>```pythoninfo(self, message: str, logger_name: str | None = None, extra: Mapping[str, Any] | None = None) -> None@@ -385,7 +385,7 @@ Send a `INFO`-level message to the connected MCP Client.Messages sent to Clients are also logged to the `fastmcp.server.context.to_client` logger with a level of `DEBUG`.-#### `warning` <sup><a href="https://github.com/jlowin/fastmcp/blob/main/src/fastmcp/server/context.py#L704" target="_blank"><Icon icon="github" style="width: 14px; height: 14px;" /></a></sup>+#### `warning` <sup><a href="https://github.com/jlowin/fastmcp/blob/main/src/fastmcp/server/context.py#L708" target="_blank"><Icon icon="github" style="width: 14px; height: 14px;" /></a></sup>```pythonwarning(self, message: str, logger_name: str | None = None, extra: Mapping[str, Any] | None = None) -> None@@ -396,7 +396,7 @@ Send a `WARNING`-level message to the connected MCP Client.Messages sent to Clients are also logged to the `fastmcp.server.context.to_client` logger with a level of `DEBUG`.-#### `error` <sup><a href="https://github.com/jlowin/fastmcp/blob/main/src/fastmcp/server/context.py#L720" target="_blank"><Icon icon="github" style="width: 14px; height: 14px;" /></a></sup>+#### `error` <sup><a href="https://github.com/jlowin/fastmcp/blob/main/src/fastmcp/server/context.py#L724" target="_blank"><Icon icon="github" style="width: 14px; height: 14px;" /></a></sup>```pythonerror(self, message: str, logger_name: str | None = None, extra: Mapping[str, Any] | None = None) -> None@@ -407,7 +407,7 @@ Send a `ERROR`-level message to the connected MCP Client.Messages sent to Clients are also logged to the `fastmcp.server.context.to_client` logger with a level of `DEBUG`.-#### `list_roots` <sup><a href="https://github.com/jlowin/fastmcp/blob/main/src/fastmcp/server/context.py#L736" target="_blank"><Icon icon="github" style="width: 14px; height: 14px;" /></a></sup>+#### `list_roots` <sup><a href="https://github.com/jlowin/fastmcp/blob/main/src/fastmcp/server/context.py#L740" target="_blank"><Icon icon="github" style="width: 14px; height: 14px;" /></a></sup>```pythonlist_roots(self) -> list[Root]@@ -416,7 +416,7 @@ list_roots(self) -> list[Root]List the roots available to the server, as indicated by the client.-#### `send_notification` <sup><a href="https://github.com/jlowin/fastmcp/blob/main/src/fastmcp/server/context.py#L741" target="_blank"><Icon icon="github" style="width: 14px; height: 14px;" /></a></sup>+#### `send_notification` <sup><a href="https://github.com/jlowin/fastmcp/blob/main/src/fastmcp/server/context.py#L745" target="_blank"><Icon icon="github" style="width: 14px; height: 14px;" /></a></sup>```pythonsend_notification(self, notification: mcp.types.ServerNotificationType) -> None@@ -428,7 +428,7 @@ Send a notification to the client immediately.- `notification`: An MCP notification instance (e.g., ToolListChangedNotification())-#### `close_sse_stream` <sup><a href="https://github.com/jlowin/fastmcp/blob/main/src/fastmcp/server/context.py#L751" target="_blank"><Icon icon="github" style="width: 14px; height: 14px;" /></a></sup>+#### `close_sse_stream` <sup><a href="https://github.com/jlowin/fastmcp/blob/main/src/fastmcp/server/context.py#L755" target="_blank"><Icon icon="github" style="width: 14px; height: 14px;" /></a></sup>```pythonclose_sse_stream(self) -> None@@ -446,7 +446,7 @@ Instead of holding a connection open for minutes, you can periodically closeand let the client reconnect.-#### `sample_step` <sup><a href="https://github.com/jlowin/fastmcp/blob/main/src/fastmcp/server/context.py#L790" target="_blank"><Icon icon="github" style="width: 14px; height: 14px;" /></a></sup>+#### `sample_step` <sup><a href="https://github.com/jlowin/fastmcp/blob/main/src/fastmcp/server/context.py#L794" target="_blank"><Icon icon="github" style="width: 14px; height: 14px;" /></a></sup>```pythonsample_step(self, messages: str | Sequence[str | SamplingMessage]) -> SampleStep@@ -489,7 +489,7 @@ regardless of this setting.- - .text: The text content (if any)-#### `sample` <sup><a href="https://github.com/jlowin/fastmcp/blob/main/src/fastmcp/server/context.py#L869" target="_blank"><Icon icon="github" style="width: 14px; height: 14px;" /></a></sup>+#### `sample` <sup><a href="https://github.com/jlowin/fastmcp/blob/main/src/fastmcp/server/context.py#L873" target="_blank"><Icon icon="github" style="width: 14px; height: 14px;" /></a></sup>```pythonsample(self, messages: str | Sequence[str | SamplingMessage]) -> SamplingResult[ResultT]@@ -498,7 +498,7 @@ sample(self, messages: str | Sequence[str | SamplingMessage]) -> SamplingResult[Overload: With result_type, returns SamplingResult[ResultT].-#### `sample` <sup><a href="https://github.com/jlowin/fastmcp/blob/main/src/fastmcp/server/context.py#L885" target="_blank"><Icon icon="github" style="width: 14px; height: 14px;" /></a></sup>+#### `sample` <sup><a href="https://github.com/jlowin/fastmcp/blob/main/src/fastmcp/server/context.py#L889" target="_blank"><Icon icon="github" style="width: 14px; height: 14px;" /></a></sup>```pythonsample(self, messages: str | Sequence[str | SamplingMessage]) -> SamplingResult[str]@@ -507,7 +507,7 @@ sample(self, messages: str | Sequence[str | SamplingMessage]) -> SamplingResult[Overload: Without result_type, returns SamplingResult[str].-#### `sample` <sup><a href="https://github.com/jlowin/fastmcp/blob/main/src/fastmcp/server/context.py#L900" target="_blank"><Icon icon="github" style="width: 14px; height: 14px;" /></a></sup>+#### `sample` <sup><a href="https://github.com/jlowin/fastmcp/blob/main/src/fastmcp/server/context.py#L904" target="_blank"><Icon icon="github" style="width: 14px; height: 14px;" /></a></sup>```pythonsample(self, messages: str | Sequence[str | SamplingMessage]) -> SamplingResult[ResultT] | SamplingResult[str]@@ -555,43 +555,43 @@ regardless of this setting.- - .history: All messages exchanged during sampling-#### `elicit` <sup><a href="https://github.com/jlowin/fastmcp/blob/main/src/fastmcp/server/context.py#L975" target="_blank"><Icon icon="github" style="width: 14px; height: 14px;" /></a></sup>+#### `elicit` <sup><a href="https://github.com/jlowin/fastmcp/blob/main/src/fastmcp/server/context.py#L979" target="_blank"><Icon icon="github" style="width: 14px; height: 14px;" /></a></sup>```pythonelicit(self, message: str, response_type: None) -> AcceptedElicitation[dict[str, Any]] | DeclinedElicitation | CancelledElicitation```-#### `elicit` <sup><a href="https://github.com/jlowin/fastmcp/blob/main/src/fastmcp/server/context.py#L987" target="_blank"><Icon icon="github" style="width: 14px; height: 14px;" /></a></sup>+#### `elicit` <sup><a href="https://github.com/jlowin/fastmcp/blob/main/src/fastmcp/server/context.py#L991" target="_blank"><Icon icon="github" style="width: 14px; height: 14px;" /></a></sup>```pythonelicit(self, message: str, response_type: type[T]) -> AcceptedElicitation[T] | DeclinedElicitation | CancelledElicitation```-#### `elicit` <sup><a href="https://github.com/jlowin/fastmcp/blob/main/src/fastmcp/server/context.py#L997" target="_blank"><Icon icon="github" style="width: 14px; height: 14px;" /></a></sup>+#### `elicit` <sup><a href="https://github.com/jlowin/fastmcp/blob/main/src/fastmcp/server/context.py#L1001" target="_blank"><Icon icon="github" style="width: 14px; height: 14px;" /></a></sup>```pythonelicit(self, message: str, response_type: list[str]) -> AcceptedElicitation[str] | DeclinedElicitation | CancelledElicitation```-#### `elicit` <sup><a href="https://github.com/jlowin/fastmcp/blob/main/src/fastmcp/server/context.py#L1007" target="_blank"><Icon icon="github" style="width: 14px; height: 14px;" /></a></sup>+#### `elicit` <sup><a href="https://github.com/jlowin/fastmcp/blob/main/src/fastmcp/server/context.py#L1011" target="_blank"><Icon icon="github" style="width: 14px; height: 14px;" /></a></sup>```pythonelicit(self, message: str, response_type: dict[str, dict[str, str]]) -> AcceptedElicitation[str] | DeclinedElicitation | CancelledElicitation```-#### `elicit` <sup><a href="https://github.com/jlowin/fastmcp/blob/main/src/fastmcp/server/context.py#L1017" target="_blank"><Icon icon="github" style="width: 14px; height: 14px;" /></a></sup>+#### `elicit` <sup><a href="https://github.com/jlowin/fastmcp/blob/main/src/fastmcp/server/context.py#L1021" target="_blank"><Icon icon="github" style="width: 14px; height: 14px;" /></a></sup>```pythonelicit(self, message: str, response_type: list[list[str]]) -> AcceptedElicitation[list[str]] | DeclinedElicitation | CancelledElicitation```-#### `elicit` <sup><a href="https://github.com/jlowin/fastmcp/blob/main/src/fastmcp/server/context.py#L1029" target="_blank"><Icon icon="github" style="width: 14px; height: 14px;" /></a></sup>+#### `elicit` <sup><a href="https://github.com/jlowin/fastmcp/blob/main/src/fastmcp/server/context.py#L1033" target="_blank"><Icon icon="github" style="width: 14px; height: 14px;" /></a></sup>```pythonelicit(self, message: str, response_type: list[dict[str, dict[str, str]]]) -> AcceptedElicitation[list[str]] | DeclinedElicitation | CancelledElicitation```-#### `elicit` <sup><a href="https://github.com/jlowin/fastmcp/blob/main/src/fastmcp/server/context.py#L1041" target="_blank"><Icon icon="github" style="width: 14px; height: 14px;" /></a></sup>+#### `elicit` <sup><a href="https://github.com/jlowin/fastmcp/blob/main/src/fastmcp/server/context.py#L1045" target="_blank"><Icon icon="github" style="width: 14px; height: 14px;" /></a></sup>```pythonelicit(self, message: str, response_type: type[T] | list[str] | dict[str, dict[str, str]] | list[list[str]] | list[dict[str, dict[str, str]]] | None = None) -> AcceptedElicitation[T] | AcceptedElicitation[dict[str, Any]] | AcceptedElicitation[str] | AcceptedElicitation[list[str]] | DeclinedElicitation | CancelledElicitation@@ -620,7 +620,7 @@ type or dataclass or BaseModel. If it is a primitive type, anobject schema with a single "value" field will be generated.-#### `set_state` <sup><a href="https://github.com/jlowin/fastmcp/blob/main/src/fastmcp/server/context.py#L1155" target="_blank"><Icon icon="github" style="width: 14px; height: 14px;" /></a></sup>+#### `set_state` <sup><a href="https://github.com/jlowin/fastmcp/blob/main/src/fastmcp/server/context.py#L1159" target="_blank"><Icon icon="github" style="width: 14px; height: 14px;" /></a></sup>```pythonset_state(self, key: str, value: Any) -> None@@ -633,7 +633,7 @@ The key is automatically prefixed with the session identifier.State expires after 1 day to prevent unbounded memory growth.-#### `get_state` <sup><a href="https://github.com/jlowin/fastmcp/blob/main/src/fastmcp/server/context.py#L1169" target="_blank"><Icon icon="github" style="width: 14px; height: 14px;" /></a></sup>+#### `get_state` <sup><a href="https://github.com/jlowin/fastmcp/blob/main/src/fastmcp/server/context.py#L1173" target="_blank"><Icon icon="github" style="width: 14px; height: 14px;" /></a></sup>```pythonget_state(self, key: str) -> Any@@ -644,7 +644,7 @@ Get a value from the session-scoped state store.Returns None if the key is not found.-#### `delete_state` <sup><a href="https://github.com/jlowin/fastmcp/blob/main/src/fastmcp/server/context.py#L1178" target="_blank"><Icon icon="github" style="width: 14px; height: 14px;" /></a></sup>+#### `delete_state` <sup><a href="https://github.com/jlowin/fastmcp/blob/main/src/fastmcp/server/context.py#L1182" target="_blank"><Icon icon="github" style="width: 14px; height: 14px;" /></a></sup>```pythondelete_state(self, key: str) -> None@@ -653,7 +653,7 @@ delete_state(self, key: str) -> NoneDelete a value from the session-scoped state store.-#### `enable_components` <sup><a href="https://github.com/jlowin/fastmcp/blob/main/src/fastmcp/server/context.py#L1195" target="_blank"><Icon icon="github" style="width: 14px; height: 14px;" /></a></sup>+#### `enable_components` <sup><a href="https://github.com/jlowin/fastmcp/blob/main/src/fastmcp/server/context.py#L1199" target="_blank"><Icon icon="github" style="width: 14px; height: 14px;" /></a></sup>```pythonenable_components(self) -> None@@ -677,7 +677,7 @@ ResourceListChangedNotification, and PromptListChangedNotification.- `match_all`: If True, matches all components regardless of other criteria.-#### `disable_components` <sup><a href="https://github.com/jlowin/fastmcp/blob/main/src/fastmcp/server/context.py#L1233" target="_blank"><Icon icon="github" style="width: 14px; height: 14px;" /></a></sup>+#### `disable_components` <sup><a href="https://github.com/jlowin/fastmcp/blob/main/src/fastmcp/server/context.py#L1237" target="_blank"><Icon icon="github" style="width: 14px; height: 14px;" /></a></sup>```pythondisable_components(self) -> None@@ -701,7 +701,7 @@ ResourceListChangedNotification, and PromptListChangedNotification.- `match_all`: If True, matches all components regardless of other criteria.-#### `reset_visibility` <sup><a href="https://github.com/jlowin/fastmcp/blob/main/src/fastmcp/server/context.py#L1271" target="_blank"><Icon icon="github" style="width: 14px; height: 14px;" /></a></sup>+#### `reset_visibility` <sup><a href="https://github.com/jlowin/fastmcp/blob/main/src/fastmcp/server/context.py#L1275" target="_blank"><Icon icon="github" style="width: 14px; height: 14px;" /></a></sup>```pythonreset_visibility(self) -> Nonediff --git a/src/fastmcp/client/mixins/prompts.py b/src/fastmcp/client/mixins/prompts.pyindex e7c8df80d..e8907c194 100644--- a/src/fastmcp/client/mixins/prompts.py+++ b/src/fastmcp/client/mixins/prompts.py@@ -70,12 +70,20 @@ class ClientPromptsMixin:"""all_prompts: list[mcp.types.Prompt] = []cursor: str | None = None+ seen_cursors: set[str] = set()while True:result = await self.list_prompts_mcp(cursor=cursor)all_prompts.extend(result.prompts)- if result.nextCursor is None:+ if not result.nextCursor:break+ if result.nextCursor in seen_cursors:+ logger.warning(+ f"[{self.name}] Server returned duplicate pagination cursor"+ f" {result.nextCursor!r} for list_prompts; stopping pagination"+ )+ break+ seen_cursors.add(result.nextCursor)cursor = result.nextCursorreturn all_promptsdiff --git a/src/fastmcp/client/mixins/resources.py b/src/fastmcp/client/mixins/resources.pyindex 86de910d9..f49f861f8 100644--- a/src/fastmcp/client/mixins/resources.py+++ b/src/fastmcp/client/mixins/resources.py@@ -69,12 +69,20 @@ class ClientResourcesMixin:"""all_resources: list[mcp.types.Resource] = []cursor: str | None = None+ seen_cursors: set[str] = set()while True:result = await self.list_resources_mcp(cursor=cursor)all_resources.extend(result.resources)- if result.nextCursor is None:+ if not result.nextCursor:break+ if result.nextCursor in seen_cursors:+ logger.warning(+ f"[{self.name}] Server returned duplicate pagination cursor"+ f" {result.nextCursor!r} for list_resources; stopping pagination"+ )+ break+ seen_cursors.add(result.nextCursor)cursor = result.nextCursorreturn all_resources@@ -119,12 +127,21 @@ class ClientResourcesMixin:"""all_templates: list[mcp.types.ResourceTemplate] = []cursor: str | None = None+ seen_cursors: set[str] = set()while True:result = await self.list_resource_templates_mcp(cursor=cursor)all_templates.extend(result.resourceTemplates)- if result.nextCursor is None:+ if not result.nextCursor:+ break+ if result.nextCursor in seen_cursors:+ logger.warning(+ f"[{self.name}] Server returned duplicate pagination cursor"+ f" {result.nextCursor!r} for list_resource_templates;"+ " stopping pagination"+ )break+ seen_cursors.add(result.nextCursor)cursor = result.nextCursorreturn all_templatesdiff --git a/src/fastmcp/client/mixins/tools.py b/src/fastmcp/client/mixins/tools.pyindex 557af20be..f702e4938 100644--- a/src/fastmcp/client/mixins/tools.py+++ b/src/fastmcp/client/mixins/tools.py@@ -73,12 +73,20 @@ class ClientToolsMixin:"""all_tools: list[mcp.types.Tool] = []cursor: str | None = None+ seen_cursors: set[str] = set()while True:result = await self.list_tools_mcp(cursor=cursor)all_tools.extend(result.tools)- if result.nextCursor is None:+ if not result.nextCursor:break+ if result.nextCursor in seen_cursors:+ logger.warning(+ f"[{self.name}] Server returned duplicate pagination cursor"+ f" {result.nextCursor!r} for list_tools; stopping pagination"+ )+ break+ seen_cursors.add(result.nextCursor)cursor = result.nextCursorreturn all_toolsdiff --git a/src/fastmcp/server/context.py b/src/fastmcp/server/context.pyindex 9889aaee9..faa212a2a 100644--- a/src/fastmcp/server/context.py+++ b/src/fastmcp/server/context.py@@ -423,12 +423,16 @@ class Context:"""all_items: list[Any] = []cursor: str | None = None+ seen_cursors: set[str] = set()while True:request = request_factory(cursor)result = await call_method(request)all_items.extend(extract_items(result))- if result.nextCursor is None:+ if not result.nextCursor:break+ if result.nextCursor in seen_cursors:+ break+ seen_cursors.add(result.nextCursor)cursor = result.nextCursorreturn all_itemsdiff --git a/tests/server/test_pagination.py b/tests/server/test_pagination.pyindex c1387fb46..f90a763c0 100644--- a/tests/server/test_pagination.py+++ b/tests/server/test_pagination.py@@ -2,6 +2,9 @@from __future__ import annotations+from unittest.mock import patch++import mcp.typesimport pytestfrom mcp.shared.exceptions import McpError@@ -241,3 +244,193 @@ class TestPageSizeValidation:ValueError, match="list_page_size must be a positive integer"):FastMCP(list_page_size=-1)+++class TestPaginationCycleDetection:+ """Tests that auto-pagination terminates when the server returns cycling cursors."""++ async def test_tools_constant_cursor_terminates(self) -> None:+ """list_tools should stop if the server always returns the same cursor."""+ server = FastMCP()++ @server.tool+ def my_tool() -> str:+ return "ok"++ async with Client(server) as client:+ original = client.list_tools_mcp++ async def returning_constant_cursor(+ *,+ cursor: str | None = None,+ ) -> mcp.types.ListToolsResult:+ result = await original(cursor=cursor)+ result.nextCursor = "stuck"+ return result++ with patch.object(+ client, "list_tools_mcp", side_effect=returning_constant_cursor+ ):+ tools = await client.list_tools()++ # Should get tools from first page + one duplicate (the retry before+ # detecting the cycle), then stop.+ assert len(tools) == 2+ assert all(t.name == "my_tool" for t in tools)++ async def test_prompts_constant_cursor_terminates(self) -> None:+ """list_prompts should stop if the server always returns the same cursor."""+ server = FastMCP()++ @server.prompt+ def my_prompt() -> str:+ return "text"++ async with Client(server) as client:+ original = client.list_prompts_mcp++ async def returning_constant_cursor(+ *,+ cursor: str | None = None,+ ) -> mcp.types.ListPromptsResult:+ result = await original(cursor=cursor)+ result.nextCursor = "stuck"+ return result++ with patch.object(+ client, "list_prompts_mcp", side_effect=returning_constant_cursor+ ):+ prompts = await client.list_prompts()++ assert len(prompts) == 2+ assert all(p.name == "my_prompt" for p in prompts)++ async def test_resources_constant_cursor_terminates(self) -> None:+ """list_resources should stop if the server always returns the same cursor."""+ server = FastMCP()++ @server.resource("test://r")+ def my_resource() -> str:+ return "data"++ async with Client(server) as client:+ original = client.list_resources_mcp++ async def returning_constant_cursor(+ *,+ cursor: str | None = None,+ ) -> mcp.types.ListResourcesResult:+ result = await original(cursor=cursor)+ result.nextCursor = "stuck"+ return result++ with patch.object(+ client, "list_resources_mcp", side_effect=returning_constant_cursor+ ):+ resources = await client.list_resources()++ assert len(resources) == 2+ assert all(r.name == "my_resource" for r in resources)++ async def test_resource_templates_constant_cursor_terminates(self) -> None:+ """list_resource_templates should stop if the server always returns the same cursor."""+ server = FastMCP()++ @server.resource("test://items/{item_id}")+ def my_template(item_id: str) -> str:+ return item_id++ async with Client(server) as client:+ original = client.list_resource_templates_mcp++ async def returning_constant_cursor(+ *,+ cursor: str | None = None,+ ) -> mcp.types.ListResourceTemplatesResult:+ result = await original(cursor=cursor)+ result.nextCursor = "stuck"+ return result++ with patch.object(+ client,+ "list_resource_templates_mcp",+ side_effect=returning_constant_cursor,+ ):+ templates = await client.list_resource_templates()++ assert len(templates) == 2++ async def test_cycling_cursors_terminates(self) -> None:+ """list_tools should stop if the server cycles through a set of cursors."""+ server = FastMCP()++ @server.tool+ def my_tool() -> str:+ return "ok"++ async with Client(server) as client:+ call_count = 0+ original = client.list_tools_mcp++ async def returning_cycling_cursor(+ *,+ cursor: str | None = None,+ ) -> mcp.types.ListToolsResult:+ nonlocal call_count+ result = await original(cursor=cursor)+ # Cycle through A -> B -> C -> A+ cursors = ["A", "B", "C"]+ result.nextCursor = cursors[call_count % 3]+ call_count += 1+ return result++ with patch.object(+ client, "list_tools_mcp", side_effect=returning_cycling_cursor+ ):+ tools = await client.list_tools()++ # A, B, C seen, then A is a duplicate β 4 calls total+ assert call_count == 4+ assert len(tools) == 4++ async def test_empty_string_cursor_terminates(self) -> None:+ """list_tools should stop if the server returns an empty string cursor."""+ server = FastMCP()++ @server.tool+ def my_tool() -> str:+ return "ok"++ async with Client(server) as client:+ original = client.list_tools_mcp++ async def returning_empty_cursor(+ *,+ cursor: str | None = None,+ ) -> mcp.types.ListToolsResult:+ result = await original(cursor=cursor)+ result.nextCursor = ""+ return result++ with patch.object(+ client, "list_tools_mcp", side_effect=returning_empty_cursor+ ):+ tools = await client.list_tools()++ assert len(tools) == 1+ assert tools[0].name == "my_tool"++ async def test_normal_pagination_unaffected(self) -> None:+ """Cycle detection should not interfere with normal pagination."""+ server = FastMCP(list_page_size=10)++ for i in range(25):++ @server.tool(name=f"tool_{i}")+ def make_tool() -> str:+ return "ok"++ async with Client(server) as client:+ tools = await client.list_tools()+ assert len(tools) == 25+ assert len({t.name for t in tools}) == 25