MCP servers can dynamically manage tool availability based on user identity, permissions, feature flags, and configuration. This means the set of tools an agent discovers at session start can change mid-session — tools may be added, removed, or updated after the initial tools/list fetch.
This page describes how the system behaves when tool availability changes, what signals agents can expect, and recommendations for delivering a smooth user experience.
The server evaluates tool availability on every tools/list request. Each call returns the current-truth tool set for the requesting session — there is no stale server-side cache. If something changed since the last fetch (a permission update, a feature flag flip, a config change), the next tools/list response reflects it.
This means tools/list is always safe to call and always returns an accurate snapshot.
However, agents typically cache the tools/list response and reuse it across multiple conversation turns. That cached copy can go stale if something changes on the server between fetches.
If an agent calls a tool that is no longer registered for the current session context, the server responds with JSON-RPC error code -32601 (Method Not Found). This is the standard MCP error for “this tool doesn’t exist in the current tool set.”
This is not an auth failure or a server error — it means the tool was available when the agent last fetched the list, but is not anymore. The most common cause is that something changed (permissions, flags, config) between the last tools/list call and the tools/call attempt.
After receiving a -32601, a fresh tools/list call returns the updated set. Comparing the old and new lists makes it straightforward to identify what changed.
Several things can cause the available tools to change while a session is active:
Feature flag and configuration changes update the tool set on the server immediately, but there is no proactive signal to connected agents. The agent’s cached list becomes stale until it either re-fetches tools/list or hits a -32601 on a removed tool.
There are several natural sync points where a fresh tools/list call keeps things in sync:
-32601 error — this is the clearest signal that the cached list is out of date.tools/list per turn is safe (the server always returns current truth) and adds only minor latency.Since tools/list is evaluated per-request and is lightweight, calling it more often than strictly necessary has minimal cost.
The server does not currently push notifications when the tool set changes. There is no proactive signal to connected agents — the agent’s cached list becomes stale until it re-fetches or hits a -32601.
The tools/list response does not currently include a TTL or expiration hint. There is no server-provided signal telling the agent when its cached list should be considered stale.
The current model is pull-based:
-32601 response signals that the cached list is out of date.The MCP 2026-07-28 specification — the largest revision since launch — ships on July 28, 2026 and introduces changes that directly affect resynchronization:
Mcp-Session-Id and the initialize handshake are removed entirely (SEP-2567). The base protocol goes stateless — every request stands on its own. Servers that need to carry state across calls mint explicit handles (for example, a basket_id) that the model threads through subsequent tool arguments, replacing implicit session-scoped state. This eliminates the need for sticky routing and shared session stores at the protocol layer.ttlMs and cacheScope on list results. Modeled on HTTP Cache-Control, these fields let the server tell agents exactly how long a tools/list response is fresh and whether it is safe to share across users. This replaces the current guesswork around polling intervals with a concrete, server-informed signal.Mcp-Method and Mcp-Name headers on Streamable HTTP. These allow load balancers and gateways to route based on the MCP operation without inspecting the request body, making plain round-robin load balancing viable for MCP deployments.BigCommerce plans to evaluate and adopt the relevant parts of this spec once it is finalized. The pull-based resync model described on this page continues to work as a baseline regardless — the spec additions are improvements on top of it, not replacements.
A few things that lead to a better experience when tool availability changes:
-32601 is a protocol detail. Something like “This feature is no longer available — your permissions may have changed” is more helpful to an end user.