How MCP clients reload configuration and cache tools

Use the smallest reload that matches the change

Saving an MCP configuration file, restarting a server process, refreshing the discovered tool list, and repeating OAuth are separate actions. Start with the client-specific configuration action, then verify the server status and tool list before escalating. Reauthorization is for an authentication state, not a general-purpose cache clear.

The protocol separates server connection from tool discovery. A client obtains tools with tools/list, and a server that declares listChanged can notify the client when that list changes. Whether a particular client refreshes automatically, retains a cached list, or exposes a manual reset remains client behavior.

Configuration changed

Reload or restart the configured serverUse the documented client action; a saved file alone does not prove the running connection changed.

Server code changed

Restart the server processThen inspect the client-visible tool list.

Tool names or schemas changed

Refresh or reset discovered toolsUse a client cache action when one is documented.

Authentication failed

Reconnect or reauthorizeDo this only after status or logs identify an authentication problem.

Diagnose the boundary before clearing anything

First confirm that the client loaded the intended project or user configuration and that the server is enabled. Next inspect connection status and logs. Then compare the client-visible tool names and schemas with the server version you expected. This sequence distinguishes a file-loading problem from a process problem and a stale discovery list.

If the connection is healthy but old tools remain visible, use the client's tool-refresh action. VS Code names this action MCP: Reset Cached Tools. Claude Code normally responds to list_changed, but its documentation says a failed refresh preserves the previously discovered capabilities until a later refresh succeeds.

Recognize a stale tool cache

A stale tool list is narrower than a broken server: the client can connect, but tool names, descriptions, or schemas do not match the server version you intended to run. Confirm the mismatch in the client's tool browser or list command before resetting discovery state.

Claude Code can display a cached status for a remote server when it loads a prior session's tool list and delays connection until first use. Its documentation says the tools remain available from the first message and provides MCP_DISCOVERY_CACHE=0 for users who want every server to connect at startup. That discovery cache is different from a failed dynamic refresh, which preserves the previous list until another refresh succeeds.

Dated reload behavior by client

The entries below reflect first-party documentation accessed on August 8, 2026. They are documentation verification, not a fresh hands-on acceptance run on every client build.

VS Code

Restart Server; Reset Cached Tools when neededConfiguration changes require the MCP server to (re)start. The experimental chat.mcp.autostart setting can restart on detected configuration changes; MCP: Reset Cached Tools clears a stale tool list.

Claude Code

Automatic list_changed refresh; manual retry in /mcpClaude Code refreshes capabilities after list_changed. If refresh fails it retains the previous capabilities; remote HTTP or SSE reconnects automatically, while stdio does not.

Cursor editor

Restart Cursor after updating custom server filesCursor's current update FAQ gives this step for custom servers. Use Customize and MCP Logs to inspect enabled state, initialization, and connection errors.

Cursor CLI

Login is immediate; verify with list-toolsThe CLI documents immediate access after agent mcp login and exposes agent mcp list and agent mcp list-tools for status and discovery checks.

Continue with the right client guide

Use the client directory when the configuration was never loaded, the location guide when the wrong scope may have been edited, or the VS Code guide for that client's server schema and OAuth flow.

Page boundary and research limits

This page owns the difference between configuration reload, server restart, tool discovery refresh, and reauthorization. It does not claim one universal reload command or borrow a control from one client for another.

The last30days pass returned 90 items across eight sources, but only five directly addressed a client reload, restart, reauthorization, or tool-discovery action. ArXiv timed out, Reddit was partial, Techmeme returned no results, and X was not configured. No community item is used to establish a client contract; current first-party documentation supplies the dated behavioral evidence.