Documentation Index
Fetch the complete documentation index at: https://docs.praison.ai/llms.txt
Use this file to discover all available pages before exploring further.
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
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}")
-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
