MCPの長時間ツール呼び出しが自動でバックグラウンド化する仕組み
MCPツール呼び出しがメイン会話で2分を超えると、Claude Codeはバックグラウンドタスクへ自動で切り替えます。しきい値の変更方法と対象外になる4つのケースを扱います。
MCPツール呼び出しはなぜ2分でバックグラウンドに移るのか
メイン会話でのMCPツール呼び出しは、実行が2分を超えるとバックグラウンドタスクへ自動的に切り替わります。Claudeはタスクidを即座に受け取って次の作業を続け、呼び出しが完了した時点で結果がタスク通知として届きます。この仕組みはClaude Code v2.1.212以降が対象です。
自動バックグラウンド化が入る前、長時間のMCPツール呼び出しはセッション全体を止めていました。データベースの大規模集計や、外部APIの重いバッチ処理を呼ぶMCPサーバーでは、応答が返るまでClaudeは他の作業に一切着手できませんでした。自動バックグラウンド化は、この待ち時間をClaudeの手が空く時間に変える仕組みです。
トリガーになるのは経過時間だけ
しきい値の判定基準は経過時間のみです。呼び出す内容やMCPサーバーの種類は関係ありません。2分を超えて実行中のツール呼び出しは、その瞬間からバックグラウンドタスクとして扱われます。
バックグラウンドに移ったあとも、呼び出しそのものを縛る制限は変わりません。サーバー単位のtimeout設定またはMCP_TOOL_TIMEOUT環境変数が定める壁時計の上限と、CLAUDE_CODE_MCP_TOOL_IDLE_TIMEOUTが定めるアイドルタイムアウトは、バックグラウンドで実行中でもそのまま効き続けます。自動バックグラウンド化が変えるのは「どこで待たされるか」だけで、「いつまで待つか」の制限は別レイヤーにあります。
進行中のタスクは/tasksに表示され、そこから停止もできます。セッションを終了するとタスクは残りません。
バックグラウンド化されない4つのケース
すべてのMCPツール呼び出しが対象になるわけではありません。対象外になる条件は次の4つです。
| 呼び出しの種類 | バックグラウンド化 | 理由 |
|---|---|---|
| メイン会話からの呼び出し | バックグラウンド化される | 理由通常の対象 |
| サブエージェントからの呼び出し | バックグラウンド化されない | 理由すでに独立したスレッドで動いている |
| IDEサーバーへの呼び出し | バックグラウンド化されない | 理由対象外に固定 |
非対話モード(claude -p) | バックグラウンド化されない(既定) | 理由CLAUDE_AUTO_BACKGROUND_TASKS=1のときだけ対象になる |
| elicitationダイアログが開いている呼び出し | バックグラウンド化されない(ダイアログが閉じるまで保留) | 理由サーバーが遅いのではなく、あなたの入力待ちのため |
非対話モードが既定で対象外なのには理由があります。一回限りの実行は、バックグラウンドタスクの結果が届く前にプロセスごと終了してしまう可能性があるからです。CIやスクリプトからclaude -pを使い、かつ長時間のMCP呼び出しでプロセスを止めたくない場合はCLAUDE_AUTO_BACKGROUND_TASKS=1を明示的に立てます。
elicitation(MCPサーバーがツール呼び出しの途中でユーザーに追加入力を求める仕組み)のダイアログが開いているあいだも、バックグラウンド化は保留されます。これはサーバーの処理が遅いのではなく、あなたの入力を待っているだけだからです。elicitationには2つの形があります。フォームモードはユーザー名とパスワードのような入力欄をその場に表示し、URLモードは認証や承認のためのブラウザURLを開いてCLI側で完了を確認します。どちらの形でも、あなたが応答するまでサーバー側の処理は進まないため、自動バックグラウンド化の対象にはなりません。
しきい値と関連タイムアウトを変える
自動バックグラウンド化のしきい値はミリ秒単位で変更できます。
# しきい値を5分(300000ミリ秒)に変更
export CLAUDE_CODE_MCP_AUTO_BACKGROUND_MS=300000
# 自動バックグラウンド化そのものを止める
export CLAUDE_CODE_MCP_AUTO_BACKGROUND_MS=0CLAUDE_CODE_DISABLE_BACKGROUND_TASKS=1を設定すると、自動バックグラウンド化だけでなく他のバックグラウンドタスク機能もまとめて無効になります。個々のMCPサーバー呼び出しの壁時計上限を調整したいときは.mcp.jsonの該当サーバー設定にtimeout(ミリ秒)を足すか、MCP_TOOL_TIMEOUT環境変数を使います。たとえば重い集計クエリを投げるサーバーなら、そのサーバーのエントリに"timeout": 600000と書けば上限を10分に伸ばせます。アイドル判定だけを変えたいならCLAUDE_CODE_MCP_TOOL_IDLE_TIMEOUTです。
3層のタイムアウトそれぞれの既定値
3層のタイムアウトは、既定値も変更方法もそれぞれ独立しています。
| 層 | 既定値 | 変更する環境変数 |
|---|---|---|
| 自動バックグラウンド化のしきい値 | 既定値2分 | 変更する環境変数CLAUDE_CODE_MCP_AUTO_BACKGROUND_MS |
壁時計の上限(サーバー単位のtimeoutが未設定のとき) | 既定値約28時間 | 変更する環境変数.mcp.jsonのtimeout(サーバー単位)/ MCP_TOOL_TIMEOUT |
| アイドルタイムアウト | 既定値HTTP・SSE・WebSocket・claude.aiコネクタは5分、stdioは30分 | 変更する環境変数CLAUDE_CODE_MCP_TOOL_IDLE_TIMEOUT |
アイドルタイムアウトは、サーバーが応答も進捗通知も一切返さない時間が続いたときに働きます。壁時計の上限まで待たず、無応答のまま経過した時間だけで打ち切る点が壁時計上限との違いです。サーバー単位のtimeoutを1000ミリ秒以上に設定すると、その値がアイドルタイムアウトの下限としても働き、Claude Codeはその時間より早くアイドル判定で打ち切ることはありません。アイドルタイムアウトの対象はIDEサーバーとSDKのインプロセスサーバーを除く全サーバー種別です。
MCP_TIMEOUTとMCP_TOOL_TIMEOUTは何が違うか
MCP関連のタイムアウト環境変数は名前が似ていて混同しやすいので、それぞれが何を制御するかを分けて覚えておくと設定ミスを防げます。
| 環境変数 | 制御対象 |
|---|---|
MCP_TIMEOUT | 制御対象MCPサーバーの起動タイムアウト(接続確立までの待ち時間) |
MCP_TOOL_TIMEOUT | 制御対象ツール呼び出し1回あたりの壁時計上限(既定は約28時間) |
CLAUDE_CODE_MCP_TOOL_IDLE_TIMEOUT | 制御対象応答も進捗通知も無い状態が続いたときのアイドル判定 |
CLAUDE_CODE_MCP_AUTO_BACKGROUND_MS | 制御対象メイン会話の呼び出しをバックグラウンドへ切り替えるしきい値(既定2分) |
MCP_TIMEOUTはサーバーへの接続そのものが確立するまでの時間で、本記事が扱う「ツール呼び出し1回の実行時間」とは別の話です。自動バックグラウンド化と関係するのは残りの3つで、サーバーが繋がったあとにツールを呼び出してからの時間を扱います。名前だけで判断せず、この対応表を手元に置いておくと設定ミスを防げます。
HTTP・SSE・claude.aiコネクタサーバーには、壁時計上限とは別に「最初の応答バイトが返るまで」を測るper-requestタイマーもあります。この値は60秒・そのサーバーに適用されるツールタイムアウト・MCP_TIMEOUTのうち最も長いものに設定され、MCP_TOOL_TIMEOUTの既定値である約28時間はこの比較には入りません。stdioサーバーとWebSocketサーバーにはこのper-requestタイマーはありません。呼び出しがすぐに応答し始めているのに全体としては長引いている場合、このタイマーには引っかからずに自動バックグラウンド化のしきい値まで進みます。
「バックグラウンド」という言葉のもう1つの意味
MCPまわりのドキュメントでは「バックグラウンド」という言葉が別の意味でも使われるので注意します。alwaysLoad: trueを設定していないサーバーは、既定でセッション起動時に接続処理そのものをバックグラウンドで行い、起動を止めません。これは「ツール呼び出しの実行がバックグラウンドに移る」という本記事のテーマとは別の話で、MCP_CONNECTION_NONBLOCKING=0を設定すると起動がサーバーの接続完了を待つようになります。「バックグラウンド」が接続確立を指しているのか、ツール呼び出しの実行を指しているのかは、文脈で見分ける必要があります。
接続待ちのMCPサーバーとは別の仕組み
まだ接続処理中のMCPサーバーが持つツールを呼ぼうとしたときにClaudeが待つ動きは、自動バックグラウンド化とは別の仕組みです。MCP tool searchが有効な既定構成では、この待ちはToolSearch呼び出しの内部で発生します。tool searchを使わない構成(カスタムのANTHROPIC_BASE_URL使用時など)ではWaitForMcpServersツールが代わりに使われます。どちらも「サーバーがまだ繋がっていない」ことに対する待ちであり、「繋がったサーバーのツール呼び出しが長時間かかっている」ことに対応する自動バックグラウンド化とは対象が異なります。
なぜサブエージェントの呼び出しは対象外なのか
サブエージェントからのMCPツール呼び出しが対象外になっているのは、単なる制限ではなく設計上自然な帰結です。サブエージェントはもともとメインの会話スレッドとは別に動いており、その呼び出しが長引いてもメインの会話をブロックしません。自動バックグラウンド化が解決したいのは「メインの会話が1つの重い呼び出しに引きずられる」問題なので、すでに独立して動いているサブエージェントの呼び出しには適用する意味がないと言えます。
この整理を踏まえると、この機能が実質的に変えたのは「長時間のMCP呼び出しを避けるためだけにサブエージェントへ処理を切り出す」という回避策の必要性です。以前は、メインの会話をブロックしたくなければ重い呼び出しをサブエージェントに移すしかありませんでした。今は単発の呼び出しでも、2分を超えれば自動的に同じ効果が得られます。
Ctrl+Bのバックグラウンド実行と何が違うか
Ctrl+Bでコマンドをバックグラウンドに回す機能は、あなたが明示的に指示してBashコマンドを裏へ回す操作です。対して自動バックグラウンド化は、MCPツール呼び出しに限って、しきい値を超えた時点でClaude Codeが自動的に切り替えます。前者は操作、後者は制御という違いがあります。
この違いは実務にも表れます。Bashコマンドは自分でCtrl+Bを押し忘れれば止まったままです。MCPツール呼び出しは何もしなくても2分で解放されるので、MCP設定ガイドで扱っている重い処理系のMCPサーバー(大規模データベースの集計や外部APIのバッチ処理など)を使うほど、この自動化の恩恵は大きくなります。Lighthouse監査に時間がかかるChrome DevTools MCPもその一例です。
まとめ
MCPツール呼び出しの自動バックグラウンド化は、メイン会話からの呼び出しが2分を超えたときに働く仕組みで、Claude Code v2.1.212以降が対象です。サブエージェント・IDEサーバー・非対話モード(既定)・elicitation待ちの呼び出しは対象外になります。しきい値はCLAUDE_CODE_MCP_AUTO_BACKGROUND_MSで変更でき、0にすれば無効化できます。壁時計の上限とアイドルタイムアウトは独立した別設定として、バックグラウンドに移った後も効き続けます。進行中のタスクは/tasksで確認・停止できるので、重いMCPサーバーを日常的に使っているなら一度設定を見直しておくと運用が安定します。