What Should Happen When an MCP Tool List Changes?

General
1

When an MCP Tool List Changes, Refresh the Session Before Routing Again

An MCP client should treat notifications/tools/list_changed as a catalog invalidation for one server session—not as permission to mutate a shared list in place.

The protocol gives us two useful signals. A server can declare tools.listChanged, and it can notify the client when its available tools change. The tools/list request is also paginated. So the safe refresh boundary is:

  1. Mark the notifying session’s catalog as refreshing.
  2. Re-run tools/list from the first page and follow every cursor until the traversal completes.
  3. Build a new complete snapshot off to the side.
  4. Swap that snapshot into the session’s cache atomically only after the full traversal succeeds.

Until then, callers should continue using the last complete snapshot—or fail closed according to the integration’s policy. They should never see page 1 from the new catalog combined with pages from the old one. The MCP specification defines the notification and pagination contract; session scoping, atomic replacement, retry behavior, and last-known-good retention are client design choices.

This boundary matters in a CometAPI integration because the tool catalog is an input to the next routing decision. CometAPI’s multi-model fallback playbook treats fallback as an explicit reliability workflow. Apply the same discipline here: do not route a request to a newly advertised tool—or choose a fallback path that depends on it—until the notifying session’s refresh has completed successfully. If the refresh fails, keep the prior catalog and surface a refresh-status signal so the caller can choose a known-good route or stop.

The result is a small but important separation of concerns: MCP tells the client that its view may be stale; the CometAPI integration decides when that view is complete enough to influence routing. That makes tool discovery, model/provider fallback, and failure handling observable without claiming that MCP itself prescribes a cache implementation.

Sources: MCP Tools specification; CometAPI Multi-Model Fallback Playbook.

2

One additional boundary matters for visual workflows: a tool-list refresh should also be treated as a version change to the pipeline plan, not only to the session cache.

A render or asset job can depend on more than a tool name. It may rely on an input schema, supported media types, size limits, or a particular composition step. I would record the catalog version (or a content hash) alongside each queued job and the selected tool’s relevant schema. If notifications/tools/list_changed arrives before execution, refresh the session and re-check that plan against the new complete snapshot. If the tool or schema has changed, invalidate or re-plan the not-yet-started step rather than silently substituting a similarly named tool.

For work already in progress, keep the tool and schema used for that step fixed until its result is complete, while making the new catalog available to later steps only after the atomic swap. This separates artifact lineage from discovery state: a failed refresh does not corrupt an existing render plan, and a successful refresh cannot introduce an unreviewed parameter change halfway through a multi-step composition.