[DOCS] MCP HTTP 404 error messages do not document the URL and MCP-config pointer added in v2.1.191

Documentation Type

Missing documentation (feature not documented)

Documentation Location

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

Section/Topic

"Automatic reconnection" section (around line 173-177), which is the only place the MCP docs describe what users see for HTTP/SSE connection errors that are not retried.

Current Documentation

The "Automatic reconnection" section in https://code.claude.com/docs/en/mcp currently says:

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 same backoff applies when an HTTP or SSE server fails its initial connection at startup. As of v2.1.121, Claude Code retries the initial connection up to three times on transient errors such as a 5xx response, a connection refused, or a timeout, then marks the server as failed if it still cannot connect. Authentication and not-found errors are not retried because they require a configuration change to resolve.

The MCP page does not describe the user-facing error message format at all. https://code.claude.com/docs/en/errors does not list MCP-specific connection errors either: the only MCP-related cross-reference is in the "Connection problems" recovery list, which simply points back to the MCP page without describing the 404 error format.

What's Wrong or Missing?

The changelog for v2.1.191 says:

Improved MCP error messages: HTTP 404 errors now show the URL and point to your MCP config

That is a user-visible runtime behavior change for HTTP/SSE MCP servers. After v2.1.191, when a remote MCP server returns 404 Not Found, Claude Code surfaces the failing URL in the error message and explicitly tells the user to check their MCP configuration (i.e. the .mcp.json project config or the mcpServers block in ~/.claude.json).

The current mcp.md "Automatic reconnection" section tells the user that authentication and not-found errors are not retried, but it never says:

1. what text the user actually sees when a 404 surfaces, or
2. that the error message now includes the failing URL, or
3. that the error message now points the user at their MCP config.

That leaves a documentation gap for the most common misconfiguration: a server name, transport type, or url field pointing at an endpoint that does not exist. Users currently see "not-found" wording and have to guess that the resolution path is to inspect .mcp.json.

Suggested Improvement

Update the "Automatic reconnection" section in https://code.claude.com/docs/en/mcp to document the v2.1.191 error message change.

Suggested addition immediately after the existing "Authentication and not-found errors are not retried..." sentence:

HTTP 404 error format (v2.1.191+) When a remote HTTP or SSE MCP server returns 404 Not Found, Claude Code does not retry the connection. The error message now includes the failing URL and points you at your MCP configuration. For example, a misconfigured url in .mcp.json produces a message along the lines of: > MCP server github returned HTTP 404 for https://api.example.com/mcp. Check the url field for this server in your MCP config (.mcp.json or ~/.claude.json). The same format applies during startup retries and during /mcp reconnect failures. Stdio servers do not surface HTTP errors and are not affected.

It would also help to cross-reference this from the troubleshooting guidance that already links to the MCP page from https://code.claude.com/docs/en/errors and https://code.claude.com/docs/en/troubleshooting, so users searching for "HTTP 404" or "MCP server returned" land on the relevant section.

Impact

Medium - Makes feature difficult to understand

Additional Context

Affected Pages:

| Page | Context |
|------|---------|
| https://code.claude.com/docs/en/mcp | Primary MCP docs page; "Automatic reconnection" section is the only place that mentions not-found errors but does not describe the new error message format or MCP-config pointer |
| https://code.claude.com/docs/en/errors | Generic error reference; only cross-references the MCP page without describing the HTTP 404 error format |
| https://code.claude.com/docs/en/troubleshooting | High-level troubleshooting index; routes "MCP server failed to connect" to the MCP page, which still does not document the new format |

Total scope: 3 pages affected

Source: Changelog v2.1.191

Exact changelog entry:

Improved MCP error messages: HTTP 404 errors now show the URL and point to your MCP config

Note: An existing open docs issue covers the related but distinct v2.1.139 behavior where the /mcp reconnect panel displays the HTTP status and URL on reconnect failure. The v2.1.191 change is broader: it covers general MCP error messages, specifically for HTTP 404 responses, and additionally tells the user where to look in the MCP config.