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

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

# 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

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

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:

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:

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

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 - CLI commands for pagination
• MCP Tool Search - Search and filter tools
• MCP Server - Core MCP server documentation