A list that fits in one response is not necessarily a complete list. If an MCP tool returns only the first records without saying that more data exists, an agent can answer confidently from a sample. If it returns everything, the cost of the call grows exactly when the dataset stops fitting comfortably in context.
The fix is to make pagination part of the tool contract: return a bounded page, stable ordering, an opaque cursor, and an explicit completeness signal. The agent continues only when there is a reason to fetch more. Before exposing a tool over the network, the guide to hosting a remote MCP server in TypeScript with HTTP helps separate transport, authentication, and execution. This article covers another boundary: what the result itself promises.
The code below is a local Node.js fixture. It does not call a model or a real MCP server. Its purpose is to prove the pagination policy, not to measure a provider.
Design rule
- A page is a slice of the result, not a complete answer.
- The cursor should be opaque to the client and valid only for the query and snapshot controlled by the server.
- The response must say whether more data exists instead of making the model infer it from the list length.
- Server-side filtering, aggregation, or a file handle may be better than paging thousands of rows through context.
The meaning matters more than response size
The most dangerous failure is not a response that is too large. It is a partial response that looks final. An items field with ten records does not say whether ten records exist in total, whether the server applied a limit, or whether the query found exactly that set.
That meaning should not live only in a vague instruction inside the tool description. The runtime must be able to record whether the response was complete, and the agent must receive that information with the data. If the tool answers "which orders are late?", the result should carry the condition that permits or prevents the word "all".
There is a second risk: letting the model decide by itself how many pages to read. Without a per-run limit, the tool can consume repeated calls to walk a dataset that should have been filtered on the server. The detector for repeated tool calls and legitimate polling solves a different problem, but the same principle applies: the runtime should know the stopping condition.
Separate protocol pagination from result pagination
MCP already has pagination for protocol list operations. The TypeScript client documentation shows listTools() following nextCursor to aggregate tool pages and also allows a caller to access a specific page with a held cursor (MCP TypeScript SDK, "client calling", retrieved November 20, 2026). That covers discovery of tools, prompts, resources, and templates.
This mechanism does not automatically make a business-tool response into a browsable collection. A tool such as search_orders still needs to define its page format, cursor meaning, record order, and continuation policy. Mixing the two contracts creates a dangerous assumption: nextCursor in tools/list does not guarantee that tools/call knows how to return the rest of search_orders.
If the implementation uses the current TypeScript SDK, structuredContent and outputSchema can make the output contract explicit for the application and client (MCP TypeScript SDK, "server API", retrieved November 20, 2026). The schema still does not decide whether the first page is enough. It makes the decision representable and testable.
What should a result page contain?
Start with a small envelope. The names can vary, but the meaning should stay stable:
| Field | Responsibility |
|---|---|
items |
Records in this page, already bounded by the tool's budget. |
nextCursor |
Opaque token for requesting the next page; absent when there is no continuation. |
complete |
true only when the server knows the query ended for this snapshot. |
snapshot |
Identifier or version used to keep the query consistent when needed. |
notice |
Short text for the model, especially when the result is incomplete or needs a filter. |
complete may look redundant next to nextCursor, but it makes the intent readable. A cursor can expire, be rejected, or disappear in an intermediary layer. The caller should not declare "all" merely because it received fewer items than the limit.
Do not return total by habit. An exact total can require an expensive query, become stale before the next page, or suggest precision the backend does not guarantee. If the decision needs a total, document when it is calculated and which snapshot it represents.
How to keep the cursor stable and safe
The cursor is not a page number for the agent to interpret. It is a continuation receipt issued by the server. It may carry a snapshot version, the last ordered key, and a signature. The client should only send it back.
Three rules prevent most problems:
- Use deterministic ordering. A query that changes order between calls can repeat records or skip them.
- Validate the cursor on the server. Reject malformed tokens, tokens from another query, and tokens from an incompatible snapshot. Do not accept a freely supplied
offsetwhen it can cross tenant boundaries. - Define a lifetime. A cursor may expire when its snapshot is gone. The response should say that the query must restart instead of continuing from a position that no longer represents the same set.
A cursor can be encoded as Base64URL for transport, but encoding is not authentication. If its position reveals sensitive data or can be changed to reach another tenant, sign its contents or store the state on the server behind a random reference.
Node.js fixture: page, cursor, and completeness
The fixture below uses a fixed list to keep verification reproducible. In production, replace orders with a query that has stable ordering and define how the snapshot will be kept. The cursor remains a server detail.
import assert from "node:assert/strict";
const orders = [
{ id: "ord-101", status: "late" },
{ id: "ord-102", status: "paid" },
{ id: "ord-103", status: "late" },
{ id: "ord-104", status: "open" },
{ id: "ord-105", status: "late" },
];
const SNAPSHOT = "orders-v1";
const MAX_PAGE_SIZE = 2;
function encodeCursor(cursor) {
return Buffer.from(JSON.stringify(cursor)).toString("base64url");
}
function decodeCursor(value) {
try {
const cursor = JSON.parse(Buffer.from(value, "base64url").toString("utf8"));
if (cursor.snapshot !== SNAPSHOT || typeof cursor.afterId !== "string") {
throw new Error("cursor does not belong to this result set");
}
return cursor;
} catch (error) {
throw new Error(`invalid cursor: ${error.message}`);
}
}
function listLateOrders({ cursor, limit = MAX_PAGE_SIZE } = {}) {
const pageSize = Math.min(Math.max(limit, 1), MAX_PAGE_SIZE);
const filtered = orders
.filter((order) => order.status === "late")
.sort((a, b) => a.id.localeCompare(b.id));
const start = cursor
? filtered.findIndex((order) => order.id === decodeCursor(cursor).afterId) + 1
: 0;
if (cursor && start === 0) throw new Error("cursor points outside the snapshot");
const items = filtered.slice(start, start + pageSize);
const last = items.at(-1);
const nextCursor = last && start + items.length < filtered.length
? encodeCursor({ snapshot: SNAPSHOT, afterId: last.id })
: undefined;
return {
items,
nextCursor,
complete: nextCursor === undefined,
snapshot: SNAPSHOT,
notice: nextCursor
? "More matching orders exist. Continue only if the task needs all of them."
: "This result is complete for the current snapshot.",
};
}
const first = listLateOrders();
assert.deepEqual(first.items.map((item) => item.id), ["ord-101", "ord-103"]);
assert.equal(first.complete, false);
assert.equal(typeof first.nextCursor, "string");
const second = listLateOrders({ cursor: first.nextCursor });
assert.deepEqual(second.items.map((item) => item.id), ["ord-105"]);
assert.equal(second.complete, true);
assert.equal(second.nextCursor, undefined);
assert.deepEqual(
[...first.items, ...second.items].map((item) => item.id),
["ord-101", "ord-103", "ord-105"],
);
assert.throws(() => listLateOrders({ cursor: "not-a-cursor" }), /invalid cursor/);
console.log("pagination fixture passed");
Save it as mcp-pagination-fixture.mjs and run:
node mcp-pagination-fixture.mjs
The test proves four local properties: ordering is stable, the first page declares that it is incomplete, the second page does not repeat records, and an invalid cursor is rejected. It does not prove that every MCP client will follow the next page, or that a production database snapshot will remain available for the required lifetime.
How should the tool expose the envelope?
The MCP adapter should return the envelope as structured data and a short explanation for the model. The exact details depend on the SDK generation, so the example below is intentionally illustrative:
const result = listLateOrders(args);
return {
content: [{
type: "text",
text: result.complete
? "The result is complete for this snapshot."
: "The result is partial. Use nextCursor only when more records are needed.",
}],
structuredContent: result,
};
The contract-testing guide for MCP servers in TypeScript is the right place to add discovery, schema, and call checks. Include at least one case that checks complete: false, a second case that uses the returned cursor, and a case that proves an incomplete response is not described by the test as a final list.
If the tool declares outputSchema, the schema should represent the continuation and error states the client needs to handle. Do not use a hidden text instruction as the only source of truth. Text helps the model; structure lets the host, test, and log make decisions without parsing prose.
Is pagination always the best interface?
No. The choice depends on what the agent needs to do with the data:
| Need | Better interface | Reason |
|---|---|---|
| Find a few candidates | Filtered search with a small limit | The server reduces the set before context use. |
| Compare every record | Server-side aggregation | The model receives the operation's result, not thousands of rows. |
| Export or reconcile everything | File or export handle | The complete data can be processed outside the conversation. |
| Explore a moderate set | Cursor pagination | The agent can continue explicitly and within bounds. |
| Wait for an external change | Scheduler polling with a deadline | The next time is not controlled freely by the model. |
This choice appears in practitioner discussions about treating one page as the complete dataset and paging an MCP tool that returns many records. Use those reports to recognize symptoms and vocabulary, not as proof that one strategy is always better.
The guide to codebase RAG over MCP for agents that should not read everything starts from a similar premise: retrieving only relevant context is usually better than dumping the whole repository into the model. For transactional data, the concrete form may be filtering, ordering, aggregation, or export, but the principle is the same: the agent should not use context as an accidental database.
What should the runtime observe?
Record enough to explain an incomplete answer without retaining unnecessary data:
- run and query identifiers;
- tool name and contract version;
- snapshot or logical scope used by the page;
- number of returned items and applied limit;
- whether
nextCursorwas present, without logging the cursor in clear text when it carries sensitive information; - stop reason:
complete,page_limit,cursor_expired,invalid_cursor, orexport_required.
The guide to tracing AI agent tool calls with OpenTelemetry covers correlation between run, tool, attempt, and summarized result. Telemetry helps explain why the agent stopped, but it does not replace the dispatcher guard. The page control must block the next call before it reaches the backend.
Method and limits
I checked the current MCP TypeScript client and server documentation on November 20, 2026. It supports the distinction between protocol list pagination and structured data returned by a tool. I also reviewed public practitioner discussions to find questions about completeness, filtering, and export. Those discussions were not used as technical proof.
I wrote and ran the fixture for this article with Node.js. It uses a fixed list and an artificial snapshot, so it is not a benchmark, does not measure tokens, and does not demonstrate model behavior. AI assistance helped organize the research, review the text, and produce the localized versions. It did not run a production agent or provide a quality measurement. When I need to extend a debugging session with less repeated context, I use RemoteCode, a tool I built.
Conclusion
Tool pagination is a promise about completeness. It declares the difference between "these are the records I found on this page" and "this query is finished." An opaque cursor, stable ordering, per-run limit, and completeness field give the runtime a decision that does not depend on guessing the model's intent.
When the agent needs a few candidates, filter on the server. When it needs everything, consider aggregation or export. Use navigable pages for controlled exploration, and let the test prove that an incomplete response cannot pass as complete.