Reconnect action unreachable for mcpServers entries added by direct ~/.claude.json edit

Product: Claude Code SDK v2.1.119, Claude Desktop on macOS

Severity: Medium — recovery from transient auth failures requires renaming server keys, no in-app remediation path

Summary:

The v2.1.118 changelog notes a fix for "HTTP/SSE MCP servers with custom headers being stuck in 'needs authentication' after a transient 401" by exposing a Reconnect action in the /mcp menu. That fix only reaches MCP servers registered through Claude Desktop's Connectors UI (Settings → Connectors). MCP servers added by directly editing the top-level mcpServers block in ~/.claude.json — the documented configuration path for many remote HTTP servers — are not surfaced in the Connectors UI at all. They therefore have no Reconnect surface, and once they enter the stuck "needs authentication" state, there is no in-app way to recover them. The only fix I found is to rename the server keys to force fresh registration.

Steps to reproduce:

1. Configure a remote HTTP MCP server by directly editing ~/.claude.json. Example:

``json
"mcpServers": {
"digitalocean-accounts": {
"type": "http",
"url": "https://accounts.mcp.digitalocean.com/mcp",
"headers": {
"Authorization": "Bearer <your_api_token>"
}
}
}
``

1. Use the server normally for several days (it works fine).

1. Have the upstream server experience a transient 401 Unauthorized during a deployment. (In my case, DigitalOcean deployed mcp-digitalocean v1.0.49 at 2026-04-24 07:01 UTC.)

1. From this point onward, every tool call to the server returns:

``
api error: GET https://api.digitalocean.com/v2/account: 401 (request "...") Unable to authenticate you
`
This error originates upstream — the MCP server proxies our request to the DO API and DO rejects it because the token never reached the MCP server in a usable form. (curl -H "Authorization: Bearer <same-token>" https://accounts.mcp.digitalocean.com/mcp with an identical tools/call` payload returns 200 OK and the correct data, confirming the token, URL, and upstream are all healthy.)

1. Quit Claude Desktop (Cmd+Q), relaunch — server is still stuck.

1. Update Claude Desktop to a build containing SDK v2.1.118 or later (I went from v2.1.111 to v2.1.119) — server is still stuck.

1. Open Settings → Connectors. The manually-added server is not listed there. There is no Reconnect button to find.

1. The chat-line /mcp slash command returns "/mcp isn't available in this environment" in Claude Desktop, so the CLI's /mcp Reconnect surface is unreachable from Desktop.

1. Workaround: rename the server key in ~/.claude.json (e.g., digitalocean-accounts → do-accounts). After quit/relaunch, the new key registers fresh and works immediately.

What should have happened:

After updating to a build with the v2.1.118 fix, there should have been a way to trigger Reconnect on the stuck servers without renaming. Specifically, one of:

• Manually-edited mcpServers entries should appear in the Connectors UI alongside UI-added connectors, with the same Reconnect action.
• The chat-line /mcp slash command should be available in Claude Desktop's Code chat, exposing the same Reconnect menu the CLI has.
• A claude mcp reconnect <name> (or claude mcp reset <name>) CLI subcommand should exist for headless recovery.

Root cause analysis:

The v2.1.118 fix wired the Reconnect action into the Connectors UI surface. Manually-edited mcpServers entries have no UI surface — Settings → Connectors only shows connectors it added itself. So the fix exists but cannot be reached for the entries that arguably need it most (remote HTTP servers configured via the documented JSON method).

I confirmed the stuck state is keyed to the server name and persists across quit/relaunch. Searching ~/Library/Application Support/Claude/Local Storage/leveldb for the original digitalocean-* names turns up at least one MCP-prefixed entry ($mcp__digit... fragment visible in the LDB strings), suggesting the runtime cache is in Electron's LevelDB. Renaming the server keys bypasses the cache by creating a new cache key, which is why it works.

Impact:

• A transient 401 from any remote HTTP MCP server (or any deployment-time blip on the upstream side) can permanently brick that server's connection from the user's perspective until they manually rename keys.
• Users of mcp__digitalocean-*, mcp__sentry-*, mcp__notion-*, and any other MCP server documented as a JSON-edit setup are exposed.
• The current workaround (rename keys) is invisible to most users, ugly in ~/.claude.json, and creates drift from upstream documentation.

Suggested fix:

Easiest: surface manually-edited mcpServers entries in the Connectors UI so the existing v2.1.118 Reconnect action covers them too. They already have all the metadata needed (name, URL, transport, auth headers).

Alternative: enable the /mcp slash command inside Claude Desktop's Code chat — this is what users would reach for first, and it would also fix several adjacent gaps.

Alternative: add claude mcp reconnect <name> and claude mcp reset-cache <name> to the CLI for scripted recovery, plus document the LevelDB key shape so admins can clear stuck entries safely without nuking unrelated state.

Additional context:

• macOS, Claude Desktop on Apple Silicon
• SDK versions tested: v2.1.111 (broken), v2.1.119 (broken on the original keys, working on renamed keys)
• Direct curl to the same MCP endpoint with the same bearer header succeeds — proves the auth and upstream are not at fault
• Related: anthropics/claude-code #51736, #52200 — different facets of the same MCP recovery surface gap