> This page is for Developer.

> For clean Markdown of any page, append .md to the page URL.
> For a complete documentation index, see https://docs.bigcommerce.com/llms.txt.
> For AI client integration (Claude Code, Cursor, etc.), connect to the MCP server at https://docs.bigcommerce.com/_mcp/server.

# Agent Behavior for Tool Resynchronization

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.

## How tool availability works

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.

## What happens when a tool is no longer available

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.

```mermaid
sequenceDiagram
    participant Agent
    participant MCP Server

    Agent->>MCP Server: tools/list
    MCP Server-->>Agent: tools: [A, B, C]
    Note over MCP Server: Something changes server-side<br />(permissions, feature flag, config)
    Agent->>MCP Server: tools/call B
    MCP Server-->>Agent: error -32601 (Method Not Found)
    Agent->>MCP Server: tools/list
    MCP Server-->>Agent: tools: [A, C]
    Note over Agent: Tool B is no longer available.<br />Updated tool set: A and C.
```

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.

## What causes the tool set to change mid-session

Several things can cause the available tools to change while a session is active:

| Trigger                                               | What changes                                             | How it surfaces                                                                   |
| ----------------------------------------------------- | -------------------------------------------------------- | --------------------------------------------------------------------------------- |
| User logs in or out                                   | Tools scoped to authentication state appear or disappear | Typically accompanied by a session change                                         |
| User role changes (for example, elevated permissions) | Role-gated tools added or removed                        | May come with a session change, or may be silent                                  |
| Feature flag updates                                  | Flagged tools enabled or disabled                        | **Silent** — no session event, no error until the next `tools/list` or a `-32601` |
| Server-side configuration change                      | Tools tied to config appear or disappear                 | **Silent** — same as feature flags                                                |

> **Warning**
>
> 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.

## Keeping the tool list fresh

There are several natural sync points where a fresh `tools/list` call keeps things in sync:

* **After a `-32601` error** — this is the clearest signal that the cached list is out of date.
* **After session reconnect or re-initialization** — the session context may have changed, and the tool set along with it.
* **Periodically during long-running sessions** — a 60-second interval is a reasonable baseline for catching silent changes like feature flag flips. Shorter intervals make sense for sessions where user state changes frequently; longer intervals are fine for stable sessions.
* **At the start of each conversation turn** — calling `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.

## Current limitations

### No push notifications for tool list changes

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`.

### No cache TTL signal

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.

### How resynchronization works today

The current model is **pull-based**:

* **Error-driven**: A `-32601` response signals that the cached list is out of date.
* **Time-driven**: Periodic re-fetching catches silent changes (feature flags, config updates).
* **Event-driven**: Session reconnects and auth state changes are natural moments to re-fetch.

## What's coming in the spec

The [MCP 2026-07-28 specification](https://blog.modelcontextprotocol.io/posts/2026-07-28-release-candidate/) — the largest revision since launch — ships on July 28, 2026 and introduces changes that directly affect resynchronization:

* **Sessionless protocol.** `Mcp-Session-Id` and the `initialize` handshake are removed entirely ([SEP-2567](https://modelcontextprotocol.io/seps/2567-sessionless-mcp)). 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.

> **Info**
>
> 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.

## UX recommendations

A few things that lead to a better experience when tool availability changes:

* **Translate errors into context.** A `-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.
* **Surface changes proactively.** When a re-fetch reveals new tools or removed tools, letting the user know ("You now have access to quoting tools" or "Order history is no longer available") builds trust and reduces confusion.
* **Avoid silent retries on removed tools.** If a tool is gone after a re-fetch, continuing to call it creates a poor loop. Acknowledging the change and moving on is a better experience.
* **Keep the conversation going.** A tool disappearing does not mean the session is broken — the agent still has access to everything else in the updated list. Framing it as a capability change rather than an error keeps things smooth.