[DOCS] [MCP] `/mcp` reconnect picks up `.mcp.json` edits without restart and shows HTTP status/URL on failure

Documentation Type

Incorrect/outdated documentation

Documentation Location

https://code.claude.com/docs/en/mcp

Section/Topic

"Automatic reconnection" section (lines 338-342)

Current Documentation

The docs currently describe automatic reconnection behavior:

If an HTTP or SSE server disconnects mid-session, Claude Code automatically reconnects with exponential backoff: up to five attempts, starting at a one-second delay and doubling each time. The server appears as pending in /mcp while reconnection is in progress. After five failed attempts the server is marked as failed and you can retry manually from /mcp. Stdio servers are local processes and are not reconnected automatically.

The documentation does not mention:

1. .mcp.json edit detection: When you edit a server's .mcp.json entry and then run /mcp reconnect, Claude Code picks up the changes without requiring a restart of Claude Code.
2. Failure status display: When reconnecting fails, the /mcp panel now shows the HTTP status code and URL that failed, making it easier to diagnose connection issues.

What's Wrong or Missing?

A. Missing: .mcp.json edit detection on reconnect

The automatic reconnection section does not document that reconnecting to a server after editing its .mcp.json configuration picks up those changes without restarting Claude Code. Users may not realize they can edit MCP server configs and simply reconnect rather than restarting the entire application.

B. Missing: HTTP status and URL on reconnect failure

The documentation does not describe the new behavior where reconnect failures display the HTTP status code and URL in the /mcp panel. This is useful diagnostic information for debugging connection issues — for example, distinguishing a 401 Authentication error from a 404 Not Found or a connection refused error.

Suggested Improvement

Update the "Automatic reconnection" section to include:

Add after the existing reconnection paragraph:

Reconnecting after configuration changes After editing a server's configuration in .mcp.json, you can run /mcp reconnect <name> to apply the changes without restarting Claude Code. The reconnection reads the updated configuration directly from the file. Diagnosing connection failures When a reconnect attempt fails, the /mcp panel displays the HTTP status code and URL that failed (for example, 401 or https://api.example.com/mcp). This helps you quickly identify whether the failure is due to authentication issues, a server not found, network problems, or other HTTP-level errors.

Impact

Medium - Makes feature difficult to understand

Additional Context

Changelog reference (v2.1.139): /mcp Reconnect now picks up .mcp.json edits without a restart, and shows the HTTP status and URL when reconnecting fails

Affected Pages:

| Page | Context |
|------|---------|
| https://code.claude.com/docs/en/mcp | Primary documentation — "Automatic reconnection" section (lines 338-342) |
| https://code.claude.com/docs/en/changelog | Changelog entry for v2.1.139 (confirms the new behavior) |

Total scope: 1 page needs documentation update