{"name":"CLAUDE_CODE_MCP_TOOL_IDLE_TIMEOUT","slug":"claude-code-mcp-tool-idle-timeout","family":"env","title":"Environment variables","noun":"environment variable","description":"Idle timeout in milliseconds for MCP tool calls. When a stdio, HTTP, SSE, WebSocket, or [claude.ai connector](\/docs\/en\/mcp#use-mcp-servers-from-claude-ai) MCP server sends no response and no progress notification for this long, the tool call aborts with an error instead of waiting for the overall `MCP_TOOL_TIMEOUT`. Overrides the per-transport defaults of 300000 (5 minutes) for network servers and 1800000 (30 minutes) for stdio servers. Set to `0` to disable the idle check. Values below 1000 are raised to one second, and the value is capped at the effective `MCP_TOOL_TIMEOUT`. A per-server `timeout` in `.mcp.json` of at least 1000 raises that server's idle window to at least the `timeout` value. Doesn't apply to IDE servers or SDK in-process servers. Requires Claude Code v2.1.187 or later. Before v2.1.203, stdio servers were exempt from the idle timeout","description_source":"docs","described_by":{"doc":"claude-code\/env-vars","title":"Environment variables"},"presence":{"first_seen":"2.1.187","removed_in":null,"in_current_build":true,"newest_mined":"2.1.309","builds":107,"mined_builds":150,"first_cited":{"version":"2.1.187","released_at":"2026-06-23 17:55:41","spans":2}},"aliases":[],"entries":[{"version":"2.1.290","anchor":"mcp-tool-idle-timeout-watchdog-gains-an-extra-timer-cleanup","heading":"MCP tool idle timeout now clears an extra timer when a call ends","line":"When an MCP tool call finishes, Claude Code's idle-timeout check now also clears a second timer; its error text is unchanged","released_at":"2026-10-05 18:12:44","reason":"found in this entry's text, named in this entry"},{"version":"2.1.187","anchor":"mcp-tool-idle-timeout-detection","heading":"MCP tool idle timeout detection","line":null,"released_at":"2026-06-23 17:55:41","reason":"found in this entry's text"}],"entries_total":2,"docs":[{"source":"claude-code","path":"env-vars","title":"Environment variables","documented":true},{"source":"claude-code","path":"mcp","title":"Connect Claude Code to tools via MCP","documented":false}],"docs_total":2,"gates":[],"related":[{"name":"CLAUDE_CODE_MCP_ALLOWLIST_ENV","slug":"claude-code-mcp-allowlist-env","description":"Set to `1` to spawn stdio MCP servers with only a safe baseline environment plus the server's configured `env`, instead of inheriting your shell environment"},{"name":"CLAUDE_CODE_MCP_ALWAYS_LOAD_JOIN_BEFORE_INPUT","slug":"claude-code-mcp-always-load-join-before-input","description":"A new environment variable, `CLAUDE_CODE_MCP_ALWAYS_LOAD_JOIN_BEFORE_INPUT`, affects always-load MCP servers when set to exactly `true`"},{"name":"CLAUDE_CODE_MCP_APPS_HOST","slug":"claude-code-mcp-apps-host","description":"With CLAUDE_CODE_MCP_APPS_HOST set to true, Claude Code tells MCP servers it accepts MCP App content"},{"name":"CLAUDE_CODE_MCP_AUTO_BACKGROUND_MS","slug":"claude-code-mcp-auto-background-ms","description":"Elapsed time in milliseconds before a still-running MCP tool call [moves to a background task](\/docs\/en\/mcp#automatic-backgrounding-of-long-tool-calls) (default: 120000, or 2 minutes). Set to `0` to turn automatic backgrounding off. Requires Claude Code v2.1.212 or later"},{"name":"CLAUDE_CODE_MCP_CONNECTOR_PREWAIT_MS","slug":"claude-code-mcp-connector-prewait-ms","description":"New CLAUDE_CODE_MCP_CONNECTOR_PREWAIT_MS environment variable overrides how long Claude Code waits for remote MCP servers to start"},{"name":"CLAUDE_CODE_MCP_MEMORY_CGROUP","slug":"claude-code-mcp-memory-cgroup","description":"On Linux you can force MCP servers into their own memory cgroup with an environment variable."},{"name":"CLAUDE_CODE_MCP_PREWAIT_SERVERS","slug":"claude-code-mcp-prewait-servers","description":"`CLAUDE_CODE_MCP_PREWAIT_SERVERS` and `CLAUDE_CODE_MCP_PREWAIT_SERVERS_MS` name MCP servers for remote worker sessions to wait for before the first turn"},{"name":"CLAUDE_CODE_MCP_PREWAIT_SERVERS_MS","slug":"claude-code-mcp-prewait-servers-ms","description":"`CLAUDE_CODE_MCP_PREWAIT_SERVERS` and `CLAUDE_CODE_MCP_PREWAIT_SERVERS_MS` name MCP servers for remote worker sessions to wait for before the first turn"},{"name":"CLAUDE_CODE_MCP_STARTUP_WAIT_MS","slug":"claude-code-mcp-startup-wait-ms","description":"How long in milliseconds the first turn of a [non-interactive](\/docs\/en\/headless) session waits for MCP servers that are still connecting, in place of the default [first-turn wait](\/docs\/en\/agent-sdk\/mcp#connection-timing). When set, the wait covers every pending server. Set to `0` to skip the wait. A [`--permission-prompt-tool`](\/docs\/en\/cli-reference#cli-flags) server keeps its own `MCP_TIMEOUT` wait regardless of the value. Requires Claude Code v2.1.274 or later"}],"url":"https:\/\/changelogs.core-directive.com\/reference\/env\/claude-code-mcp-tool-idle-timeout","family_url":"https:\/\/changelogs.core-directive.com\/reference\/env.json"}