Claude CodeのMCPツール呼び出しがタイムアウト｜延長設定の手順

MCPサーバー経由のツールを呼ぶと、処理が終わる前に「timeout」で切れて返ってこない——そんなときに、どの設定をどこに書けば延びるのかをまとめます。対象は、Claude Code（CLI/デスクトップ）でMCPツールを使っていて、時間のかかる処理が途中で打ち切られて困っている人です。設定値は執筆時点（2026-09）の公式ドキュメントの記述にもとづきます。バージョンで変わる可能性があるので、最終的には手元の公式ドキュメントで確認してください。

タイムアウトは「起動」と「ツール実行」で別物

まず切り分けが要ります。MCPまわりのタイムアウトは、大きく分けて2種類あるからです。「MCPサーバーが起動するまで待つ時間」と、「起動済みのサーバーにツール呼び出しを投げてから結果を待つ時間」は、別の設定で制御されます。ここを混同すると、直したい方と違う値をいじって効かない、ということになります。

公式ドキュメントによると、Claude Codeは次の環境変数を参照します（執筆時点）。

「呼び出しが処理の途中で切れる」の主犯はたいてい MCP_TOOL_TIMEOUT です。一方、サーバーが立ち上がる前に諦められてしまう（接続に失敗する）なら MCP_TIMEOUT を疑います。なお、時間ではなく出力が大きすぎて途切れる場合は、後述の MAX_MCP_OUTPUT_TOKENS の話になります。

延長する手順

設定の入れ方は2つあります。用途で使い分けます。

方法1: シェルの環境変数で渡す

その場で試すならこれが速いです。値はミリ秒で、120000は120秒です。

export MCP_TIMEOUT=30000
export MCP_TOOL_TIMEOUT=120000
claude

方法2: settings.json の env に書く

毎回効かせたいなら設定ファイルに書きます。Claude Codeの設定は、ユーザー全体が ~/.claude/settings.json、プロジェクト共有が <プロジェクト>/.claude/settings.json、個人ローカルが .claude/settings.local.json の順で読まれます。プロジェクト単位で固定したいなら2番目に置きます。

{
  "env": {
    "MCP_TIMEOUT": "30000",
    "MCP_TOOL_TIMEOUT": "120000",
    "MAX_MCP_OUTPUT_TOKENS": "50000"
  }
}

env の値は文字列（ダブルクオート）で書くのが無難です。編集したら Claude Code を一度終了して起動し直してください。環境変数は起動時に読まれるので、開いたまま変えても反映されません。

つまずきやすい点

• 単位はミリ秒。 「60」と書くと0.06秒で即切れます。60秒なら 60000、3分なら 180000。ここが一番多い取り違えです。
• 切れる原因が時間とは限らない。 エラーが timeout ではなく出力の打ち切りに見えるなら、MAX_MCP_OUTPUT_TOKENS 側です。公式ドキュメントによると既定値は25000トークン（執筆時点）で、大量に返すツールではここに当たります。
• サーバー自体が固まっている場合は延長しても無駄。 Claude Code内で /mcp を実行して、そのサーバーが connected かを先に確認します。接続に失敗しているなら、延ばすのではなく起動コマンドや認証を疑います。
• どれくらいに延ばすか。 何秒で切れているかログで確認し、実際にかかる時間＋余裕を足した値にします。やみくもに巨大な値にすると、本当に固まったときの気づきが遅れます。環境によって適正値は異なります。

subprocessから claude を呼ぶときの落とし穴

私は記事生成をバッチ化するのに、Python の subprocess から claude -p を呼んで自動実行しています（APIキーではなくCLIを使う構成）。この形で気をつけているのが、環境変数の渡し方です。

subprocess はデフォルトでは呼び出し側の環境を子プロセスへ引き継ぎますが、env= を明示的に渡す実装にしていると、そこに入れ忘れた変数は子の claude に届きません。MCPのタイムアウトを延ばしたつもりが効かない、という原因になります。

import os, subprocess

env = os.environ.copy()
env["MCP_TOOL_TIMEOUT"] = "180000"  # 180秒（ミリ秒）

subprocess.run(
    ["claude", "-p", prompt],
    env=env,
    timeout=600,  # ← これは秒。Python側の別のタイムアウト
)

もう一点、subprocess.run の timeout は秒で、MCP_TOOL_TIMEOUT のミリ秒とは別レイヤーです。外側の秒数が短いと、MCP側を延ばしても外側で先にプロセスが殺されます。二重のタイムアウトがあることを意識して、外側を内側より長く取ります。

まとめ

MCPツールの呼び出しが途中で切れるなら、まず /mcp で接続を確認し、時間切れなら MCP_TOOL_TIMEOUT（ミリ秒）を settings.json の env に入れて再起動する——ここまでを一度やってみてください。値はログで実測した秒数に余裕を足して決め、出力が原因なら MAX_MCP_OUTPUT_TOKENS を見る、という順で切り分ければ、当てずっぽうに数字を大きくせずに済みます。