Claude CodeのWaitForMcpServersでバックグラウンド接続中のMCPを待つ

WaitForMcpServersは、まだバックグラウンドで接続中のMCPサーバーを待つ組み込みツールです。必要なサーバーが未接続のときにClaudeが自分で呼び、セッションを再起動せずにそのサーバーのツールを使えるようにします。

ただし、このツールは常に見えるわけではありません。ツール検索が有効な標準構成では現れず、同じ待ちをToolSearchが肩代わりします。この記事では、どちらの経路に自分の環境が乗っているかの見分け方と、待っても使えないときの切り分けを扱います。

WaitForMcpServersは何をするツールか

ツール一覧での説明は、次の3点に絞られます。

• 対象は、バックグラウンドで接続中のMCPサーバー(1つでも複数でも可)
• 目的は、リクエストがそのツールを使えるようにすること。セッションの再起動は要らない
• 呼ぶのはClaude。必要なサーバーがまだ接続されていないときに使う

ツール一覧の「許可が必要か」の列はNoです。ファイルを書き換えるわけでもコマンドを走らせるわけでもなく、接続を待つだけのツールなので、承認ダイアログは出ません。

人間が普段この名前を打つ場面はありません。/mcpで各サーバーの状態を見ている人が、「なぜ今のターンでClaudeは待ったのか」を追うときに、この名前に出会うことになります。

見えるのはツール検索が無効なときだけ

MCPのページは、接続中のサーバーを待つ方法を構成ごとに分けて書いています。

最後の行は例外です。Foundryの配備は、ツール検索をサーバー側が拒否します。Claude Codeはその拒否をAPIの応答で初めて知るため、最初はWaitForMcpServersではなくツール検索の経路で動きます。拒否を検知して全ツールの先読み込みに切り替えた後は、接続を終えたサーバーのツールが、Claudeの次のリクエストから使えるようになります。

つまり、このツールの有無はモデルの好みではなく、環境の設定で決まります。社内のゲートウェイ経由で使っている、あるいはENABLE_TOOL_SEARCH=falseを入れているチームでは、接続待ちの場面でWaitForMcpServersの呼び出しがログに出ます。

ツール検索が有効なら、待ちはToolSearchの中で起きる

標準構成では、MCPのツール定義は先読みされず、必要になったときにClaudeがToolSearchで探して読み込みます。起動直後は名前と各サーバーの説明だけがコンテキストに入ります。

接続中のサーバーのツールが必要になった場合、Claudeは別のツールを呼ぶ代わりに、ToolSearchを呼ぶだけで済みます。待ちはその呼び出しの内側で行われます。

もう1つ、ツール検索が有効な構成には利点があります。Claudeが作業している最中にサーバーの接続が終わると、Claude Codeは次のリクエストで、そのサーバーのツール名の一覧をClaudeに伝えます。同じターンの中で検索して呼べるので、次のメッセージを待つ必要がありません。

WaitForMcpServersはこの動きの代役です。ツール検索が無効だと、ツール名の一覧を後から差し込む仕組みがないため、Claudeに「待つ」という明示的な操作を渡す形になっています。

ツール検索の仕組み自体は、Tool Searchの正規表現版とBM25版の違いが検索側から詳しく書いています。

自分の環境がどちらの経路かを確かめる

見分け方は3つあります。

まず、環境変数を見ます。ENABLE_TOOL_SEARCHがfalseなら、ツール検索は無効です。autoやauto:5のようなしきい値指定の場合は、ツール定義の合計がコンテキストの10%(auto:5なら5%)に達するまで先読みされ、達すると全部が後回しになります。

echo "ENABLE_TOOL_SEARCH=${ENABLE_TOOL_SEARCH:-(未設定)}"
echo "ANTHROPIC_BASE_URL=${ANTHROPIC_BASE_URL:-(未設定)}"

ANTHROPIC_BASE_URLが設定されていて、第一者でないホスト(社内のプロキシなど)を指しているなら、ツール検索は既定で無効です。プロキシがtool_referenceブロックを通すと分かっている場合に限り、ENABLE_TOOL_SEARCH=trueで上書きできます。通さないプロキシでtrueにすると、リクエストが失敗します。

設定ファイルに環境変数を書いている場合は、settings.jsonのenvフィールドを確認します。次の形でfalseが入っていれば、そのプロジェクトではWaitForMcpServersの経路です(公式の記載に沿った例です)。

{
  "env": {
    "ENABLE_TOOL_SEARCH": "false"
  }
}

次に、CLAUDE_CODE_DISABLE_EXPERIMENTAL_BETASを見ます。これが設定されていると、ツール検索は無効のままで、ENABLE_TOOL_SEARCHに自分で値を入れても上書きできません。管理者がv2.1.227以降で管理設定を使えば、組織としてツール検索を有効に保つことはできます。

最後に、モデルです。ツール検索にはtool_referenceブロックに対応したモデルが必要です。Sonnet 4.5、Haiku 4.5、Opus 4.5以降が該当します。

ToolSearchだけを権限で止めることもできます。この場合にWaitForMcpServersが代わりに現れるかどうかは、ツール一覧にも記載がありません。ツール一覧は「ツール検索が無効のときに現れる」としか書いていないためです。

