MCP server that starts after Claude Code is never connected — no retry, and /mcp reconnect fails with "No token data found"

MCP server that starts after Claude Code is never connected — no retry, and /mcp reconnect fails with "No token data found"

Summary

Claude Code appears to resolve and connect MCP servers once, at process
startup, and caches a failed connection for the lifetime of the
process. If a local MCP server isn't running yet when claude starts,
that server is marked failed and is never retried — not on the next
tools/call, not on /clear, and /mcp → reconnect fails outright.
The only recovery is fully quitting and restarting the claude process.

This makes any MCP server that ships inside a desktop app (the server
starts when the user opens the app) look permanently broken whenever the
user's terminal was opened first — a very common ordering. The support
burden lands on the MCP server vendor, and the natural recovery commands a
user reaches for (/mcp reconnect, /clear) don't work.

Environment

• Claude Code 2.1.248
• macOS 26.6.2
• Reproduced with a local HTTP MCP server (localhost + bearer token from

.mcp.json) and with a stdio server; the failure mode is the same.

Repro 1 — failed server is cached for the process lifetime

1. Configure a local MCP server (HTTP transport, http://127.0.0.1:<port>

with a bearer token, or a stdio command that requires the companion app).

1. Start claude while the server/app is not running.

→ Connection fails (ConnectionRefused in
~/Library/Caches/claude-cli-nodejs/<project>/mcp-logs-<name>/*.jsonl,
3 attempts at startup, then nothing).

1. Start the server/app. Verify it's reachable (curl succeeds).
2. In the same claude session: the server still shows failed in

/mcp; its tools are unavailable.

1. /clear and start a new conversation → still failed (same process).
2. Quit claude entirely and relaunch → connects instantly.

Expected: a failed server is retried lazily — on the next /mcp
view, on the next attempted tools/call, or at minimum via an explicit
reconnect action.

Repro 2 — /mcp reconnect uses stale transport + current credentials

Observed when the server's configuration changed while a claude process
was running (in our case the config migrated from an HTTP+bearer entry to
a stdio command entry):

1. claude started under the old config (HTTP + bearer), server marked

failed as above.

1. Config file now specifies the stdio transport.
2. /mcp → select the server → reconnect.

→ Fails with "No token data found".

The reconnect appears to reuse the transport pinned at boot (HTTP)
while resolving credentials from the current config (which no longer
has a token) — a mismatched half-and-half read. Expected: reconnect
re-reads the current config atomically (transport + credentials together),
or clearly reports that a restart is required.

Impact

• Desktop-app-bundled MCP servers (app launches the server) present as

broken for every user whose terminal session predates the app launch.

• The in-product recovery affordances (/mcp reconnect) fail, so users

escalate to the server vendor rather than restarting the client.

• Vendors end up documenting "fully restart Claude Code (quitting the

conversation is not enough)" as a support FAQ — which works, but is the
kind of workaround users find only after concluding the server is broken.

Suggested behavior

1. Retry failed MCP servers lazily: on /mcp open, and/or on the first

tools/call addressed to a failed server.

1. Make /mcp reconnect perform a full fresh connection from the

current config (transport, credentials, everything), not the
boot-time snapshot.

1. If a config change genuinely requires a restart, say so explicitly in

the reconnect failure message instead of a credentials error.