> ## Documentation Index
> Fetch the complete documentation index at: https://praison.ai/docs/llms.txt
> Use this file to discover all available pages before exploring further.

# MCP Pagination Module

> Paginate tools, resources, and prompts lists per MCP 2025-11-25 specification

# MCP Pagination Module

The MCP Server V2 implements pagination for `tools/list`, `resources/list`, and `prompts/list` endpoints per the MCP 2025-11-25 specification.

## Overview

Pagination uses **opaque cursors** (base64url encoded) that the server generates. Clients cannot determine page size - the server decides based on its configuration.

**Key Features:**

* Default page size: 50 items
* Maximum page size: 100 items
* Opaque cursor encoding (base64url)
* Invalid cursor validation with JSON-RPC errors

## Code Usage

### Basic Pagination

```python theme={"theme":{"light":"vitesse-light","dark":"vitesse-dark"}}
from praisonai.mcp_server.registry import MCPToolRegistry

# Create registry and register tools
registry = MCPToolRegistry()
for i in range(100):
    registry.register(
        name=f"tool_{i}",
        handler=lambda: f"Tool {i}",
        description=f"Tool number {i}"
    )

# Get first page (default 50 items)
tools, next_cursor = registry.list_paginated()
print(f"Got {len(tools)} tools")
print(f"Next cursor: {next_cursor}")

# Get next page using cursor
if next_cursor:
    more_tools, next_cursor = registry.list_paginated(cursor=next_cursor)
    print(f"Got {len(more_tools)} more tools")
```

### Custom Page Size

```python theme={"theme":{"light":"vitesse-light","dark":"vitesse-dark"}}
# Request smaller pages
tools, next_cursor = registry.list_paginated(page_size=10)
print(f"Got {len(tools)} tools")  # 10 tools

# Page size is clamped to MAX_PAGE_SIZE (100)
tools, _ = registry.list_paginated(page_size=200)
print(f"Got {len(tools)} tools")  # Max 100 tools
```

### Cursor Utilities

```python theme={"theme":{"light":"vitesse-light","dark":"vitesse-dark"}}
from praisonai.mcp_server.registry import encode_cursor, decode_cursor

# Encode a cursor with offset
cursor = encode_cursor(50)
print(f"Cursor: {cursor}")  # e.g., "NTA"

# Decode cursor
offset, snapshot = decode_cursor(cursor)
print(f"Offset: {offset}")  # 50

# Encode with snapshot hash (for consistency checking)
cursor = encode_cursor(100, "abc123hash")
offset, snapshot = decode_cursor(cursor)
print(f"Offset: {offset}, Snapshot: {snapshot}")
```

### Resource and Prompt Pagination

```python theme={"theme":{"light":"vitesse-light","dark":"vitesse-dark"}}
from praisonai.mcp_server.registry import MCPResourceRegistry, MCPPromptRegistry

# Resource pagination
resource_registry = MCPResourceRegistry()
resources, next_cursor = resource_registry.list_paginated(page_size=20)

# Prompt pagination
prompt_registry = MCPPromptRegistry()
prompts, next_cursor = prompt_registry.list_paginated(page_size=20)
```

## Server Handler Integration

The MCP server automatically handles pagination in the protocol handlers:

```python theme={"theme":{"light":"vitesse-light","dark":"vitesse-dark"}}
from praisonai.mcp_server.server import MCPServer
import asyncio

server = MCPServer(name="my-server")

# The server handles pagination automatically
# Client sends: {"method": "tools/list", "params": {"cursor": "NTA"}}
# Server responds with paginated results and nextCursor
```

## Error Handling

Invalid cursors raise `ValueError`:

```python theme={"theme":{"light":"vitesse-light","dark":"vitesse-dark"}}
try:
    tools, _ = registry.list_paginated(cursor="invalid!!!")
except ValueError as e:
    print(f"Invalid cursor: {e}")
```

The server converts this to a JSON-RPC error with code `-32602` (Invalid params).

## MCP Protocol Compliance

This implementation follows MCP 2025-11-25 specification:

| Requirement                 | Implementation                   |
| --------------------------- | -------------------------------- |
| Opaque cursors              | Base64url encoded offset         |
| Server-determined page size | Default 50, max 100              |
| `nextCursor` in response    | Included when more results exist |
| Invalid cursor handling     | JSON-RPC error -32602            |

## Constants

```python theme={"theme":{"light":"vitesse-light","dark":"vitesse-dark"}}
from praisonai.mcp_server.registry import DEFAULT_PAGE_SIZE, MAX_PAGE_SIZE

print(f"Default page size: {DEFAULT_PAGE_SIZE}")  # 50
print(f"Maximum page size: {MAX_PAGE_SIZE}")      # 100
```

## See Also

* [MCP Pagination CLI](/docs/cli/mcp-pagination) - CLI commands for pagination
* [MCP Tool Search](/docs/mcp/mcp-tool-search) - Search and filter tools
* [MCP Server](/docs/mcp/mcp-server) - Core MCP server documentation