{
  "permissions": {
    "deny": ["ToolSearch"]
  }
}

待っても使えないときの切り分け

WaitForMcpServersは接続を待つだけで、接続を成功させるツールではありません。サーバー側に原因があれば、待っても状態は変わりません。

押さえておきたいのは、失敗の伝わり方が構成で違う点です。

• ツール検索あり: 失敗したサーバー名と接続エラーがClaudeに伝わり、Claudeは接続失敗として応答に書く。該当するツールが見つからないToolSearchの結果にも、同じ情報が入る
• ツール検索なし: 失敗した接続はClaudeに報告されない

後者の構成では、Claudeは「サーバーが失敗した」という手がかりを持たないまま動きます。WaitForMcpServersの呼び出しの後でもツールが現れないなら、自分で/mcpを開いて状態を確認するのが近道です。

claude mcp listは、各サーバーを✔ Connected、! Needs authentication、✘ Failed to connectのように表示します。失敗のときは、HTTPステータスやエラーコード、サーバーが返した文言も続きます。

claude mcp list

失敗の種類ごとの自動再試行は、MCPのページに次のように整理されています。

再試行を使い切って失敗になったサーバーは、/mcpから手動で再接続できます。失敗や認証待ちが複数あるときは、/mcp reconnect allが1回で済ませてくれます。使い方と効かないケースは、/mcp reconnect allの記事にあります。

待ちが出てくる周辺の場面

再開したセッションからの呼び出し

セッションを再開すると、保存された会話の中にあるMCPツールを、サーバーがまだ接続中のままClaudeが呼ぶことがあります。サーバーが初回の接続試行中なら、Claude Codeはその呼び出しを最大10秒保留し、ツールが使えるようになった時点で実行します。

10秒以内に接続できないとき、またはすでに失敗後の再試行に入っているときは、呼び出しがNo such tool availableのエラーで失敗します。これはWaitForMcpServersの待ちとは別の仕組みで、再開直後に限った保留です。

発見キャッシュで接続が遅れる場合

リモートのHTTP/SSEサーバーを以前に使っていると、/mcpにcached 2h ago · connects on first use · 5 toolsのような状態が出ることがあります。起動時には接続せず、保存済みのツール一覧を使い、Claudeが最初にツールを呼んだ時点で接続する動きです。ツールは最初のメッセージから使えるので、操作は要りません。

この発見キャッシュはv2.1.221以降の機能で、既定ではオフです(段階的な提供で有効になっているアカウントもあります)。MCP_DISCOVERY_CACHE=1でオン、0でオフに固定できます。v2.1.238より前は既定でオンでした。cachedの状態のサーバーで/mcpの「Reconnect」を選ぶと、その場で接続し、キャッシュは残ります。

サブエージェントでは使えない

サブエージェントは、メインの会話にある組み込みツールとMCPツールを受け継ぎます。ただし、いくつかのツールはどのサブエージェントからも外れます。WaitForMcpServersはその一覧に入っています。AskUserQuestion、EnterPlanMode、ScheduleWakeup、Workflowなども同じ扱いです。

サブエージェントのtoolsフィールドにWaitForMcpServersと書いても、受け継がれません。一方、バックグラウンドで動くサブエージェントでもToolSearchは残ります。接続待ちのサーバーを持つ環境で、サブエージェントに作業を任せる設計にしたいときは、ここを念頭に置きます。サブエージェント内での未接続サーバーの扱いは、ドキュメントに記載がありません。

動的なツール更新と再接続の関係は、MCPのlist_changedと再接続の記事で詳しく扱っています。長時間かかるツール呼び出しが自動でバックグラウンドに回る仕組みは別物で、MCPの自動バックグラウンド化の記事にまとめました。

設定でこの名前を書く場面

ツール名を直接書くのは、権限ルール、--allowedToolsと--disallowedTools、スキルのallowed-tools、hookのif条件など、設定の側です。ルールの書式はToolName(specifier)ですが、WaitForMcpServersのように絞り込みの指定子を持たないツールは、名前だけを書きます。hookのmatcherも同様で、括弧付きの書式ではなく素のツール名を使います。

ツール検索を無効にした環境で、allowedToolsを厳密に列挙して非対話の実行を組んでいる場合は、この名前が列挙から漏れていないかを見直す価値があります。ツール一覧では許可が不要となっていますが、--allowedToolsで使えるツールを絞る運用との相性は、ドキュメントに記載がありません。実行ログで呼び出しが拒否されていないかを、一度確かめておくと安心です。

まとめ

WaitForMcpServersは、ツール検索が無効な構成で、接続中のMCPサーバーを待つためのClaude用のツールです。標準構成ではToolSearchが同じ役目を果たすので、この名前を目にしないのが普通です。

名前が見えたら、環境のどこかでツール検索が外れています。ENABLE_TOOL_SEARCH、ANTHROPIC_BASE_URL、モデルの世代の順に当たると原因に届きます。その構成では失敗した接続がClaudeに伝わらないので、待ったのにツールが出ない場合は/mcpかclaude mcp listの表示が頼りです。