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

MCP_TIMEOUT はMCPサーバーの起動を待つ時間、MCP_TOOL_TIMEOUT はMCPサーバーのツール呼び出しを待つ時間を決める、別の段階に効く環境変数です。名前が似ているため取り違えやすく、サーバーが起動しない不具合に対して MCP_TOOL_TIMEOUT を伸ばしても効果はありません。両者の役割・既定値・関連する2つの変数との違いを切り分けます。

接続フェーズと実行フェーズ、どちらを止めているか

MCP_TIMEOUT はセッション起動時にMCPサーバーへ接続する処理を、MCP_TOOL_TIMEOUT は接続済みのサーバーが個々のツール呼び出しに応答する処理を、それぞれ制限します。Claude Codeが1つのMCPサーバーとやり取りする流れは「起動して接続する」→「ツールを呼び出して結果を受け取る」の2段階に分かれ、この2つの環境変数はそれぞれ別の段階を担当します。

既定値の桁が大きく違う理由は単純です。起動は速く終わって当然の処理なので短く区切り、ツール実行はデータ取得やビルドなど時間のかかる処理を許容する必要があるため、実質的に無制限に近い長さが既定になっています。

MCP_TIMEOUTはサーバー起動の待ち時間を決める

MCP_TIMEOUT は、Claude CodeがMCPサーバーの起動を待つ上限をミリ秒で指定します。既定は30,000(30秒)です。値を変えるときはセッション起動前に環境変数として渡します。

MCP_TIMEOUT=10000 claude

この例では起動待ちを10秒に短縮します。逆に、起動が重いサーバーで待ち時間を延ばしたいときは値を大きくします。

MCP_TIMEOUT が絡む具体的な失敗パターンもあります。--permission-prompt-tool に渡したツールが、最初の権限確認が必要になった時点でまだ接続済みのMCPツールに含まれていないと、Claude Codeはエラーで終了します。この判定の前に、Claude Codeはサーバーの接続を MCP_TIMEOUT が決める上限(既定30秒)まで待ちます。サーバーの起動に30秒以上かかる場合は、この変数を大きくするのが対処です。v2.1.206より前はこの待ち合わせ自体が入っておらず、起動の遅い健全なサーバーでも同じエラーになっていました。

MCP_TOOL_TIMEOUTはツール呼び出しの実行時間を決める

MCP_TOOL_TIMEOUT は、接続済みのMCPサーバーに対するツール呼び出しがどれだけ長く走れるかをミリ秒で指定します。既定は100,000,000(約28時間)で、実質的にはほぼ制限なしに近い値です。

ただしHTTP・SSE・claude.aiコネクター経由のサーバーには、これとは別にリクエストごとの60秒タイマーが既定でかかります。MCP_TOOL_TIMEOUT(またはサーバーごとの timeout 設定)を60,000以上にすると、このリクエストごとの上限も引き上がります。60,000未満の値を指定しても、全体の実行時間は短くなりますがリクエストごとの上限は60秒のままです。stdioとWebSocket経由のサーバーには、このリクエストごとのタイマーは存在しません。

サーバーごとに個別の値を設定したい場合は、.mcp.json のサーバー定義に timeout フィールド(ミリ秒)を追加します。この値はそのサーバーに限り MCP_TOOL_TIMEOUT の環境変数を上書きします。

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

この例では、slow-build-server だけツール実行の上限を10分(600,000ミリ秒)にします。他のサーバーは環境変数側の既定・設定値がそのまま適用されます。なお環境変数側は1,000未満の値を1秒に切り上げますが、.mcp.json の timeout フィールドは1,000未満の値をそのまま無視します。

関連する2つの変数と混同しやすいポイント

MCP_TIMEOUT と MCP_TOOL_TIMEOUT に加えて、名前や役割が近い環境変数が2つあります。この4つをまとめて把握しておくと取り違えを防げます。

MCP_CONNECT_TIMEOUT_MS は MCP_TIMEOUT と混同しやすい変数です。適用条件は MCP_CONNECTION_NONBLOCKING=0 の場合、または alwaysLoad: true を指定したサーバーがある場合の2つです。この変数は複数サーバーの接続バッチ全体をどれだけ待ってからツール一覧を確定するかを決めます。既定を過ぎても接続中のサーバーはバックグラウンドで待機を続けます。一方 MCP_TIMEOUT は個々のサーバー1台の接続試行そのものを区切る変数で、両者は別物です。

CLAUDE_CODE_MCP_TOOL_IDLE_TIMEOUT は MCP_TOOL_TIMEOUT の兄弟にあたる変数です。MCP_TOOL_TIMEOUT がツール呼び出し全体の壁時計上限であるのに対し、こちらは「応答も進捗通知も一定時間ないまま止まっている」状態だけを検知して打ち切ります。既定はHTTP・SSE・WebSocket・claude.aiコネクター経由のサーバーが5分、stdioサーバーが30分です。0 を指定するとこのアイドル検知自体を無効にできます。サーバーごとの .mcp.json の timeout を1,000以上に設定すると、そのサーバーのアイドル待機の下限としても働きます。この場合、CLAUDE_CODE_MCP_TOOL_IDLE_TIMEOUT がそれより早く打ち切ることはありません(v2.1.203以降)。IDEサーバーとSDKのインプロセスサーバーには、このアイドル検知は適用されません。

