claude-code - 💡(How to fix) Fix [DOCS] MCP docs omit Esc interrupt behavior for stdio tool calls [1 participants]

Documentation Type

Missing documentation (feature not documented)

Documentation Location

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

Section/Topic

Option 3: Add a local stdio server, Automatic reconnection, and interrupt behavior for in-flight stdio MCP tool calls

Current Documentation

The MCP docs explain local stdio servers and their reconnection behavior:

Stdio servers run as local processes on your machine. They're ideal for tools that need direct system access or custom scripts.

The same page later 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 beginner terminal guide tells users:

Press Esc to interrupt Claude if it's running.

The costs page gives similar interruption guidance:

If Claude starts heading the wrong direction, press Escape to stop immediately.

No current MCP documentation explains what should happen when a user presses Esc while Claude Code is waiting on a stdio MCP tool call.

What's Wrong or Missing?

Changelog v2.1.120 includes this fix:

Fixed pressing Esc during a stdio MCP tool call closing the entire server connection (regression in 2.1.105)

That release note confirms a user-visible behavior that is not documented: interrupting an in-flight stdio MCP tool call should not close the entire stdio MCP server connection.

The omission matters because the docs already say stdio servers are not automatically reconnected. Users and MCP server authors can currently infer that any interrupted stdio call might leave the server disconnected, or may not know whether Esc cancels only the active operation or tears down the local MCP process.

The docs should distinguish:

1. user-initiated interruption of an in-flight stdio MCP tool call,
2. an actual stdio server disconnect or process exit, and
3. the fact that stdio servers are not automatically reconnected after a real disconnect.

Suggested Improvement

Add a short note near Automatic reconnection or under the local stdio server setup section.

Suggested wording:

When you interrupt Claude Code while it is waiting on a stdio MCP tool call, Claude Code cancels or stops waiting on the active tool call without intentionally closing the entire MCP server connection. If the stdio server process itself exits or the transport disconnects, the server is not automatically reconnected; check /mcp and restart or reconnect it manually.

Also update the troubleshooting guidance for MCP servers to mention that if pressing Esc during a stdio MCP call leaves the server disconnected, users should upgrade to v2.1.120 or later because earlier versions had a regression that could close the server connection.

Impact

Medium - Makes feature difficult to understand

Additional Context

Affected Pages:

Total scope: 4 pages affected

Source: Changelog v2.1.120

Exact changelog entry: Fixed pressing Esc during a stdio MCP tool call closing the entire server connection (regression in 2.1.105)