How do I release MCP tool changes while hosts cache old catalogs?

A deployment can finish before a release reaches hosts

Replacing server replicas changes execution, while a catalog update changes the definitions offered to models. A host that retains the previous definition may continue constructing old arguments against the new implementation. The rollout therefore includes at least two adoption events, often owned by different teams.

Choose observable markers for both. Record the deployed behavior revision and the host’s active catalog revision with candidate traffic. If hosts cannot report their definition revision, identify that measurement gap before claiming complete migration.

Freshness hints leave a migration gap

The MCP caching specification treats TTL as a freshness hint and supports notification-based invalidation. It also permits stale responses during refresh failures. A release cannot assume that wall-clock age proves every consumer refreshed successfully.

Use a local activation policy that states which catalog revisions may still execute. Refresh mechanisms help distribute change; the policy determines the response when a host presents an old or unknown definition. For a harmless lookup, a supported old contract may remain available. For a suspended capability, refresh failure must not preserve authority.

Ninety hosts refresh while ten stay offline

Consider a hypothetical asset assistant with 100 managed hosts. Catalog 31 uses asset.lookup; catalog 32 introduces asset.find with clearer scope and a revised result. The server initially supports both names with their respective promised behavior.

During the pilot, ninety hosts adopt catalog 32 and ten laptops remain offline. The release team sees zero old-name calls for an hour. That is insufficient retirement evidence: the absent hosts still exist and may return with an old definition.

The team keeps compatibility until every supported returning host either refreshes before execution or receives a clear upgrade-required response. One offline-host drill exposes a startup cache that ordinary canary traffic never exercised.

Use a migration board with observable exits

This release artifact records what must be true before progressing. The proposed gates are illustrative and need risk-specific ownership.

Stage	Change	Evidence to advance	Failure response
Expand	Server accepts both documented contracts	Old and new host checks pass	Restore prior server before new activation
Pilot	Small named cohort sees new definition	Correct selection, rendering, and catalog identity	Freeze cohort and restore compatible activation
Broaden	Additional supported hosts refresh	Adoption and outcomes compared with control	Stop expansion and inspect affected path
Return test	Offline host reconnects with old cache	Refresh or explicit supported rejection	Keep old support while adapter is corrected
Retire	Remove old selectable definition and handler	Remaining consumers resolved; support deadline met	Use agreed recovery path, not silent alias substitution

Attach the exact catalog, server, policy, and backend versions. A rollback action is valid only for combinations already supported by the compatibility matrix.

Select canaries by the paths they cover

Canary release guidance provides the candidate-versus-control framework. For MCP, choose hosts that exercise different client builds, cache behavior, tool-selection contexts, and relevant result renderers. A random percentage dominated by one popular read tool may never touch the changed path.

Compare the offered definition, selected tool, accepted arguments, result interpretation, and user outcome. Protocol error rates are useful but cannot identify a model that now selects an unintended tool while every request remains valid.

Rehearse stale and mixed states explicitly

Test missed notifications, refresh failure, returning offline hosts, and partial catalog fetches. Record whether the host preserves a permitted old snapshot, rebuilds consistently, or stops the affected capability. Avoid silently merging fragments of different catalog generations into an unreviewed definition set.

For stateful workflows, decide which contract handles work started before activation. This guide does not prescribe the workflow state machine; it requires the release to identify that dependency and exercise the supported transition.

Retire behavior with consumer evidence

Old traffic reaching zero is useful evidence only relative to the expected consumers and their activity cycle. Combine it with fleet inventory, supported-host return behavior, owner acknowledgments where necessary, and explicit handling of unknown clients.

After retirement, retain the old identity in historical records so earlier selections remain explainable. For an unsafe tool, containment can override graceful coexistence. Record that as a suspension with user-visible consequences, not a successful ordinary migration.