[DOCS] MCP docs omit remote tool idle timeout and `CLAUDE_CODE_MCP_TOOL_IDLE_TIMEOUT`

Documentation Type

Missing documentation (feature not documented)

Documentation Location

https://code.claude.com/docs/en/mcp
https://code.claude.com/docs/en/env-vars
https://code.claude.com/docs/en/troubleshooting

Section/Topic

MCP tool timeout behavior for remote MCP tool calls, especially how the new remote idle timeout differs from MCP_TOOL_TIMEOUT and per-server .mcp.json timeout.

Current Documentation

The MCP docs currently document startup and hard tool execution timeouts:

Configure MCP server startup timeout using the MCP_TIMEOUT environment variable... Set a per-server tool execution timeout by adding a timeout field in milliseconds to that server's .mcp.json entry... This overrides the MCP_TOOL_TIMEOUT environment variable for that server only

Local evidence: docs/code.claude.com/docs/en/mcp.md:191-192

The env var page documents MCP_TIMEOUT and MCP_TOOL_TIMEOUT, but not the new idle-timeout override:

MCP_TOOL_TIMEOUT Timeout in milliseconds for MCP tool execution (default: 100000000, about 28 hours). A per-server timeout field in .mcp.json overrides this for that server.

Local evidence: docs/code.claude.com/docs/en/env-vars.md:337-338

Exact searches found no local docs mention of CLAUDE_CODE_MCP_TOOL_IDLE_TIMEOUT, remote MCP tool calls, or no response for 5 minutes.

What's Wrong or Missing?

Claude Code v2.1.187 added behavior for remote MCP tool calls that hang with no response for 5 minutes: they now abort with an error instead of blocking indefinitely, with an override via CLAUDE_CODE_MCP_TOOL_IDLE_TIMEOUT.

The docs currently explain startup timeout, hard wall-clock tool timeout, generic command hangs, and Agent SDK connection timeouts. They do not explain the new remote MCP idle timeout, what error users should expect, whether it applies only to remote MCP transports, how it differs from MCP_TOOL_TIMEOUT, or how to configure CLAUDE_CODE_MCP_TOOL_IDLE_TIMEOUT.

Suggested Improvement

Add a subsection near the existing MCP timeout text explaining that remote MCP tool calls abort if the server sends no response for 5 minutes, and that this idle timeout is separate from the hard wall-clock MCP_TOOL_TIMEOUT / per-server timeout limit.

Also add CLAUDE_CODE_MCP_TOOL_IDLE_TIMEOUT to https://code.claude.com/docs/en/env-vars with the exact default, units, accepted values, and whether any value disables the timeout.

Impact

Medium - Makes feature difficult to understand

Additional Context

v2.1.187 release note: Fixed remote MCP tool calls that hang with no response for 5 minutes — they now abort with an error instead of blocking indefinitely (override with CLAUDE_CODE_MCP_TOOL_IDLE_TIMEOUT).

Duplicate check found no exact duplicate. Related but non-duplicate open issues include #66393 for API_FORCE_IDLE_TIMEOUT on Vertex/Foundry stream idle timeout, #70133 for claude mcp login/logout, and #69620 for unauthenticated MCP server behavior.