これらのタイムアウトは、いずれも「呼び出しが走れる上限」を決めるだけで、セッションを常にその間ブロックするとは限りません。メイン会話からの呼び出しが2分を超えて走ると、Claude Codeはバックグラウンドタスクへ切り替えて処理を続けます。

既定はノンブロッキング起動 — MCP_TIMEOUTが効く場面は限られる

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

MCP_TIMEOUT の上限が実際に効いてくるのは、次のようなケースです。

• 環境変数 MCP_CONNECTION_NONBLOCKING を 0 に設定し、最初の問い合わせの前にサーバーの接続完了を待つようにした場合
• .mcp.json のサーバー定義で alwaysLoad: true を指定し、そのサーバーのツールを最初のプロンプト構築時点で必須にした場合(このとき接続バッチ全体の待ち時間は MCP_CONNECT_TIMEOUT_MS、既定5秒が上限になります)
• -p を使った非対話モードで、最初のターンの前にまだ接続中のサーバーを待つ場合(--mcp-config を明示的に渡すとさらに長い期限になります)
• --permission-prompt-tool で指定したツールが、最初の権限確認が必要になった時点でまだ接続済みかどうかを判定する場合(前述)

対話セッションを既定のまま使っている場合、起動が遅いサーバーがあっても他のツールから使い始められ、遅いサーバーのツールは接続でき次第追加されます。MCP_TIMEOUT を意識する必要が出てくるのは、上記のように「起動完了を待つ」設定・状況に切り替えたときです。

接続失敗時の自動再試行はMCP_TIMEOUTの外側で動く

MCP_TIMEOUT は1回の接続試行を区切る時間ですが、接続そのものが失敗したときの再試行はこの変数の外側で自動的に働きます。HTTP・SSEサーバーが起動時の初回接続に失敗した場合を考えます。5xxレスポンス・接続拒否・タイムアウトのような一時的なエラーに限り、Claude Codeは最大3回まで自動で再試行します。それでも接続できなければサーバーを失敗と判定します。認証エラーやnot foundエラーは設定変更が必要なため、この自動再試行の対象になりません。

セッション開始後にHTTP・SSEサーバーの接続が途中で切れた場合も、指数バックオフでの自動再接続が働きます。最大5回まで、1秒の遅延から始めて毎回倍にしながら再試行し、再接続中は /mcp にサーバーが保留中として表示されます。5回失敗すると失敗と判定され、/mcp から手動で再試行できます。stdioサーバーはローカルプロセスのため、この自動再接続の対象外です。

つまり「起動が遅い」と「起動に失敗して再試行している」は別の現象です。前者への対処は MCP_TIMEOUT を大きくすることですが、後者は一時的なエラーへの自動再試行がすでに走っているため、MCP_TIMEOUT を大きくしても再試行の回数や間隔そのものは変わりません。

設定例 — 用途別の組み合わせ

起動が遅いサーバーが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_TIMEOUT です。起動(接続確立)にかかる時間が既定30秒を超えている可能性があるので、値を大きくして再接続を試します。MCP_TOOL_TIMEOUT は起動後のツール呼び出しにしか効かないため、起動段階の問題には影響しません。

ツール呼び出しが途中で打ち切られます

まず対象サーバーがHTTP・SSE・claude.aiコネクターかどうかを確認します。これらの種別はリクエストごとに既定60秒のタイマーがかかるため、MCP_TOOL_TIMEOUT を60,000以上に設定するか、.mcp.json のサーバー単位 timeout を上げます。stdio・WebSocketサーバーで打ち切られる場合は、CLAUDE_CODE_MCP_TOOL_IDLE_TIMEOUT によるアイドル検知が働いている可能性もあるため、あわせて確認します。

値を0にするとどうなりますか

MCP_TOOL_TIMEOUT を0にする挙動は公式ドキュメントに記載がありません。アイドル検知専用の CLAUDE_CODE_MCP_TOOL_IDLE_TIMEOUT は0を指定するとアイドル検知自体を無効化できます。

.mcp.jsonのtimeoutと環境変数、どちらが優先されますか

サーバーごとの .mcp.json の timeout フィールドが優先されます。設定したサーバーに限り、MCP_TOOL_TIMEOUT 環境変数の値を上書きします。他のサーバーには環境変数側の値がそのまま適用されます。

まとめ

MCP_TIMEOUT は起動接続の待ち時間(既定30秒)、MCP_TOOL_TIMEOUT はツール実行の待ち時間(既定約28時間)を決める、別フェーズの環境変数です。起動しないトラブルには MCP_TIMEOUT を、長時間のツール呼び出しが打ち切られるトラブルには MCP_TOOL_TIMEOUT またはサーバーごとの .mcp.json の timeout を疑います。関連する MCP_CONNECT_TIMEOUT_MS と CLAUDE_CODE_MCP_TOOL_IDLE_TIMEOUT もあわせて押さえておくと、MCPサーバーが絡む待ち時間のトラブルシューティングが一段と早くなります。接続できないときの切り分け手順全体はMCPサーバーに接続できないときの切り分け手順にまとめています。.mcp.json の設定範囲やスコープの基礎はClaude Code MCP設定ガイド、他の環境変数の一覧はClaude Code環境変数リファレンスを参照してください。