結論：待ち時間を増やす前に、初回ターンの停止許容時間を決める
Claude Code 2.1.274では、非対話の初回ターンが接続中のMCPサーバーを待つ時間を、CLAUDE_CODE_MCP_STARTUP_WAIT_MSで上限化できます。公式changelogの説明どおり、値はミリ秒で、0は待ちません。遅いserverを待つか、待たずにMCPなしで切り分けるかを、業務の停止許容時間と処理の依存関係から決める設定です。
読者の課題は、CIやclaude -pの最初のターンが止まった時に、MCPの起動遅延なのか認証失敗なのかを説明できないことです。待ち時間を無制限にすると失敗判定が遅れ、短すぎると正常なリモート接続まで切り捨てます。まずread-onlyの一件で、MCPが必須か任意かを分けてください。
根拠はClaude Code v2.1.274公式リリースとClaude Code公式changelogです。MCPの追加方法、HTTPとSSEの扱い、信頼できないserverによるprompt injectionの注意はMCP公式文書を正本にします。既存のMCP接続トラブル診断は認証・到達性、MCPセキュリティは権限・情報持出しが中心で、本稿は初回起動の時間境界へ絞ります。
待つ設定と待たない設定を比較する
| 選択 | 向いている場面 | 先に決めること |
|---|---|---|
| 長めに待つ | 最初の処理からMCPが必須で、起動遅延が既知 | 最大待ち時間と超過時の終了処理 |
| 短めに待つ | 任意MCPを使い、初回応答を早く返したい | MCPなしで続行できる条件 |
| 0にする | CIでMCP起動を別ジョブとして検証する | server準備完了のreadback方法 |
| 設定しない | 既存の既定動作を比較基準にしたい | version更新前後の実測値 |
ここで注意したいのは、起動待ち時間がMCPの健全性を判定するタイムアウトではない点です。serverが待ち時間内に応答しても、権限不足、空のtool一覧、誤ったscope、危険な副作用が残ることがあります。反対に、時間を超えたからといってserverが壊れているとも限りません。ネットワーク、認証、serverプロセスの初期化を別々の証跡にしてください。
設定前に行う8手順
- 用途を一文にする。「issueを読むだけ」「本番変更を依頼する」など、初回ターンでMCPが必要な理由を書きます。
- 実行形態を固定する。対話型、
claude -p、SDK、CIのどれかを分け、同じ環境変数を一括配布しません。 - versionを記録する。2.1.274以降か、更新前の初回ターン時間とMCP接続状態を台帳へ残します。
- serverを分類する。HTTP、SSE、stdioを分け、必須・任意・停止対象の三群へ分類します。
- 待ち時間を測る。DNS、TLS、認証、初期化、tool一覧取得までの時間をログで測り、最大値だけでなく外れ値も見ます。
- 小さな値で検証する。まず限定projectで短い上限を設定し、timeout後の終了コードと初回出力を確認します。
- 0の経路を試す。
CLAUDE_CODE_MCP_STARTUP_WAIT_MS=0でMCPなしの挙動を確認し、後続ターンで接続済みかreadbackします。 - 停止条件を定義する。認証エラー、未知のserver、tool一覧欠落、副作用を伴う再試行は、自動継続せず人間確認へ送ります。
コマンドを例示する場合も、秘密情報を環境変数へ直書きしないでください。設定値は実行環境のsecret storeから注入し、MCPのURL、認証方式、server version、許可操作を同じ変更記録へ結び付けます。接続できない時に待ち時間だけを伸ばす変更は、原因を隠す可能性があります。
CIでは「初回ターンが終わった」だけを成功にしません。system/initのMCP状態、期待したserver名、許可されたtool、終了コード、生成物の差分を一緒に判定します。MCPが任意のjobなら、待たずに本体を検証し、MCP接続だけを別の準備jobで確認すると失敗範囲を狭められます。必須のjobなら、待ち時間超過を再試行で隠さず、ownerと復旧手順を通知します。
設定の比較では、同じ入力をMCPあり・MCPなし・server遅延の三条件で実行します。応答が変わる場合は、MCPがどの判断に影響したかを記録し、単に「初回ターンが成功した」と報告しません。外部データの取得や書き込みを含む場合は、人間承認を挟んだテスト用アカウントで行い、実データへ再試行しない境界を固定します。設定変更のロールバックは環境変数を外すだけで済む形にして、次回の障害時にも担当者が迷わないようにします。
外部serverを使う場合は、接続相手の変更も起動遅延の原因になります。DNSの切り替え、証明書更新、OAuthの再認証、serverのversion更新を一つずつ確認し、同じ時間帯の別jobと比較します。読者が設定を変更した後に判断できるよう、開始時刻、待機時間、server名、tool一覧、失敗理由を一枚のreadbackへまとめます。
このreadbackを残せば、設定変更の効果とMCPの問題を分けて説明できます。担当者が変わっても、待つ・待たないの判断を再現できます。復旧後の確認も容易になります。
公開運用のチェックリスト
- Claude Codeのversionと設定scopeを記録した
- 必須MCPと任意MCPを分けた
- 待ち時間の単位がミリ秒であることを確認した
- 0にした時のMCPなし経路を検証した
- 認証失敗と起動遅延を別のエラーとして扱った
- tool一覧とserver名の期待値を固定した
- 再試行回数と副作用のある操作を制限した
- 設定を戻すownerと期限を決めた
設定を全社標準にする前に、代表的なネットワーク、server、CI runnerを三つ選びます。平均値ではなく、始業時やデプロイ時の混雑を含めて観測し、どの遅延を許容するかを業務ごとに決めてください。待機時間を長くすることで人の確認が遅れる業務なら、速度より停止条件を優先します。
よくある質問
この環境変数はMCP serverのタイムアウトですか？
初回の非対話ターンが接続中のMCP serverを待つ時間を制限するための設定です。各serverの通信・認証・tool実行のタイムアウトとは分けて管理します。
0なら接続エラーはなくなりますか？
エラーをなくす設定ではありません。待たずに初回ターンを進める選択なので、後で接続状態と処理の前提を確認してください。
長い値を全社へ配布してよいですか？
業務ごとにMCPの必須性が違うため、まず限定scopeで実測します。CI、開発、運用の停止許容時間を分け、戻す手順を用意してから標準化します。
公式情報
次の一歩
MCPをつないだ後の業務停止条件や、人間確認の境界まで決まっていない場合は、設定値だけでは安定運用になりません。Miraigentの無料診断で、対象業務、server、権限、ログ、復旧責任を60秒から棚卸しできます。