Gemini CLI tightens MCP tool discovery: debounced list_changed refresh, trailing queue, and resilient retries

Gemini CLI’s MCP integration has been steadily gaining real-time awareness of server-side tool changes. A local search trail points to early MCP notifications support landing on 2026-01-08 (commit 5f60281d2528), when list_changed began showing up as a first-class signal in the codebase. But as more servers started emitting frequent change events, a subtle set of reliability issues emerged: refresh storms, missed updates during in-flight executions, and “empty discovery” edge cases that could leave the client thinking no tools existed at all.

PR #21050, merged with commit 352fb0c9, addresses those problems by reshaping how Gemini CLI responds to MCP notifications—especially tools/list_changed. The update focuses on three pragmatic mechanics: a debounced refresh to collapse bursts of notifications into a single fetch, a trailing execution queue to ensure the last observed change is applied after ongoing work completes, and a retry path when discovery unexpectedly returns an empty tool list.

The heart of the fix lives in the MCP client and manager layers (notably packages/core/src/tools/mcp-client.ts and mcp-client-manager.ts). Instead of treating each list_changed notification as an immediate “refresh now,” the client now schedules refreshes with debounce behavior—favoring stability over reflex. When refresh requests arrive while tool execution or discovery is already in progress, the system doesn’t drop them; it records that another refresh is needed and runs a trailing refresh once the current operation settles.

The more defensive twist is what happens when discovery returns empty. Empty tool lists can be legitimate, but they can also be transient—caused by timing gaps, server warm-up, or inconsistent state during an update. The new logic retries discovery when it sees an empty result in situations where tools are expected, preventing the CLI from “forgetting” capabilities due to a single bad response.

Another noteworthy change improves compatibility with imperfect or minimal MCP servers: notification handlers are now registered even if the server capabilities omit an explicit listChanged declaration. In practice, some servers emit list_changed notifications without advertising them cleanly in capabilities; this update makes Gemini CLI more tolerant, opting to listen rather than assuming silence.

Tests were updated alongside the implementation, reflecting a test-driven development (TDD) approach. The revised test suite captures the new timing and sequencing expectations—debounce behavior, queued trailing refresh, and retry-on-empty—reducing the chance of regressions as MCP support evolves.

Why it matters

Tool lists are the contract between Gemini CLI and MCP servers. If the client refreshes too aggressively, it wastes cycles and risks race conditions; if it refreshes too timidly, it runs stale tools. By debouncing notification-driven refreshes, guaranteeing a trailing update after in-flight work, and retrying when discovery returns empty, Gemini CLI becomes both calmer under load and more reliable during server churn—exactly when users need the tool layer to be trustworthy.

Sources

• PR #21050: https://github.com/google-gemini/gemini-cli/pull/21050
• Git commit 352fb0c9 (Gemini CLI): updates in packages/core/src/tools/mcp-client.ts, mcp-client-manager.ts, and related tests
• Local gsio search output: “list_changed results showing MCP notifications support added on 2026-01-08 (commit 5f60281d2528)”