Claude Media
MCP_TIMEOUTとMCP_TOOL_TIMEOUTの違い — Claude CodeのMCP接続設定
Claude CodeTips

MCP_TIMEOUTとMCP_TOOL_TIMEOUTの違い — Claude CodeのMCP接続設定

MCP_TIMEOUTはMCPサーバーの起動待ち、MCP_TOOL_TIMEOUTはツール実行の待ち時間を決める環境変数です。既定値・関連変数・設定例をまとめます。

読了目安 約10分

MCP_TIMEOUT はMCPサーバーの起動を待つ時間、MCP_TOOL_TIMEOUT はMCPサーバーのツール呼び出しを待つ時間を決める、別の段階に効く環境変数です。名前が似ているため取り違えやすく、サーバーが起動しない不具合に対して MCP_TOOL_TIMEOUT を伸ばしても効果はありません。症状から触る変数を決める手順と、公式の説明だけでは見落としやすい挙動をまとめます。

症状から触る変数を決める

「何が」「いつ」止まっているかで、見る変数が決まります。Claude CodeがMCPサーバーとやり取りする流れは「起動して接続する」と「ツールを呼び出して結果を受け取る」の2段階です。この2つの変数は、それぞれ別の段階を区切ります。

手順

タイムアウトの切り分け順

  1. 1

    サーバーが接続済みになるか見る

    /mcp でサーバーの状態を確認します。接続されないまま失敗するなら起動段階の問題です。MCP_TIMEOUT(既定30秒)を大きくして再起動します。

  2. 2

    接続はできるが呼び出しが切れる

    接続済みのサーバーでツール呼び出しが途中で打ち切られるなら実行段階の問題です。MCP_TOOL_TIMEOUT、または .mcp.json のサーバー単位の timeout を見ます。

  3. 3

    HTTP・SSE・コネクターで60秒前後で切れる

    リクエストごとのタイマーが効いている可能性があります。値の決まり方は次節で扱います。

  4. 4

    応答が無いまま5分または30分で切れる

    アイドル検知です。CLAUDE_CODE_MCP_TOOL_IDLE_TIMEOUT の領分です。

起動と実行で、既定値の桁が違う

くらべる

MCP_TIMEOUT と MCP_TOOL_TIMEOUT

起動の待ち

MCP_TIMEOUT

MCPサーバーの起動を待つ上限です。既定は30,000ミリ秒(30秒)。MCP_TIMEOUT=10000 claude のようにセッション起動前に渡します。

実行の待ち

MCP_TOOL_TIMEOUT

MCPツールの実行時間の上限です。既定は100,000,000ミリ秒(約28時間)で、実質的にほぼ制限なしです。

起動待ちを10秒に縮める例は次のとおりです。逆に起動が重いサーバーでは値を大きくします。

MCP_TIMEOUT=10000 claude

MCP_TIMEOUTが効く場面は限られる

MCPサーバーの起動は既定でノンブロッキングです。サーバーはバックグラウンドで接続を続け、ツールは接続が完了した順に使えるようになります。多くの対話セッションでは、30秒の上限が体感の待ち時間を作るわけではありません。上限が実際に待ち時間として現れるのは、起動完了を待つ設定や状況に入ったときです。

  • 環境変数 MCP_CONNECTION_NONBLOCKING を 0 にして、最初の問い合わせの前に接続完了を待つ場合
  • .mcp.json のサーバー定義で alwaysLoad: true を指定した場合(このとき接続バッチ全体の待ちは MCP_CONNECT_TIMEOUT_MS、既定5秒が上限です)
  • -p の非対話モード(--input-format stream-json を除く)で、最初のターンの前に接続中のサーバーを待つ場合
  • Agent SDKの options.mcpServers に渡したstdioサーバー、ツール一覧のキャッシュを持たないHTTP・SSEサーバー、インプロセスのSDKサーバー

--permission-prompt-tool に渡したツールのサーバーも、MCP_TIMEOUT の上限まで待ってから最初のターンに進みます。v2.1.206より前は、このサーバーの接続が終わる前に「MCP tool not found」で落ちることがありました。起動に30秒以上かかるサーバーなら、MCP_TIMEOUT を大きくするのが対処です。

