CLAUDE_CODE_DISABLE_MCP_TASK_BACKGROUNDでMCPタスクの結果を待つ

CLAUDE_CODE_DISABLE_MCP_TASK_BACKGROUND を 1 にすると、対話セッションのClaudeはMCPタスクの結果が出るまで待つようになります。既定ではMCPサーバーが長い処理を「タスク」として受け付けた時点でツール呼び出しが返り、Claudeは別の作業へ進みます。この変数はその既定を、完了待ちに切り替えます。

似た働きの変数に CLAUDE_CODE_MCP_AUTO_BACKGROUND_MS=0 があります。両者は「全部待つ」か「長い呼び出しだけ裏に回す」かで分かれます。この記事では、2つの違いと、待機中の Esc や時間制限の扱いをまとめます。必要なバージョンはClaude Code v2.1.304以降です。

MCPタスクは何が既定で裏に回るのか

MCPタスクとは、レポートの書き出しやビルドのような長い処理を、MCPサーバー自身が実行する仕組みです。サーバーがジョブを受け付けると、Claudeのツール呼び出しはそこで返ります。Claudeは結果を待たずに作業を続けます。

ジョブが終わると、トランスクリプトに次の形の1行が出ます。結果はClaudeに渡り、画面には出ません。

MCP task <server task id> (<server>/<tool>) completed.

Claudeが待機中なら、結果が届いた時点で自動的に続きに取りかかります。実行中はフッターに 1 MCP task のような件数が表示され、/tasks から確認や停止ができます。

つまり既定の挙動は「タスクを投げたら先へ進む」です。次の結果に依存する作業、たとえばビルド結果を見てから修正するような流れでは、Claudeが結果の出る前に先へ進んでしまいます。そのため結果を待たせたい場面が出てきます。

待たせる2つの環境変数は何が違うのか

対話セッションでClaudeに結果を待たせる変数は2つあります。どちらも settings.json の env ブロックに書けます。

MCP_AUTO_BACKGROUND_MS=0 は、MCPタスクに限らずあらゆるMCPツール呼び出しを、終了まで待ちます。自動バックグラウンドそのものを止める変数なので、待ちが長くなっても裏には回りません。

DISABLE_MCP_TASK_BACKGROUND=1 は、待ちの上限が違います。自動バックグラウンドが有効なままなら、既定の2分を過ぎた呼び出しは裏へ移ります。短いタスクはその場で終わり、長いタスクがセッションを塞ぎ続けることはありません。

2分を過ぎて裏に回った呼び出しはMCPタスクなのか

DISABLE_MCP_TASK_BACKGROUND=1 で2分を超えて移った呼び出しは、MCPタスクではなく通常のバックグラウンド呼び出しです。ここが見落としやすい点です。

通常のバックグラウンド呼び出しは、セッションを抜けると残りません。MCPタスクなら、リモートサーバー上の処理は終了後も続き、同じセッションを再開すれば追跡を再開できます。待機に切り替えた結果、この「セッションを越えて追える」性質を手放すことになります。

長時間のジョブを、終了後も走らせたまま別の日に結果を取りたい場合には、この変数は向きません。逆に、結果を見てから次の手を決める流れが主なら、待機のほうが扱いやすくなります。

待機中にEscを押すとどうなるか

待っている間に Esc を押すと、呼び出しが終了します。Claude Codeはサーバーにタスクのキャンセルを依頼します。

通常のバックグラウンドタスクでは、Esc はタスクを止めません。同じキーでも、待機中は止まり、裏に回ったあとは止まらないという違いがあります。裏に回ったタスクを止めるには、/tasks で選んで x を押すか、Claudeに頼みます。

サーバーが実際に止まるかは別の話です。キャンセルは「依頼」であり、サーバーがすでに一部を実行している場合や、最後まで終えてしまう場合があります。

待機中の時間制限はどう効くか

既定では、裏に回ったMCPタスクにClaude Code側の時間制限はありません。ただしサーバーがタスクで応答するまでは、通常のツール呼び出しの制限が適用されます。

待機に切り替えると事情が変わります。ツール呼び出しの時間制限、つまり壁時計の上限とアイドルタイムアウトが、タスク全体に適用されます。

• 壁時計の上限は、サーバーごとの timeout か MCP_TOOL_TIMEOUT で決まる(未設定時は約28時間)
• アイドルタイムアウトは、応答も進捗通知もない時間で判定される(既定はHTTP・SSE・WebSocketとclaude.aiコネクタが5分、stdioが30分)
• サーバーが状態確認に答えた回数は、アイドルの判定では「動いている」ことの印として数えられる

どちらかに達すると呼び出しが終わり、Claude Codeがサーバーにキャンセルを依頼します。長いジョブを待たせる場合は、これらの上限がジョブの所要時間より短くないかを先に確認します。環境変数の違いはMCP_TIMEOUTとMCP_TOOL_TIMEOUTの違いで整理しています。

