Add MCP-compliant pagination support

docs/clients/prompts.mdx

@@ -13,13 +13,13 @@ Prompts are reusable message templates exposed by MCP servers. They can accept a
 
 ## Listing Prompts
 
-Use `list_prompts()` to retrieve all available prompt templates:
+Use `list_prompts()` to retrieve all available prompt templates. When the server paginates results, the client automatically fetches all pages and returns the complete list.
 
 ```python
 async with client:
     prompts = await client.list_prompts()
     # prompts -> list[mcp.types.Prompt]
-    
+
     for prompt in prompts:
         print(f"Prompt: {prompt.name}")
         print(f"Description: {prompt.description}")
@@ -31,6 +31,8 @@ async with client:
             print(f"Tags: {fastmcp_meta.get('tags', [])}")
 ```
 
+For manual pagination control, use `list_prompts_mcp()` with the `cursor` parameter. See [Pagination](/servers/pagination#manual-pagination) for details.
+
 ### Filtering by Tags
 
 <VersionBadge version="2.11.0" />

docs/clients/resources.mdx

@@ -22,13 +22,13 @@ MCP servers expose two types of resources:
 
 ### Static Resources
 
-Use `list_resources()` to retrieve all static resources available on the server:
+Use `list_resources()` to retrieve all static resources available on the server. When the server paginates results, the client automatically fetches all pages and returns the complete list.
 
 ```python
 async with client:
     resources = await client.list_resources()
     # resources -> list[mcp.types.Resource]
-    
+
     for resource in resources:
         print(f"Resource URI: {resource.uri}")
         print(f"Name: {resource.name}")
@@ -40,15 +40,17 @@ async with client:
             print(f"Tags: {fastmcp_meta.get('tags', [])}")
 ```
 
+For manual pagination control, use `list_resources_mcp()` with the `cursor` parameter. See [Pagination](/servers/pagination#manual-pagination) for details.
+
 ### Resource Templates
 
-Use `list_resource_templates()` to retrieve available resource templates:
+Use `list_resource_templates()` to retrieve available resource templates. When the server paginates results, the client automatically fetches all pages and returns the complete list.
 
 ```python
 async with client:
     templates = await client.list_resource_templates()
     # templates -> list[mcp.types.ResourceTemplate]
-    
+
     for template in templates:
         print(f"Template URI: {template.uriTemplate}")
         print(f"Name: {template.name}")
@@ -59,6 +61,8 @@ async with client:
             print(f"Tags: {fastmcp_meta.get('tags', [])}")
 ```
 
+For manual pagination control, use `list_resource_templates_mcp()` with the `cursor` parameter. See [Pagination](/servers/pagination#manual-pagination) for details.
+
 ### Filtering by Tags
 
 <VersionBadge version="2.11.0" />

docs/clients/tools.mdx

@@ -13,13 +13,13 @@ Tools are executable functions exposed by MCP servers. The FastMCP client provid
 
 ## Discovering Tools
 
-Use `list_tools()` to retrieve all tools available on the server:
+Use `list_tools()` to retrieve all tools available on the server. When the server paginates results, the client automatically fetches all pages and returns the complete list.
 
 ```python
 async with client:
     tools = await client.list_tools()
     # tools -> list[mcp.types.Tool]
-    
+
     for tool in tools:
         print(f"Tool: {tool.name}")
         print(f"Description: {tool.description}")
@@ -31,6 +31,8 @@ async with client:
             print(f"Tags: {fastmcp_meta.get('tags', [])}")
 ```
 
+For manual pagination control, use `list_tools_mcp()` with the `cursor` parameter. See [Pagination](/servers/pagination#manual-pagination) for details.
+
 ### Filtering by Tags
 
 <VersionBadge version="2.11.0" />

docs/docs.json

@@ -127,6 +127,7 @@
                   "servers/lifespan",
                   "servers/logging",
                   "servers/middleware",
+                  "servers/pagination",
                   "servers/progress",
                   "servers/sampling",
                   "servers/storage-backends",

docs/servers/pagination.mdx

@@ -0,0 +1,92 @@
+---
+title: Pagination
+sidebarTitle: Pagination
+description: Control how servers return large lists of components to clients.
+icon: page
+---
+
+import { VersionBadge } from '/snippets/version-badge.mdx'
+
+<VersionBadge version="3.0.0" />
+
+When a server exposes many tools, resources, or prompts, returning them all in a single response can be impractical. MCP supports pagination for list operations, allowing servers to return results in manageable chunks that clients can fetch incrementally.
+
+## Server Configuration
+
+By default, FastMCP servers return all components in a single response for backward compatibility. To enable pagination, set the `list_page_size` parameter when creating your server. This value determines the maximum number of items returned per page across all list operations.
+
+```python
+from fastmcp import FastMCP
+
+# Enable pagination with 50 items per page
+server = FastMCP("ComponentRegistry", list_page_size=50)
+
+# Register tools (in practice, these might come from a database or config)
+@server.tool
+def search(query: str) -> str:
+    return f"Results for: {query}"
+
+@server.tool
+def analyze(data: str) -> dict:
+    return {"status": "analyzed", "data": data}
+
+# ... many more tools, resources, prompts
+```
+
+When `list_page_size` is configured, the `tools/list`, `resources/list`, `resources/templates/list`, and `prompts/list` endpoints all paginate their responses. Each response includes a `nextCursor` field when more results exist, which clients use to fetch subsequent pages.
+
+### Cursor Format
+
+Cursors are opaque base64-encoded strings per the MCP specification. Clients should treat them as black boxes, passing them unchanged between requests. The cursor encodes the offset into the result set, but this is an implementation detail that may change.
+
+## Client Behavior
+
+The FastMCP Client handles pagination transparently. Convenience methods like `list_tools()`, `list_resources()`, `list_resource_templates()`, and `list_prompts()` automatically fetch all pages and return the complete list. Existing code continues to work without modification.
+
+```python
+from fastmcp import Client
+
+async with Client(server) as client:
+    # Returns all 200 tools, fetching pages automatically
+    tools = await client.list_tools()
+    print(f"Total tools: {len(tools)}")  # 200
+```
+
+### Manual Pagination
+
+For scenarios where you want to process results incrementally (memory-constrained environments, progress reporting, or early termination), use the `_mcp` variants with explicit cursor handling.
+
+```python
+from fastmcp import Client
+
+async with Client(server) as client:
+    # Fetch first page
+    result = await client.list_tools_mcp()
+    print(f"Page 1: {len(result.tools)} tools")
+
+    # Continue fetching while more pages exist
+    while result.nextCursor:
+        result = await client.list_tools_mcp(cursor=result.nextCursor)
+        print(f"Next page: {len(result.tools)} tools")
+```
+
+The `_mcp` methods return the raw MCP protocol objects, which include both the items and the `nextCursor` for the next page. When `nextCursor` is `None`, you've reached the end of the result set.
+
+All four list operations support manual pagination:
+
+| Operation | Convenience Method | Manual Method |
+|-----------|-------------------|---------------|
+| Tools | `list_tools()` | `list_tools_mcp(cursor=...)` |
+| Resources | `list_resources()` | `list_resources_mcp(cursor=...)` |
+| Resource Templates | `list_resource_templates()` | `list_resource_templates_mcp(cursor=...)` |
+| Prompts | `list_prompts()` | `list_prompts_mcp(cursor=...)` |
+
+## When to Use Pagination
+
+Pagination becomes valuable when your server exposes a large number of components. Consider enabling it when:
+
+- Your server dynamically generates many components (e.g., from a database or file system)
+- Memory usage is a concern for clients
+- You want to reduce initial response latency
+
+For servers with a fixed, modest number of components (fewer than 100), pagination adds complexity without meaningful benefit. The default behavior of returning everything in one response is simpler and efficient for typical use cases.

docs/servers/server.mdx

@@ -95,6 +95,11 @@ The `FastMCP` constructor accepts several arguments:
   Controls how tool input parameters are validated. When `False` (default), FastMCP uses Pydantic's flexible validation that coerces compatible inputs (e.g., `"10"` → `10` for int parameters). When `True`, uses the MCP SDK's JSON Schema validation to validate inputs against the exact schema before passing them to your function, rejecting any type mismatches. The default mode improves compatibility with LLM clients while maintaining type safety. See [Input Validation Modes](/servers/tools#input-validation-modes) for details
 </ParamField>
 
+<ParamField body="list_page_size" type="int | None" default="None">
+  <VersionBadge version="3.0.0" />
+  Maximum number of items per page for list operations (`tools/list`, `resources/list`, etc.). When `None` (default), all results are returned in a single response. When set, responses are paginated and include a `nextCursor` for fetching additional pages. See [Pagination](/servers/pagination) for details
+</ParamField>
+
 </Card>
 ## Components