Claude Code MCPの起動待機を制御する方法

まず結論：設定はこの1行

最初のターンでMCPの起動を最大5秒待つなら、CLAUDE_CODE_MCP_STARTUP_WAIT_MS=5000 claude -p "Run the scheduled check"を使います。MCPサーバーの準備を待たずにジョブを始められる場合は、CLAUDE_CODE_MCP_STARTUP_WAIT_MS=0を指定します。

Claude Code 2.1.274では、2026年9月17日にこの環境変数が導入されました。リリースノートで明記されているのは2点です。値は最初の非対話ターンにおける待機時間の上限をミリ秒で表し、0なら待機しません。一方、新しい変数のデフォルト値は公開されていません。将来デフォルトが変わったり、マシン側の環境変数に影響されたりしても起動ポリシーが変化しないよう、無人ジョブでは値を明示してください。

ここでいう非対話モードとは、-pまたは--printで起動する実行です。CIチェック、cronジョブ、SDKから開始するタスクなどが該当します。対話型のターミナルセッションを対象にした設定ではありません。

実務上の目安は次のとおりです。

この範囲は運用上の推奨値であり、Anthropicのデフォルト値ではありません。標準化する前に、自分の環境でサーバーを計測してください。

Claude Code MCPの起動待機が実際に制御する範囲

最初のターンを列車の出発、各MCPサーバーを乗り換えホームに置き換えると理解しやすくなります。CLAUDE_CODE_MCP_STARTUP_WAIT_MSが決めるのは、乗り換え客を待って列車が駅にとどまる時間です。各乗客が駅への到着を試み続けられる時間でも、乗車後の作業時間でも、旅全体の終了時刻でもありません。

制御範囲が狭いこと自体に意味があります。2.1.274より前は、運用担当者が別の時間枠を制御するMCP_TIMEOUTに頼りがちでした。今はスケジュールジョブ側で、すべてのサーバー接続や後続のツール呼び出しに同じ期限を課すことなく、最初のターンだけ短い準備待ちを選べます。

4つの時計を、4種類の失敗判断に分ける

安全に運用するには、各時計に名前を付け、役割を1つずつ割り当てます。

このほか、起動時に接続をブロックする一括処理には、デフォルト5,000 msのMCP_CONNECT_TIMEOUT_MSがあります。MCP_CONNECTION_NONBLOCKING=0を指定した場合や、サーバーにalwaysLoad: trueを設定した場合などが対象です。Anthropicの環境変数リファレンスでも、MCP_TIMEOUTとは明確に区別されています。

ツール呼び出しについては、.mcp.jsonで特定サーバーにtimeoutフィールドを設定すると、そのサーバーではMCP_TOOL_TIMEOUTより優先されます。データウェアハウスのクエリにはチケット検索より長い時間が妥当、といったケースに有効です。ただし、新しい初回ターン待機の値は変わりません。

この違いを押さえると、0があらゆる処理を高速化するスイッチではない理由も見えてきます。ツール検索が有効な場合、プロンプトが後から接続中のサーバーを必要とすれば、Claude CodeはToolSearch内で待機します。ツール検索が無効ならWaitForMcpServersが使われます。入口の待機を省略しても、ジョブの後段へ待ち時間が移る可能性があります。

遅いサーバーを再現するテスト

MCPの初期化レスポンスだけを遅らせるローカルstdioサーバーを使えば、この境界を再現できます。次の内容をslow-mcp.mjsとして保存します。

import readline from "node:readline";

const delay = Number(process.env.SLOW_MCP_DELAY_MS || 5000);
const lines = readline.createInterface({ input: process.stdin });
const send = message => process.stdout.write(JSON.stringify(message) + "\n");

lines.on("line", line => {
  const request = JSON.parse(line);
  if (request.method === "initialize") {
    setTimeout(() => send({
      jsonrpc: "2.0",
      id: request.id,
      result: {
        protocolVersion: request.params.protocolVersion,
        capabilities: { tools: {} },
        serverInfo: { name: "slow-ready", version: "1.0.0" }
      }
    }), delay);
  } else if (request.method === "tools/list") {
    send({ jsonrpc: "2.0", id: request.id, result: { tools: [] } });
  }
});

