What happened
The public repository for mcp-restart describes an MIT-licensed Claude Code plugin and proxy for restarting MCP servers during a running Claude Code session. It is intended for stdio servers and has been tested with Claude Code 2.1.309 in both the Claude desktop app and CLI on Windows 11. The project is Windows-only for now and requires Node 22 or later on PATH.
The stated problem is specific to the way a Claude Code session manages connected MCP servers. According to the README, the desktop app has no reconnect or restart control for an already connected server. If a server process dies, the next tool call can start it again, but the session retains the tool list it originally read. Tools added, renamed, or removed after that point can therefore remain unavailable or inaccurate until a new session starts. The README also says that if a new server start fails, the server can remain unusable for that session even after the underlying issue is fixed.
mcp-restart places a proxy between Claude Code and each configured server. The Claude session stays connected to the proxy while the proxy runs the actual server as a child process. On a normal restart, it starts a new server alongside the old one and replays the session initialization. Only after the replacement answers does the proxy direct new calls to it. The old server may finish in-flight calls for up to 30 seconds before it is stopped. The proxy then sends a tools/list_changed notification so Claude Code reads the server's tool list again. If the new server cannot start, the proxy stops the failed replacement and leaves the old server serving requests.
The plugin exposes mcp__mcp-restart__restart_server and mcp__mcp-restart__list_servers to Claude. It also adds /mcp-restart commands for listing, wrapping, unwrapping, and restarting configured servers. In the desktop app it presents a pane with server mode, uptime, stale status, and running calls, plus controls for ordinary, forced, stale-only, and all-server restarts. A watchdog displays a restart option after a call has hung for 60 seconds; a forced restart interrupts calls in progress. The project defines “stale” through changes to selected local files such as a server script or executable, node_modules\\package-lock.json, a Python environment's Lib\\site-packages, or a uv.lock file. Servers run via npx or uvx do not have local files the tool can compare.
Installation can happen through Claude Code's plugin marketplace commands, or through the desktop application's Plugins interface. Users then run /mcp-restart wrap all, which rewrites MCP configuration so targeted servers launch through the proxy while retaining their environment. Existing sessions remain unwrapped; the README says a new session is required to get hot-swap behavior. Configuration files changed by wrapping are backed up once per run.
What the archive adds
This is a new fact on a known MCP-and-Claude-Code thread, rather than another MCP server launch. Earlier Field Notes covered Claude Code support for MCP Tasks and Elicitations, Upstash's MCP Tasks toolkit, and DeployHQ's read-only MCP server. mcp-restart instead changes the local operational lifecycle of existing stdio servers.
Trend signal
This supports agent protocols become the interoperability layer. The utility is not a new protocol: it depends on MCP behavior such as initialization and tool-list-change notifications. But it shows that once tools share a protocol surface, developers can build a separate lifecycle layer around heterogeneous servers without changing their tool implementations.
Why it matters
An MCP server under active development often combines code changes, dependencies, credentials, and tool-schema changes. Restarting the entire coding-agent session after each repair can discard working context precisely when the developer needs it to diagnose the integration. A proxy that preserves the client-facing connection while validating a replacement server offers a more controlled failure path: the old server remains available when a new version fails, while changed tools can become visible after a successful swap.
That does not make the proxy a general reliability solution. It is most relevant to a Windows developer who already runs local stdio MCP servers through Claude Code and repeatedly edits those servers. For that narrow workflow, the tool makes server lifecycle management an explicit part of the integration harness: restart, observe, retry, and refresh tool discovery without necessarily resetting the agent conversation.
What happens next
- More MCP clients or plugins will expose explicit server reload controls. (6 months, 55%). Watch for: client-side reconnect or tool-refresh commands that remove the need for a proxy.
- MCP server developers will add reload and failure-recovery steps to local test workflows. (3 months, 60%). Watch for: test guidance that exercises changed tool lists and interrupted calls.
Limits and uncertainty
The repository describes the behavior and its own testing, but it does not establish reliability across other operating systems, Claude Code versions, MCP clients, or server implementations. The documented testing is limited to Claude Code 2.1.309 on Windows 11. The tool rewrites MCP configuration, so teams should inspect the generated changes and backups before using it with production credentials or shared configurations. The README's claims about Claude Code session behavior are implementation observations, not a guarantee of long-term client behavior. No independent performance, security, or compatibility evaluation is supplied.
Skill to build now
Treat a local MCP server update as a lifecycle test, not just a code change. This week, choose one development server and test four cases: a clean restart, a replacement that fails to start, a changed tool name, and an in-flight call interrupted by a forced restart. Record whether the client refreshes discovery, preserves a usable fallback, and reports the failure clearly. Those checks reveal whether an MCP workflow can survive ordinary iteration without misleading the agent about the tools it can call.
Reader takeaway
mcp-restart addresses an unglamorous but practical boundary in local MCP development: a server can change while an agent session is still valuable. Its proxy approach preserves the session connection, swaps only a server that successfully starts, and asks Claude Code to refresh tools. It is a Windows-specific workaround, not a universal MCP lifecycle standard.