Proposal: Move MCP pagination to cursor-based approach

[SamMorrowDrums]

Currently, MCP pagination is not widely used and often results in unnecessary complexity and token usage. We propose moving away from traditional page/offset-based pagination in favor of a more explicit cursor-based approach.

Where possible, we should replace paginated list tools with search-based tools. For cases where pagination is still required, we can provide a cursor value for retrieving the next set of results (even if the cursor is something like limit=20;offset=100 or page=100). It may also be beneficial to always fetch one extra result from the API and, if more data is available, return a cursor and a moreResults: true flag.

There is value in retaining a pageSize option where user prompts specifically request a certain number of results, but in practice, models often request more data than necessary when given the option.

A cursor-based approach should make pagination more explicit and easier for both users and models to use effectively, rather than requiring the model to infer when to increment a page.

---

This proposal supersedes #430 (#430), which identified issues with pagination but did not propose a concrete solution.

Proposed solution:

• Remove page/offset-based pagination from MCP tools
• Use a single cursor field for pagination, with a moreResults boolean and a nextCursor value if more data is available
• Where possible, replace paginated list tools with search tools
• Optionally keep a pageSize parameter for user-driven limits

Feedback and discussion are welcome.