続いて、slow-mcp.jsonでClaude Codeからこのサーバーを参照します。

{
  "mcpServers": {
    "slow-ready": {
      "type": "stdio",
      "command": "node",
      "args": ["./slow-mcp.mjs"],
      "env": { "SLOW_MCP_DELAY_MS": "5000" }
    }
  }
}

実行コマンドはCLAUDE_CODE_MCP_STARTUP_WAIT_MS=1000 MCP_TIMEOUT=10000 claude -p "Reply with OK." --mcp-config ./slow-mcp.json --strict-mcp-config --output-format stream-json --verboseです。

--strict-mcp-configを付けると、テストに関係のないユーザー設定やプロジェクト設定のサーバーを除外できます。ストリーム形式では、各MCPサーバーの名前と状態を含む初期のsystem/initイベントを確認できます。渡した設定が不正な場合は、mcp_server_errorsも出力されます。

ローカル検証で確認できたこと

Claude Code 2.1.274で、5,000 ms待機するサーバーを使い、認証前の起動を確認しました。環境にログインしていなかったため、実行は認証段階で停止しています。計測対象は起動部分だけであり、まさに今回検証したい境界です。

この実時間にはClaude Codeとnpxの起動オーバーヘッドも含まれるため、そのままサービス目標に転用できる値ではありません。重要なのは状態の違いです。0と1,000 msではサーバーがpendingの間に最初のターンのゲートが開き、7,000 msでは同じサーバーがconnectedになりました。モデルのレイテンシーやジョブ全体の所要時間を測った結果ではありません。

本処理の前に準備完了を明示的に判定する

タイムアウトで答えられるのは「いつまで待つか」だけです。本番ジョブでは「どのツールが必須か」も決めなければなりません。

次の2段階でゲートを設けます。

1. 本処理を開始する前に、必須のリモートエンドポイントまたはローカルサーバーコマンドを1つずつヘルスチェックします。設定・承認済みのサーバーなら、claude mcp listでconnected、needs authentication、failed to connectなどの状態を確認できます。
2. Claude Codeのストリームでsystem/init.mcp_serversを調べます。必須サーバーがstatus: "connected"であることを条件とし、そのサーバーに関するmcp_server_errorsが空でなければ拒否します。キャッシュ済みサーバーや任意サーバーは、明示した許可リストに従って扱います。

必須サーバーがpendingなら、業務上の結果を受け入れる前に実行を終了します。任意サーバーなら、縮退モードを記録して続行します。こうすることで、待機時間の設定はポリシーそのものではなく、ポリシーへの入力になります。

検出結果のキャッシュには注意が必要です。ツール一覧がキャッシュされたリモートサーバーは、初期化時にpendingと表示され、最初のツール呼び出しで接続する場合があります。任意ツールには便利な挙動ですが、厳格な準備完了の保証にはなりません。必須ツールのゲートでは、実際の接続を要求するか、独自にヘルスチェックしてください。

最後に、プロセス全体をスケジューラ側の期限で囲みます。起動待機だけでは、モデルリクエスト、Bashコマンド、フック、後続のMCPツール呼び出しが残りの実行枠を使い切るのを防げません。

ビジネス上の価値は、主に失敗を早く確定できること

コンピューティング時間は確かに節約できますが、効果を大きく見積もるべきではありません。月間10,000件のジョブが本来30秒間待つところ、最初のターンの上限を3秒にしたとします。回収できる最大の実行容量は4,500 runner minutesです。

GitHubが現在掲載している料金では、標準的な2コアLinuxホステッドランナーは1分あたり$0.006、macOSランナーは1分あたり$0.062です。この単価なら、4,500分は無料枠を考慮する前でLinux時間$27、macOS時間$279に相当します。またGitHubでは各ジョブの使用時間を1分単位に切り上げるため、27秒短縮しても、ジョブ全体が同じ課金枠に収まるなら請求額は変わらないことがあります。

