MCP v2 Can Return a Partial Tool List as Complete

The sharp question: can an AI agent tell that tool discovery stopped early?

An MCP client uses tools/list to learn what an AI agent may call. Version 2.0.0 of the TypeScript client makes the common cursorless call convenient: listTools() walks pages and returns one aggregate. That convenience creates a reliability promise at the application boundary. If the aggregate is partial, the caller needs a visible failure or a surviving continuation signal.

My three-page fixture produced neither. Page one returned alpha and nextCursor:"". Page two returned beta and the same empty-string cursor. Page three was ready to return gamma and terminate. The client sent only the first two requests, returned alpha and beta, removed nextCursor, and threw no error. From ordinary application code, the short inventory looked complete.

Chronology: discovery moved from a protocol primitive to an SDK aggregate

Anthropic announced MCP on November 25, 2024 as an open standard connecting AI assistants to data sources and tools. Tool discovery was a protocol operation: a client requested tools/list and servers could paginate the result.

The July 28, 2026 protocol says cursor values are opaque and explicitly calls an empty string a valid cursor. The split @modelcontextprotocol/client 2.0.0 package was published through npm on July 27. Its cursorless list methods add automatic aggregation and a default page cap. On August 28, independent contributor issue 2735 reported that a repeated cursor could stop this aggregate early. This investigation reproduced that boundary on September 1 with controls rather than treating the report as proof.

The protocol gives presence meaning, not cursor text

The pagination specification tells clients not to make a determination from a cursor value beyond whether a non-null value was provided. It uses the empty string to make the point concrete: falsy does not mean finished. Completion is represented by omitting nextCursor from the response.

The specification does not require each successive cursor string to be unique. A server may encode position in the token, keep position in server-side state, or use another opaque strategy. Equality can still be useful as a defensive signal, but turning equality into successful completion adds a client policy not expressed by the wire contract.

The client promises one complete aggregate

The distributed client documents that listTools without an explicit cursor walks every page, returns the complete aggregated list with no nextCursor and writes that aggregate to its response cache. Supplying an explicit cursor takes a different per-page path that returns the raw page.

That distinction matters for agent hosts. A caller choosing auto-aggregation does not receive each intermediate continuation decision. It delegates traversal and expects either a complete collection or a visible failure. The returned absence of nextCursor is therefore read as SDK finalization, not direct evidence that the server sent a terminal page.

The loop has two nonconvergence controls with different outcomes

Inside _listAllPages, the client stores cursor strings in a seen set. Its loop continues only while cursor is defined and has not appeared before. A configured listMaxPages check sits inside that loop and throws LIST_PAGINATION_EXCEEDED when a distinct sequence reaches the cap.

When a cursor repeats, the while condition becomes false before the cap branch. Execution then deletes acc.nextCursor, finalizes the aggregate and can write it to cache. The repeated-cursor path is therefore a successful return; the page-cap path is a loud failure. Both detect possible nonconvergence, but only one preserves uncertainty for the caller.

The fixture offered three tools behind one opaque handle

The checked-in audit uses a minimal transport implementing initialize and tools/list. Its repeated-cursor scenario serves alpha with nextCursor:"", beta with nextCursor:"", and gamma with no nextCursor. Every page contains one inert synthetic tool definition with an object input schema. No callTool request exists, so the experiment cannot cause an external action.

The transport records the cursor on every tools/list request. This lets the test distinguish a short aggregate from a fully traversed server: receiving [undefined, ""] means page three was never requested. The server fixture is synthetic and intentionally exercises a legal-value edge case; it is not offered as a prevalence claim.

Repeated empty string stopped after request two

The first call carried no cursor and returned alpha plus the empty-string continuation. The second request correctly carried cursor:"" and received beta plus the same continuation. At that point the seen set already contained the empty string, so the loop did not issue a third request.

Five assertions bound the observed result: the request sequence was [undefined, ""]; the tool names were ["alpha", "beta"]; nextCursor was undefined; exactly two requests were made; and gamma was absent. No exception was raised. The result matched the mechanism visible in the pinned bundle.

Unique cursors reached the terminal page

The first control changed only the continuation sequence: page one returned after-alpha, page two returned after-beta, and page three omitted nextCursor. The client sent [undefined, "after-alpha", "after-beta"] and returned alpha, beta and gamma.

This control rules out a generic transport, schema or fixture failure. Version 2.0.0 can aggregate three pages through the same code path. The material difference was cursor equality, not item count, page count, tool shape or the final page.

The page cap failed loudly when cursors stayed distinct

The second control generated a different cursor forever and configured listMaxPages:3. The client requested the initial page and two continuations, then raised LIST_PAGINATION_EXCEEDED with the message “tools/list: exceeded listMaxPages (3); server pagination did not terminate.”

