環境変数

CLAUDE_CODE_MCP_TOOL_IDLE_TIMEOUT

MCP ツール呼び出しのアイドルタイムアウト(ミリ秒)である。stdio、HTTP、SSE、WebSocket、claude.ai コネクターのいずれかの MCP サーバーがこの時間応答も進行通知も返さない場合、ツール呼び出しは全体の MCP_TOOL_TIMEOUT を待つ代わりにエラーで中断される。ネットワークサーバーに対する 300000(5 分)、stdio サーバーに対する 1800000(30 分)というトランスポートごとの既定値を上書きする。0 に設定するとアイドルチェックが無効になる。1000 未満の値は 1 秒に引き上げられ、値は実効的な MCP_TOOL_TIMEOUT が上限になる。.mcp.json での 1000 以上のサーバー単位のタイムアウトは、そのサーバーのアイドル時間を少なくともそのタイムアウト値まで引き上げる。IDE サーバーや SDK のインプロセスサーバーには適用されない。Claude Code v2.1.187 以降が必要である。v2.1.203 より前では、stdio サーバーはアイドルタイムアウトの対象外だった

使い方・用途

  • 応答も進捗通知も返さない MCP サーバーへのツール呼び出しが、全体のタイムアウトまで長時間セッションをブロックするのを防ぎたい。
  • ネットワーク経由の MCP サーバーがハングしたとき、デフォルトの5分 idle 待機よりも短く切り上げて素早くエラーを検知したい。
  • 応答が遅い stdio の MCP サーバー向けに、デフォルトの30分 idle 待機を短縮したい。
英語原文(公式ドキュメントより)

Idle timeout in milliseconds for MCP tool calls. When a stdio, HTTP, SSE, WebSocket, or claude.ai connector 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

関連ドキュメント

関連する変更履歴

v2.1.187(1件)

Fixed
リモートMCPツールの呼び出しが応答なしでハングする問題を修正し、タイムアウト設定を追加
英語原文を表示
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)

変更後

ネットワークの問題や外部サーバーの不調によって CLI 全体がフリーズして作業が中断されるのを防ぎます。

関連ドキュメント