より大きな効果は運用面にあります。準備完了チェックに3秒で失敗すれば、スケジューラには再試行、適切な担当者への通知、フォールバックへの切り替えを行う余裕が生まれます。逆に、データベースや課題管理システムがないまま静かに始まったジョブは、もっともらしい一方で不完全な結果を生成しかねません。後からそれを見つけて巻き戻すコストは、ランナー時間より高くつきます。

大きなレスポンスも制御する場合は、Claude Codeのツール出力上限ガイドでワークフローの出力側を別途確認できます。無人インストールやネットワークポリシーも扱うなら、この準備完了ゲートとコマンド単位のネットワークアクセスを組み合わせてください。

効果が大きい7つのワークフロー

1. 財務・業務レポートの定期実行

財務担当者が午前6時にレポートを実行し、ウェアハウスのMCPサーバーを利用するとします。そのサーバーを必須に指定し、実測したコールドスタートへ少し余裕を加え、接続できなければ停止します。価値は単なる高速化ではありません。最新の数値を取得できないまま、リポジトリ内のファイルだけで整ったレポートが作られるのを防げます。

2. プルリクエストのリスク自動チェック

プラットフォームチームが、リスクの高いプルリクエストごとにClaude Codeを実行し、GitHub、課題管理、セキュリティスキャナーのツールを使うケースです。スキャナーとGitHubを必須、課題管理を任意にできます。最重要の証拠が抜けたままレビューが進むのではなく、理由の明確なエラーを開発者へすぐ返せます。

3. リリース調整ジョブ

リリース担当者が定期エージェントを使い、マージ済みの変更、進行中のインシデント、デプロイ状況を照合するとします。各情報源に準備完了ルールを設定できます。デプロイ用MCPサーバーが停止していれば、安全であるかのようなリリースノートを下書きする前にジョブを止められます。

4. 夜間のサポート振り分け

サポートチームがジョブにチケットの分類、アカウント履歴の確認、返信文案の作成を任せるケースです。ヘルプデスクと顧客データのサーバーは必須、Slackは任意にできます。待機時間に上限を設ければキューを滞らせず、準備完了ルールによって、情報源がないときに非公開の顧客情報を推測する事態も防げます。

5. インシデント対応アシスタント

オンコール担当者がアラートから非対話の診断を開始します。短い起動待機を設けると、ログとメトリクスに本当にアクセスできるかが明確になります。どちらかの必須サーバーが利用できなければ、不完全な診断に対応時間を費やすことなく、ラッパーから手動のランブックへ直ちに切り替えられます。

6. オートスケールする一時ランナー

チームがエージェントジョブごとに新しいコンテナを立ち上げる場合、ローカルstdioサーバーでは、パッケージの読み込み、認証ヘルパー、スキーマ検出などのコールドスタートが発生します。起動時間を測れば、妥当な7秒の準備待ちと、不調なサーバーを恒久的にごまかす回避策を区別できます。

7. マルチテナント型エージェント製品

顧客ごとに異なるMCP接続を提供する製品では、あるテナントはSalesforce、別のテナントはLinearを必須とし、外部ツールが不要なテナントもいます。実行単位の必須サーバー一覧があれば、同じオーケストレーション層からテナントごとに短い待機時間を選べます。最も遅い連携を全員のデフォルトにする必要はありません。

構築する価値がある3つのプロダクト

1. Claude Code CI向けMCP準備完了ゲート

最も有望なのはこれです。必須サーバーのポリシーを読み込み、待機時間を明示してClaude Codeを起動し、system/initを記録したうえで、エージェントの結果を受け入れる前に機械可読な準備未完了エラーを返す、小さなランナーラッパーです。

需要は限定的ですが、事業として検討できる水準です。claude code automationは米国で月間約140回検索され、サジェストデータでは前年比200%増、CPCは$10.88です。Claude Codeを自動実行する方法や、Claude CodeでMCPを設定する方法も検索されています。いずれも、このセットアップ課題が実在することを直接示しています。

