Mcp Pager — Zero Config Response Paging For Mcp Servers (typescript + Python)
LocalAbout Mcp Pager — Zero Config Response Paging For Mcp Servers (typescript + Python)
mcp-pager is a TypeScript and Python middleware layer for MCP server developers. It splits oversized tool responses by token count and provides metadata for fetching subsequent pages.
Key features
- 01Token-aware response chunking
- 02Cursor-based page retrieval
- 03Redis shared storage backend
- 04Optional HMAC cursor signing
- 05Pagination lifecycle callbacks
Use cases
- 01Handling tool results larger than LLM context limits
- 02Paging through large result sets across server processes
MCP support
It wraps an MCP server and intercepts tool responses that exceed a token limit. MCP clients can request further chunks using the supplied cursor and get_next_page.
Configuration
Local server config is the same for every client. Copy it into your client’s MCP config file.
Tools
Local servers expose tools only once running on your machine, and the maintainer has not provided a tool list.
Details
From the project READMEmcp-pager
Token-aware response management for MCP servers.
Your tools return thousands of records. LLMs have token limits. mcp-pager sits between them — it intercepts oversized tool responses, chunks them by token count, and delivers each page with agent-readable metadata so the LLM knows exactly what to fetch next. One line of code. No changes to your existing server.
Choose your language
| TypeScript / JavaScript | Python | |
|---|---|---|
| Install | npm install mcp-pager | pip install mcp-pager |
| Docs | TypeScript guide → | Python guide → |
| Registry | npmjs.com/package/mcp-pager | pypi.org/project/mcp-pager |
| MCP SDK | @modelcontextprotocol/sdk | mcp (FastMCP) |
What it does
Tool call → mcp-pager → Your MCP server
│
token count ≤ limit?
├─ yes → return as-is
└─ no → chunk → store → return page 1 + metadata
get_next_page(cursor) → read from store → return next chunk + metadata
When a response is too large, the LLM receives structured metadata it can act on directly:
{
"hasMore": true,
"pageIndex": 0,
"totalPages": 22,
"remainingPages": 21,
"nextCursor": "eyJpZCI6Ijkx...",
"instruction": "Call `get_next_page` with nextCursor to get the next page. Repeat until hasMore is false."
}
Key features
| Feature | Description |
|---|---|
| Zero config | One line wraps your entire server |
| One backend call | Your API is called once regardless of how many pages the LLM fetches |
| Sliding TTL | Cursor expiry resets on every page fetch — long sessions never time out mid-way |
| Redis backend | Production-ready shared storage for multi-process / serverless deployments |
| HMAC signing | Optional cursor signing for multi-tenant environments |
| Observability | onPaginate / on_paginate callback with typed lifecycle events |
| Agent-readable metadata | Structured JSON tells the LLM exactly what to do next |
Documentation
| Doc | Description |
|---|---|
| TypeScript guide | Full API, backends, signing, observability |
| Python guide | Full API, FastMCP integration, backends |
| LLM prompting guide | Tested system prompts for Claude, GPT-4o, Cursor |
| Migration guide | Moving from manual pagination to mcp-pager |
| Token savings | Before/after numbers with real examples |
| Roadmap | What's coming in v1.x (Smart Response Handling) |
Source
mcp-pager/
├── src/ TypeScript source
├── docs/ Guides and documentation
├── python/
│ ├── mcp_pager/ Python source
│ └── README.md Full Python documentation
└── examples/ Demo servers (TS + Python)
License
MIT — Satish Kakollu
Comments
New to MCP?
From what the protocol is to installing your first server, these answers cover most first questions.
An open protocol that defines how AI applications connect to external tools and data in a uniform way. Clients talk to the model; MCP servers provide tools, resources and prompt templates. They exchange standard messages, so one server can be reused by many clients.