既定のまま裏に回すと、終了や再開でタスクはどうなるか

待機に切り替える価値は、既定の挙動と比べて初めて見えます。既定のまま裏に回したMCPタスクは、終了や再開のたびに扱いが変わります。

stdioサーバーはClaude Codeの終了でプロセスごと止まります。サーバーのドキュメントに「処理は残る」と書かれていない限り、終了前にタスクが終わるのを待つか、/tasks で止めます。

待機に切り替えれば、この管理は要りません。呼び出しが返るまでセッションの中で待つだけなので、タスクを追いかけ直す場面がなくなります。

タスクがユーザーへの質問(elicitationダイアログ)を出すこともあります。/tasks を開いている間はダイアログが隠れるため、/tasks を閉じてから答えます。辞退や Esc もサーバーへの回答の一つで、その後に続けるかどうかはサーバーが決めます。

裏に回したタスクが届かないとき、/tasks に何が出るか

既定のまま使うと、サーバーに連絡が取れない状態が /tasks のエントリや終了時のトランスクリプトに文言で出ます。表示中もジョブは動いている可能性があり、Claude Codeは手を出さずに状態確認を続けます。

最後の行は、結果が不明になる唯一の型です。ビルドやデータ書き込みのような副作用のあるタスクでは、同じ呼び出しを繰り返す前に、実行済みの範囲を確認します。

変数を設定しても違いが見えないときは

この変数が変えるのは、サーバーがタスクで答えた呼び出しだけです。サーバーがタスクで返さない呼び出しは、設定の有無にかかわらず通常のツール呼び出しです。値を 1 にしても挙動が変わらないなら、まず次を順に見ます。

1. 使っているのが端末のCLI、Agent SDK、GitHub Actionsのいずれかか(VS Code拡張とデスクトップアプリには、MCPタスクがありません)
2. バージョンがv2.1.304以降か
3. 該当ツールが、サーバー側でタスクとして実行される種類の処理か
4. 実行中にフッターの 1 MCP task や /tasks の一覧に、MCPタスクが現れるか。現れないなら、その呼び出しはタスクではありません

サーバーを自作する場合は、リクエストの _meta にタスク拡張が含まれるときだけタスクで答えます。含まれないのにタスクで返すと、Claudeには Unsupported result type 'task' for tools/call というエラーが渡ります。

設定の書き方と効かない条件

settings.json の env に書きます。

{
  "env": {
    "CLAUDE_CODE_DISABLE_MCP_TASK_BACKGROUND": "1"
  }
}

全部の呼び出しを待たせたい場合は、CLAUDE_CODE_MCP_AUTO_BACKGROUND_MS を "0" にします。2分で移す閾値を変えたいだけなら、同じ変数にミリ秒を指定します(既定は120000)。

この設定が意味を持つのは、そもそも呼び出しがMCPタスクになるときだけです。次の条件がすべて揃う必要があります。

• サーバーがタスクに対応している
• HTTP・stdio・claude.aiコネクタのサーバーが、プロトコルリビジョン2026-07-28で接続されている
• セッションがフィーチャーフラグを取得できる(Amazon Bedrockなどのサードパーティプロバイダや、テレメトリを切った環境では使えない)
• 端末のCLI、Agent SDK、GitHub Actionsのセッションである(VS Code拡張とデスクトップアプリにMCPタスクはない)
• 呼び出しがメインの会話から出ている(サブエージェントからは出ない)
• 対話セッションである

最後の条件を補足します。Agent SDKや claude -p を --input-format stream-json で動かす場合は、CLAUDE_AUTO_BACKGROUND_TASKS=1 が要ります。このときも DISABLE_MCP_TASK_BACKGROUND が 1 でないことと、MCP_AUTO_BACKGROUND_MS が 0 でないことが、MCPタスクになる条件に含まれます。ワンショットの claude -p "<prompt>" では、MCPタスクそのものが使えません。

CLAUDE_CODE_DISABLE_BACKGROUND_TASKS=1 を設定した場合や、ベアモードで起動した場合も、それだけではClaudeはMCPタスクを待ちません。環境変数の一覧にも、この設定でもMCPタスクとMonitorツールはバックグラウンドで動くと書かれています。待たせたいときは、必ず前節の2つのどちらかを使います。

どちらを選ぶか

迷ったときは、次の表で見分けます。

DISABLE_MCP_TASK_BACKGROUND=1 が切り替えるのはMCPタスクの扱いです。MCP_AUTO_BACKGROUND_MS=0 は自動バックグラウンドそのものを止めるので、タスクでない通常のMCPツール呼び出しにも効きます。

MCPタスクという仕組みそのものの経緯はMCP Tasksとはにあります。バックグラウンドへ移すキーやコマンドはCtrl+Bで長時間コマンドを裏に回すに、環境変数全体の探し方は環境変数リファレンスにまとめています。