販売可能な最小構成は、ポリシーファイル、GitHub Actionsのアノテーション、実行ごとのJSON証跡を備えたCLIです。課題は流通です。Anthropicがより高度な準備完了ポリシーをネイティブに追加する可能性があるため、複数のエージェントランタイムにまたがる履歴、アラート、対応力が持続的な価値になります。

2. タイムアウトポリシーのリンター

シェルスクリプト、CIファイル、設定、.mcp.jsonを走査し、時計の取り違えを検出するツールです。必須ツールがあるのに起動待機が0、ジョブ全体の期限は短いのにツールタイムアウトが28時間、任意の連携に上限がない、といった設定を警告します。

完全一致のキーワードmcp server timeoutは、米国で月間約10回検索され、報告されている前年比トレンドは-67%です。関連語にはMCP_TOOL_TIMEOUTがあり、Claude Codeのタイムアウトを延ばす方法も検索されています。準備完了ゲートの一機能としては十分な需要ですが、単独の事業を成立させるほどではありません。

MVPには、GitHub Actions、一般的なシェル構文、Claude CodeのMCP設定に対応するパーサーと、判断の明確な修正案が必要です。課題は過信を招くことです。実行時に測定しなければ、静的な設定だけでサーバーの実際のコールドスタート分布は分かりません。

3. 定期エージェントの起動テレメトリ

system/initイベントを、接続レイテンシー、pending状態、不正な設定、縮退実行のタイムラインへ変換するプロダクトです。プラットフォームチームにとって、多数のリポジトリにまたがる傾向やアラートは、JSONLファイルを手作業で読むより価値があります。

この案も、月間140回のclaude code automation検索を需要として共有します。さらにclaude code browser automationが月間40回あり、サジェストデータではこちらも前年比200%増です。より大きな潮流として、Claude Codeを反復可能なジョブへ組み込むチームが増え、起動証跡が運用課題になりつつあることを示しています。

MVPはイベントコレクター、必須・任意サーバーの対応表、準備状態がサービス目標を外れたときのアラートで構成できます。課題はデータの機密性です。MCP名とツールのメタデータから社内システムが推測される可能性があるため、秘匿化とセルフホストは後から加えるエンタープライズ向け機能ではなく、製品の中核要件です。

制約を踏まえた率直な結論

この設定が解決するのは、信頼できる自動化を構成する小さいながらも重要な一部分です。壊れたMCPサーバーを修復することも、期限切れのコネクターを再認証することも、後続のツール呼び出しを短縮することも、Claude Codeプロセス全体を止めることもできません。

最初の有用な処理にMCPが必要なジョブでは、0を使わないでください。初期化時にpendingとなり、ツールを検索する段階で再び待つ可能性があります。また、不安定なサーバーが正常に見えるまで値を引き上げるのも避けるべきです。HTTPサーバーとSSEサーバーは最初の接続で一時的に失敗すると再試行しますが、認証エラーやnot-foundエラーには設定変更が必要です。待機時間を延ばしても、事実が判明する時点が遅れるだけです。

stdioサーバーは、セッション途中で接続が切れても自動的には再接続しません。起動待機を長くしても、10分後の正常性は保証されません。

最善のポリシーは厳格で、単純です。最初のターンには短く明示的な待機時間を設定し、必須サーバーを名前で指定し、状態ゲートを設け、ツール用タイムアウトを分離し、ジョブ全体を外側の期限で囲みます。この構成なら、不可解な遅延ではなく、対処可能な失敗を得られます。

月曜日に、定期実行しているClaude Codeジョブを1つ選び、必須MCPのコールドスタートを測定してください。実態に合う最小の待機時間を設定し、必須サーバーがpendingなら結果を信頼する前に失敗させます。エージェントワークフロー全体にこの信頼性レイヤーを構築したい場合は、本番システムの構築を支援できます。