Pagination Support

1MCP Agent supports pagination for MCP protocol responses to improve performance when dealing with large result sets from multiple servers. This feature helps manage resources efficiently when aggregating data from many MCP servers.

Overview

What it does: Enables paginated responses for MCP protocol methods (resources, tools, prompts, resource templates)

Why it's disabled by default: Not all MCP clients support pagination, so it's opt-in to ensure compatibility

How it works: Uses cursor-based pagination to fetch results from multiple servers in chunks

⚠️ Important: Default Behavior

Pagination is disabled by default because not all MCP clients support pagination. When disabled:

• All results from all connected MCP servers are fetched and returned at once
• This ensures maximum compatibility with existing clients
• May consume more memory and time with many servers

Enabling Pagination

1. Command Line Flag

Enable pagination with the --pagination or -p flag:

# Enable pagination for HTTP transport
npx -y @1mcp/agent --config mcp.json --pagination

# With short flag
npx -y @1mcp/agent --config mcp.json -p

2. Environment Variable

Set the ONE_MCP_PAGINATION environment variable:

export ONE_MCP_PAGINATION=true
npx -y @1mcp/agent --config mcp.json

3. HTTP Query Parameter

For HTTP transport, enable pagination per-request:

# Test pagination with MCP Inspector
pnpm inspector

# Then in the inspector interface:
# 1. Navigate to the tools tab
# 2. Enable pagination in settings
# 3. Click "List Tools" to see paginated results
# 4. Use the "List More Tools" button to navigate through results

How Pagination Works

Cursor Format

1MCP returns an opaque, versioned cursor. It binds the walk to the capability kind, current runtime generation, active filters, provider position, and the provider's opaque cursor. Clients must return the value unchanged and must not decode or construct cursors.

Providers are visited in deterministic name order, with provider ID used as the tie-breaker. Each aggregate page contains at most one provider page, and 1MCP's own capabilities participate in the same sequence.

Pagination Flow

Supported MCP Methods

Pagination works with these MCP protocol methods:

• resources/list - List available resources
• resources/templates/list - List resource templates
• tools/list - List available tools
• prompts/list - List available prompts

Performance Benefits

With Pagination Enabled

Memory Usage: Lower - only current page in memory Response Time: Faster initial response - immediate first page Network: Reduced - smaller response payloads Scalability: Better - handles many servers efficiently

# Example: 10 servers with 100 resources each
# Without pagination: 1000 resources in single response (slow)
# With pagination: 50-100 resources per response (fast)

Without Pagination (Default)

Memory Usage: Higher - all results loaded at once Response Time: Slower - waits for all servers Network: Larger - complete result sets Compatibility: Maximum - works with all clients

Client Implementation

Making Paginated Requests

{
  "jsonrpc": "2.0",
  "id": 1,
  "method": "resources/list",
  "params": {
    "_meta": {
      "progressToken": "optional-progress-token"
    }
  }
}

Handling Paginated Responses

{
  "jsonrpc": "2.0",
  "id": 1,
  "result": {
    "resources": [
      {
        "uri": "file:///example.txt",
        "name": "Example File",
        "mimeType": "text/plain"
      }
    ],
    "nextCursor": "aGVsbG86d29ybGQ="
  }
}

Fetching Next Page

{
  "jsonrpc": "2.0",
  "id": 2,
  "method": "resources/list",
  "params": {
    "cursor": "aGVsbG86d29ybGQ=",
    "_meta": {
      "progressToken": "optional-progress-token"
    }
  }
}

Error Handling

Invalid Cursor

Malformed, legacy, cross-method, filter-mismatched, and stale-generation cursors are rejected with an MCP InvalidParams error. Start a new walk without a cursor after the provider set, filters, or capability generation changes.

{
  "jsonrpc": "2.0",
  "id": 1,
  "error": {
    "code": -32602,
    "message": "Invalid capability pagination cursor"
  }
}

Server Unavailable

When a provider listing fails, 1MCP continues with healthy providers and marks every remaining response in that walk as partial. Failure facts are sanitized and returned under _meta["app.1mcp/capability-pagination"]; provider error text is never exposed.

{
  "_meta": {
    "app.1mcp/capability-pagination": {
      "partial": true,
      "failures": [{ "provider": "example", "code": "upstream_list_failed" }],
      "recovery": { "action": "restart_without_cursor" }
    }
  }
}

Configuration Examples

Development Setup

# Quick development with pagination
npx -y @1mcp/agent --config dev.json --pagination --log-level debug

Production Setup

# Production with environment variables
export ONE_MCP_PAGINATION=true
npx -y @1mcp/agent --config production.json

Docker Environment

# docker-compose.yml
services:
  1mcp:
    image: ghcr.io/1mcp-app/agent:latest
    environment:
      - ONE_MCP_PAGINATION=true
      - ONE_MCP_CONFIG_PATH=/config/mcp.json
    volumes:
      - ./config:/config
    ports:
      - '3050:3050'

When to Enable Pagination

✅ Enable When

• You have 5+ MCP servers with large result sets
• Client supports pagination (can handle nextCursor)
• Performance is more important than simplicity
• Working with resource-intensive operations

❌ Keep Disabled When

• You have few MCP servers (≤3) with small result sets
• Client doesn't support pagination (ignores nextCursor)
• Compatibility is more important than performance
• Simple setup is preferred

Troubleshooting

Check If Pagination Is Working

# Test with MCP Inspector
pnpm inspector

# In the inspector:
# 1. Enable pagination in settings
# 2. Navigate to any list view (resources, tools, prompts)
# 3. Look for "List More" button and page indicators
# 4. Check the response JSON for "nextCursor" field

Debug Pagination Issues

# Enable debug logging to see pagination flow
npx -y @1mcp/agent --config mcp.json --pagination --log-level debug

Look for log messages like:

• Fetching all items for client X (when pagination disabled)
• Fetching next page for client X with cursor Y (when pagination enabled)

Common Issues

Empty Results with Pagination:

• Check if servers support pagination
• Verify cursor format is valid base64

Performance Not Improved:

• Ensure client is making paginated requests
• Check if servers return appropriate page sizes

Cursor Errors:

• Enable debug logging to see cursor parsing
• Verify server names haven't changed in configuration

Related Documentation

• Configuration Guide - Full configuration options
• Feature Overview - All 1MCP features
• Server Management - Managing MCP servers
• Health Check API - Monitoring server status