modelcontextprotocol / modelcontextprotocol/typescript-sdk
`McpServer` does not implement server-side pagination for list operations
Nobody has claimed this yet.
- Dominant language
- TypeScript
- Stars
- 13.4k
- Forks
- 2.2k
- Avg merge
- 3d 15h
- Merged PRs (30d)
- 4
Description
Summary
The high-level McpServer class does not implement cursor-based pagination for tools/list, resources/list, resources/templates/list, or prompts/list. All registered items are returned in a single response regardless of set size.
Spec Reference
The MCP pagination specification defines an opaque cursor-based pagination model where:
- Servers return a page of results along with an optional
nextCursorfield - Clients continue paginating by including the cursor in subsequent requests
- Page size is determined by the server
The following operations are expected to support pagination:
resources/listresources/templates/listprompts/listtools/list
Current Behavior
In mcp.ts, all three list handlers return the complete set without reading the cursor request parameter or returning nextCursor:
// tools/list — returns everything
this.server.setRequestHandler('tools/list', (): ListToolsResult => ({
tools: Object.entries(this._registeredTools).filter(...).map(...)
}));
// resources/list — returns everything
this.server.setRequestHandler('resources/list', async (_request, ctx) => {
// ...
return { resources: [...resources, ...templateResources] };
});
// prompts/list — returns everything
this.server.setRequestHandler('prompts/list', (): ListPromptsResult => ({
prompts: Object.entries(this._registeredPrompts).filter(...).map(...)
}));
Notes
- The client (
packages/client) already handles paginated responses correctly (loops onnextCursor). - The type system already defines nextCursor in PaginatedResultSchema (
schemas.ts). - Users can work around this by using the low-level Server class and implementing their own list handlers with cursor logic, but
McpServerprovides no built-in mechanism or configuration for it.
I'd be happy to open a PR for this if the maintainers are aligned with the need.
Contributor guide
First steps
- Read the whole issue, then the project's contributing guide.
- Comment on the issue to say you are picking it up — it saves two people doing the same work.
- Fork the repository and make your change on a branch.
- Open a pull request that references the issue number.
Research direction
Start in mcp.ts by reading the tools/list, resources/list, resources/templates/list, and prompts/list handlers, then review PaginatedResultSchema in schemas.ts and the pagination loop in packages/client. Define how the server page size and opaque cursors should work, and verify that each operation reads a cursor and returns nextCursor when more items remain.
Written by the indexing model from the issue text.
Assessment
- Tech stack
- typescript
- Domain
- api, backend-api-design
- Issue type
- Feature
- Difficulty
- 4/5
- Estimated time
- 3-5 days
- Activity status
- Quiet
- Clarity
- Mostly clear
- Newbie friendliness
- 48/100