Client.listTools() silently drops pages when a server repeats a cursor

[chelojimenez]

Version

@modelcontextprotocol/client 2.0.0

Summary

When a server returns the same opaque cursor for more than one page, the auto-aggregating listTools() / listPrompts() / listResources() / listResourceTemplates() path stops early and reports the result as complete. The caller cannot tell that pages are missing.

In _listAllPages:

let cursor = acc.nextCursor;
const seen = new Set();
let pages = 1;
while (cursor !== void 0 && !seen.has(cursor)) {
  ...
}
delete acc.nextCursor;

Two things combine here. The loop exits when a cursor repeats, and then nextCursor is deleted from the aggregate, so the truncated list is indistinguishable from a complete one. No error is thrown and nothing is logged.

Why this is a problem

The 2026-07-28 pagination rules say cursors are opaque:

Don't make any determination based on cursor value other than whether a non-null value was provided (e.g. an empty string is a valid cursor and thus MUST NOT be treated as the end of results)

Comparing two cursors for equality is a determination based on their value. Nothing in the spec requires successive pages to carry different tokens, so a server that keeps its pagination position server side and returns one constant handle for every page is behaving legally, and the client drops everything after page two.

The empty string makes this concrete. It is the spec's own example of a valid cursor, and it is a natural choice for a server whose token carries no information, but a server that returns nextCursor: "" twice gets truncated.

A cursor cycle such as A, B, A truncates the same way.

Repro

import { Client } from "@modelcontextprotocol/client";

const PAGES = [
  { name: "alpha", nextCursor: "" },
  { name: "beta", nextCursor: "" },
  { name: "gamma" }, // last page, no nextCursor
];

let index = 0;
const received = [];

const transport = {
  async start() {},
  async close() {},
  async send(message) {
    if (message.id === undefined || message.id === null) return;
    const reply = (result) =>
      queueMicrotask(() =>
        transport.onmessage?.({ jsonrpc: "2.0", id: message.id, result })
      );

    if (message.method === "initialize") {
      return reply({
        protocolVersion: message.params.protocolVersion,
        capabilities: { tools: {} },
        serverInfo: { name: "repeated-cursor", version: "1.0.0" },
      });
    }
    if (message.method === "tools/list") {
      const cursor = message.params?.cursor;
      received.push(cursor);
      if (cursor === undefined) index = 0;
      const page = PAGES[Math.min(index, PAGES.length - 1)];
      index += 1;
      return reply({
        tools: [{ name: page.name, inputSchema: { type: "object" } }],
        ...(page.nextCursor === undefined ? {} : { nextCursor: page.nextCursor }),
      });
    }
    return reply({});
  },
};

const client = new Client({ name: "repro", version: "1.0.0" });
await client.connect(transport);

const result = await client.listTools();
console.log("requests:  ", JSON.stringify(received));
console.log("tools:     ", result.tools.map((t) => t.name).join(", "));
console.log("nextCursor:", JSON.stringify(result.nextCursor));

Actual:

requests:   [null,""]
tools:      alpha, beta
nextCursor: undefined

Expected: alpha, beta, gamma. The server was still offering a cursor after beta, and the third request is never sent.

Suggested fix

Drop the seen set and let listMaxPages bound the walk. The cap already covers the case the dedupe is aimed at, its own docs describe it as "a defence against a server whose nextCursor never converges", and it does that without reading cursor values. It also fails loudly with ListPaginationExceeded instead of returning a short list that looks complete. A server that wants to spin the client can return distinct cursors forever anyway, so the dedupe only catches the one shape that may well be legitimate.

If the dedupe is worth keeping for some reason, throwing on a repeat rather than returning a truncated aggregate would at least make the truncation visible.

Happy to send a PR if you would like one.

Context

Found while fixing our own client so it treats an empty-string nextCursor as a real cursor. Our code is correct now, but the aggregate walk is below us, so the tool list still comes back short for this kind of server.

[mikemikimike]

I am preparing a focused fix for this issue: remove cursor-value deduplication from the auto-pagination walk and rely on the existing listMaxPages bound, with a regression test for repeated opaque cursors. This preserves the protocol rule that cursor values are opaque and keeps non-converging servers bounded.

[mikemikimike]

Implemented in PR #2736: #2736

The client now treats pagination cursors as opaque and follows repeated cursor values until server termination or the existing listMaxPages bound. A regression test covers repeated cursors and verifies request ordering.

Remote verification completed on commit 16a3e1752de0ef0884fa78a3b547acceb39db6d1:

• build, package publish, and examples checks passed
• client/server conformance checks passed
• Node test and E2E matrices passed for runtimes 20, 22, and 24
• Bun and Deno runtime checks passed

Local dependency installation was blocked by a Windows pnpm store permissions error, so the repository CI performed the install and validation in its supported environment.