--mcp-config を -p と一緒に渡す場合の待ち合わせは、v2.1.221以降です。ツール一覧のキャッシュを持つサーバーは待たずに、最初に使うときに接続します。

MCP_TOOL_TIMEOUTとリクエストごとの60秒タイマー

MCP_TOOL_TIMEOUT は、接続済みサーバーに対するツール呼び出しの壁時計上の上限です。既定の約28時間は「実質無制限」と読めますが、HTTP・SSE・claude.aiコネクター経由のサーバーには別にリクエストごとのタイマーがかかります。これは各リクエストが、サーバーの最初の応答バイトを受け取るまでの待ちを区切るものです。

公式の環境変数表は「MCP_TOOL_TIMEOUT かサーバー単位の timeout を60,000より大きくすると上限が上がる」と説明します。MCPのページにはさらに踏み込んだ記述があり、タイマーの値は次の3つのうち最大です。

数字

リクエストごとのタイマーの値

  • 下限

    60秒

    常にこの値以上

  • ツールのタイムアウト

    サーバー単位の timeout など

    そのサーバーに適用される値

  • MCP_TIMEOUT

    既定30秒

    伸ばすとこちらも効く

HTTP・SSE・claude.aiコネクターのサーバーのみ。stdioとWebSocketにはこのタイマーがありません

ここから2つの帰結が出ます。1つは、MCP_TIMEOUT を60秒より大きくすると、起動待ちだけでなくこのリクエストごとの上限も上がることです。もう1つは、MCP_TOOL_TIMEOUT が未設定のときの約28時間は比較に入らないことです。60秒未満の値を指定しても、リクエストごとの上限は60秒より短くなりません。

自作MCPサーバーの中でAnthropic SDKを呼ぶ場合、SDKの既定タイムアウトが60秒を超えることもあります。Anthropic SDKのリトライ・タイムアウト既定値の言語差も確認してください。

サーバーごとのtimeoutと下限の扱い

サーバーごとに個別の値を設定するには、.mcp.json のサーバー定義に timeout フィールド(ミリ秒)を足します。そのサーバーに限り、MCP_TOOL_TIMEOUT を上書きします。

{
  "mcpServers": {
    "slow-build-server": {
      "command": "node",
      "args": ["server.js"],
      "timeout": 600000
    }
  }
}

この例では slow-build-server だけ、ツール実行の上限が10分になります。他のサーバーには環境変数側の値が適用されます。timeout は壁時計上の上限で、サーバーが進捗通知を送っても延長されません。

1,000未満の値の扱いは、環境変数とフィールドで逆です。環境変数の MCP_TOOL_TIMEOUT は1,000未満を1秒に切り上げます。.mcp.json の timeout は1,000未満を無視し、MCP_TOOL_TIMEOUT、未設定なら約28時間の既定値にフォールバックします。claude mcp add にタイムアウトを指定するオプションは無く、v2.1.287の claude mcp add --help にも載っていません。サーバー単位の timeout は .mcp.json を直接編集して足します。

4つの変数の取り違えを防ぐ

名前や役割が近い変数が、あと2つあります。

環境変数何を制限するか既定値
MCP_TIMEOUT何を制限するか個々のサーバーの接続試行既定値30秒
MCP_CONNECT_TIMEOUT_MS何を制限するか接続バッチ全体がツール一覧を確定させるまでの待ち既定値5秒
MCP_TOOL_TIMEOUT何を制限するかツール呼び出しの壁時計上の上限既定値約28時間
CLAUDE_CODE_MCP_TOOL_IDLE_TIMEOUT何を制限するか応答も進捗通知もない状態の打ち切り既定値HTTP・SSE・WebSocket・コネクターは5分、stdioは30分

MCP_CONNECT_TIMEOUT_MS は MCP_CONNECTION_NONBLOCKING=0 の場合か、alwaysLoad: true のサーバーがある場合にだけ効きます。既定を過ぎても、接続中のサーバーはバックグラウンドで接続を続けます。MCP_TIMEOUT が個々のサーバー1台の接続試行を区切るのに対し、こちらは接続バッチ全体の待ちです。

