modelcontextprotocol / modelcontextprotocol/typescript-sdk

`McpServer` does not implement server-side pagination for list operations

Open
#2,352 2 comments 0 reactions 0 assignees View on GitHub

Nobody has claimed this yet.

enhancement needs decision P2
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 nextCursor field
  • 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/list
  • resources/templates/list
  • prompts/list
  • tools/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 on nextCursor).
  • 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 McpServer provides 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

Open the contributing guide

First steps

  1. Read the whole issue, then the project's contributing guide.
  2. Comment on the issue to say you are picking it up — it saves two people doing the same work.
  3. Fork the repository and make your change on a branch.
  4. 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

Get new issues in your inbox

A short digest of beginner-friendly GitHub issues.