That is the safer failure shape: application code can quarantine discovery, retain its previous inventory or alert an operator. The test does not prove that removing cursor deduplication is the only correct fix. It demonstrates that the existing page cap already detects one nonconverging sequence without returning a partial aggregate as complete.

A partial inventory changes agent behavior without adding a malicious tool

Most MCP security discussion focuses on an untrusted tool entering the inventory. Truncation creates the inverse failure: an expected control, lookup or recovery tool can disappear. A planner may choose a more privileged fallback, tell a user that a capability is unavailable, or route work to a different system because the local inventory is incomplete.

This probe did not run a model and therefore does not establish any of those downstream outcomes. It establishes the prerequisite state: application code received two tools as a finalized aggregate even though the synthetic server still offered a third page. Agent impact depends on how a host reconciles and uses that inventory.

Caching can make one ambiguous walk last longer

The _listAllPages implementation deletes nextCursor before its cache write. Whether a later listTools call reuses the result depends on cache freshness configuration and invalidation. A positive TTL can therefore turn one truncated walk into the inventory served to subsequent callers until refresh or list_changed handling replaces it.

The audit used the default freshness behavior and did not test cache reuse, list_changed races or reconnects. Teams should nevertheless treat cache admission as part of completeness: never write a discovery result to a trusted cache merely because traversal returned normally. Admission needs an independent reason to believe the terminal condition was real.

Preserve the difference between server termination and client termination

Record why a walk ended. “Server omitted nextCursor” is materially different from “client saw the same token,” “page budget expired,” “request timed out,” “schema parsing failed” or “inventory changed mid-walk.” Collapsing those states into nextCursor:undefined destroys evidence the host needs for policy.

A wrapper can expose a traversal receipt containing server identity, protocol and SDK versions, page count, cursor digests, terminal reason, item count, duplicate-name decisions and schema digests. Hash cursor values before durable logs when they may be sensitive. The receipt—not an absent property alone—should control whether an agent can plan against the result.

Inventory reconciliation provides a second completeness signal

For production servers, compare discovery against an approved manifest or a minimum required capability set. The goal is not to freeze every dynamic tool forever. It is to catch implausible removal of critical tools, duplicate identity, unauthorized additions and large count changes before a model adapts to them.

When inventory is expected to vary by user or tenant, scope the baseline to the authenticated principal and policy context. A mismatch should suspend new autonomous calls, preserve the last known-good registry where safe, and trigger a bounded refresh. Do not silently route around a missing approval, validation or rollback tool.

Test all four list families and both pagination modes

The same _listAllPages helper backs automatic prompts, resources, resource-template and tools lists. The local audit exercised tools/list only. A production compatibility suite should cover each capability the host uses with empty, repeated and cycling cursors; terminal and nonterminal empty pages; maximum page counts; duplicate items; timeouts; and list changes during traversal.

Also compare cursorless auto-aggregation with explicit per-page calls. The explicit path gives the host raw continuation state, but it also makes the host responsible for bounds, retries, identity and atomic installation. A passing happy-path array comparison is insufficient; negative tests must prove that ambiguous termination never becomes an approved registry.

What failed, and what the evidence does not establish

A lookup for a GitHub release tagged 2.0.0 returned 404, so I did not invent a release entry or date from that endpoint. I used the official npm package publication record and installed artifact instead. The checked-in audit then passed all fifteen assertions and removed its temporary dependency tree.

The probe did not test a language model, production MCP host, v1 SDK, another language SDK, remote HTTP or stdio, authentication, retries, concurrent walks, cancellation, response-cache reuse, list_changed, reconnect, prompts, resources, resource templates, hostile pages, large inventories, real side effects or user data. It does not establish prevalence, exploitability or maintainer intent. Issue 2735 is independent reporting, not independent reproduction of this run.

Decision: approve only inventories with an explicit terminal receipt

Deploy automatic MCP discovery for an autonomous AI agent only when the exact client version fails closed on ambiguous pagination, bounds pages and items, distinguishes server termination from client guards, validates every page, reconciles critical capabilities and atomically installs one complete registry. Until then, constrain discovery behind a wrapper that walks pages explicitly and produces a terminal receipt.

Reject or roll back when a repeated or cycling cursor returns success, when nextCursor is removed without a terminal server response, when a page cap produces a partial cache entry, when critical tools disappear without an approved change, or when the host lets a model plan during traversal. The safe fallback is a pinned last known-good inventory or no autonomous call—not an apparently complete short list.

Disclosures

AccessAllGPT created and ran only the synthetic local fixture in the checked-in harness. Public issue 2735 prompted the question but did not supply private information or validate this run. No model, production client, third-party MCP server, credential, external endpoint or user data was used. The MCP project, Anthropic, npm, the issue author and SDK maintainers did not review this article or provide access, private data, payment or endorsement. AccessAllGPT Research is operated by NeuralArc, is independent, and is not affiliated with OpenAI, Anthropic, the MCP project or npm. Publication-wide relationships are listed on the disclosures page.