CLAUDE_CODE_MCP_TOOL_IDLE_TIMEOUT は、ツール呼び出し全体ではなく「無音の時間」だけを見ます。0 を指定するとアイドル検知自体を無効にでき、1,000未満の値は1秒に切り上げられます。値は有効な MCP_TOOL_TIMEOUT が上限で、それ以上には伸ばせません。サーバーごとの timeout を1,000以上にすると、そのサーバーのアイドル待機の下限として働きます(v2.1.203以降)。IDEサーバーとSDKのインプロセスサーバーには適用されません。v2.1.203より前は、stdioサーバーがアイドル検知の対象外でした。

非対話セッションの最初のターンの待ちだけを調整する CLAUDE_CODE_MCP_STARTUP_WAIT_MS(v2.1.274以降)という変数もあります。0 で待ちを省略できますが、--permission-prompt-tool のサーバーは、この値と無関係に MCP_TIMEOUT の待ちを保ちます。

これらはいずれも「呼び出しが走れる上限」を決めるだけで、セッションを常にその間ブロックするわけではありません。メイン会話からの呼び出しが2分を超えて走ると、v2.1.212以降はバックグラウンドタスクに移ります。CLAUDE_CODE_MCP_AUTO_BACKGROUND_MS でこの閾値を変えられ、0 で自動移行を止められます。移行後も、壁時計上の上限とアイドル検知は引き続き効きます。

接続失敗の自動再試行は、MCP_TIMEOUTとは別に動く

「起動が遅い」と「起動に失敗して再試行している」は別の現象です。再試行は MCP_TIMEOUT の外側で動くため、値を大きくしても再試行の回数や間隔は変わりません。

起動時の初回接続に失敗したHTTP・SSEサーバーは、5xxレスポンス・接続拒否・タイムアウトのような一時的なエラーに限り、最大3回まで再試行されます。再試行されないのは次の場合です。

  • WebSocketサーバーの初回接続
  • 認証エラーやnot foundエラー(設定の変更が必要なため)。ただし Authorization ヘッダーの唯一の出どころが headersHelper なら、新しい資格情報を拾えるので再試行されます

接続後の tools/list などの探索リクエストも、一時的なネットワークエラーなら最大3回まで再試行されます。リクエストのタイムアウトは再試行の対象外です。

セッション中にリモートサーバー(HTTP・SSEなど)が切断された場合は、指数バックオフで自動再接続します。最大5回、1秒の遅延から始めて毎回倍にします。再接続中は /mcp で保留中と表示され、5回失敗すると失敗扱いです。stdioサーバーはローカルプロセスなので、この自動再接続の対象外です。失敗したサーバーをまとめて再試行する /mcp reconnect all は、対話ターミナルではv2.1.284以降で使えます。それ以前は MCP server "all" not found と出ます。接続できないときの全体の切り分けはMCPサーバーに接続できないときの切り分け手順にあります。

設定例

起動が遅いサーバーが1台だけなら、MCP_TIMEOUT だけをセッション単位で上げます。

MCP_TIMEOUT=60000 claude

特定のサーバーだけ長時間のツール呼び出しが必要なら、前述の .mcp.json のサーバー単位 timeout を使います。チーム全体で同じ値を配るなら、.claude/settings.json の env キーに書けます。

{
  "env": {
    "MCP_TIMEOUT": "60000",
    "MCP_TOOL_TIMEOUT": "1800000"
  }
}

起動待ちが60秒、ツール実行の上限が30分になります。MCP_TOOL_TIMEOUT が60秒を超えるため、HTTP・SSE・コネクターのリクエストごとのタイマーも30分に上がります。MCP_TIMEOUT=60000 だけを設定した場合は、60秒のままです。値を揃えるときは、この下限との関係も確認します。.mcp.json の設定範囲やスコープの基礎はClaude Code MCP設定ガイド、他の変数はClaude Code環境変数リファレンスにあります。

まとめ

2つの変数を別々に決めても、HTTP・SSE・コネクターでは60秒タイマーを通じて両方が同じ上限に効きます。値を変えたら、リクエストごとのタイマーがどちらで決まっているかを確かめます。

この記事を共有:XはてブLinkedIn

関連する記事

Claude Code をもっと見る →