MCPのツール更新と接続断からの自動再接続の仕組み

サーバー側でツールを足したのに、Claude Codeに反映されないとき

MCPサーバーを設定したあと、ツールの増減が見えない場面で最初に疑うのはlist_changed通知の届き方です。MCPサーバーはこの通知で、接続を切らずにツール・プロンプト・リソースの一覧を入れ替えられます。通知を受けたClaude Codeは、そのサーバーの一覧を取り直します。データベースの作成でツールが増減しうる管理系サーバーの例がRedis Cloud MCPサーバーです。

実行形態によって、取り直す範囲が違います。

• 対話型のターミナルセッション: ツール・プロンプト・リソースの一覧を取り直します
• -p付きの非対話モードとAgent SDK: 通知で更新されるのはツール一覧だけです

取り直しに失敗しても、Claude Codeは発見済みのツール・プロンプト・リソースを保持します。次の取り直しが成功するまで一覧は空になりません。v2.1.214より前は、取り直し中の一時的なエラーで一覧が空になりました。

v1とv2のランタイムで、通知の届き方が変わる

Claude Codeは、2つのクライアントランタイムのどちらかでMCPサーバーに接続します。v1はMCP TypeScript SDK 1.x、v2は同じコードをSDK 2.0上で動かしたもので、MCPプロトコル改訂2026-07-28に対応しています。どちらを使うかは起動のたびに決まり、終了まで変わりません。

v2が既定になる条件は、フィーチャーフラグを取得するかどうかで分かれます。

サードパーティプロバイダーは、Amazon Bedrock・Claude Platform on AWS・Google CloudのAgent Platform・Microsoft Foundryです。Claude Codeを組み込むホストがCLAUDE_CODE_PROVIDER_MANAGED_BY_HOSTを設定している場合は、この表の上の行として扱われます。

v2は、HTTPサーバー、stdioサーバー、claude.aiコネクタサーバーに新しい改訂へ対応しているかを尋ね、対応していればそちらで接続します。stdioサーバーへの問い合わせは、v2.1.292以降の既定です。SSEとWebSocketのサーバーは常に従来のプロトコルで接続します。

ランタイムを固定するならMCP_SDK_GENERATIONにv1かv2を入れます。尋ねるかどうかの切り替えはMCP_PROTOCOL_NEGOTIATIONのautoとlegacyです。Anthropicは、取得させるフラグで特定のサーバーを従来のプロトコルのまま、あるいは次節の通知ストリームの対象外にもできます。

新しい改訂で接続したサーバーは、Channels連携のチャンネルサーバーとして登録されません。新改訂がチャンネルメッセージを運べないためです。チャンネルサーバーを従来のハンドシェイクのままにするには、MCP_PROTOCOL_NEGOTIATIONをlegacyにします(すべてのサーバーが従来の方式になります)。

通知ストリームが閉じ続けるときの再オープン上限

新しい改訂のサーバーからのlist_changedは、Claude Codeが開いたままにするストリームで届きます。ストリームが閉じると再び開きますが、閉じ方によって上限が2通りあります。

ストリームが戻るまでは、最後に取得したツール・プロンプト・リソースが使われ続けます。サーバー側の変更をすぐ拾いたいときは、/mcpからそのサーバーを再接続します。古いプロトコルのサーバーとv1ランタイムでは、この上限は関係しません。

起動直後に「cached」と出るのは、キャッシュから一覧を読んでいるから

以前使ったリモート(HTTP・SSE)サーバーは、/mcpでcached 2h ago · connects on first use · 5 toolsのように表示されることがあります。前回のセッションで保存した発見キャッシュからツール一覧を読み込んだ状態で、実際の接続はClaudeがそのサーバーのツールを最初に呼ぶときまで遅れます。最初のメッセージからツールは使えるので、利用者がすることはありません。

発見キャッシュはv2.1.221で入り、v2.1.238より前は既定でオンでした。いまは既定でオフで、アカウントへの段階的ロールアウトが有効なときだけオンになります。MCP_DISCOVERY_CACHE=1でオン、0にすればロールアウト対象でもオフのままです。

/mcpのサーバーメニューの操作ごとに、キャッシュエントリの扱いが変わります。

再接続と再試行の上限

接続まわりの再試行には、場面ごとに別々の上限があります。

セッション途中で切れたリモートサーバーの復旧

HTTP・SSEのようなリモートサーバーが途中で切れると、Claude Codeは指数バックオフで復旧を試みます。

claude -pとAgent SDKのセッションも同じスケジュールで再接続しますが、試行を見せる/mcpパネルはありません。SDKでは、切れたサーバーの状態がpendingに戻り、再接続に失敗し続けるとfailedかneeds-authになります。手動で再試行するにはTypeScriptならreconnectMcpServer()を呼びます。

クラウドセッションやSDKのsetMcpServers()で追加したサーバーにも、同じ復旧が働きます。これらでは、セッション途中の再接続が一時的な5xxのあとに失敗のまま残る不具合が、v2.1.239で修正されました。クラウドセッション側のツールの制約は、Claude Code on the webの制限の解説にあります。

stdioサーバーは自動復旧の対象外

ローカルプロセスのstdioサーバーは、自動では再接続されません。claude mcp addで--transportを省くと、stdioになります。

claude mcp add --help | grep -A1 "transport <transport>"

  -t, --transport <transport>  Transport type (stdio, sse, http). Defaults to
                               stdio if not specified.

上の出力はv2.1.287のものです。同じv2.1.287のclaude mcp --helpに挙がるサブコマンドはadd・add-json・get・list・login・logout・remove・reset-project-choices・serveなどで、再接続のサブコマンドはありません。再接続は、対話セッションの/mcpから行います。

最初の接続に失敗したとき

HTTP・SSEサーバーの最初の接続が、5xx応答・接続拒否・タイムアウトのような一時的なエラーで失敗すると、Claude Codeは再試行します。それでも失敗すれば、サーバーは「失敗」です。

再試行の対象外は次の2つです。

• WebSocketサーバーの最初の接続
• 認証エラーまたはnot-foundエラー: 設定変更が必要で、再試行では直らないためです

認証エラーには例外があります。headersHelperがサーバーのAuthorizationヘッダーの唯一の取得元なら、試行のたびにヘルパーを再実行して新しい認証情報を取り直せるので、再試行されます。リモートMCPのOAuth認証を組んでいる場合は、この有無がトークン切れの体感を左右します。

サーバーが接続したあとのtools/list・prompts/list・resources/listといった取得要求も、一時的なネットワークエラーやサーバーエラーなら再試行されます。認証エラー・4xx応答・リクエストタイムアウトは再試行しません。

セッションを再開した直後に「No such tool available」が出るとき

セッションを再開すると、保存済みの会話にあるツールを、そのMCPサーバーがまだ初回接続中のうちにClaudeが呼ぶことがあります。v2.1.284以降は、Claude Codeが最大10秒待ち、ツールが使えるようになった時点で実行します。待っても間に合わないとき、またはサーバーがすでに失敗後の再試行中のときは、Error: No such tool available: <ツール名>で失敗します。v2.1.284より前は、待たずに即座に失敗しました。

待つ仕組みは構成で変わります。tool searchが有効(既定)なら待機はToolSearchの呼び出しの中で、無効な構成ではWaitForMcpServersツールで行われます。

Claudeは、サーバーの失敗にどう気づくか

接続に失敗したサーバーをClaudeに伝えるかどうかは、MCP tool search(数千ツールをオンデマンドで発見する仕組み。Agent SDK版の考え方も参照)が有効かどうかで決まります。

tool searchが無効になる構成は、ENABLE_TOOL_SEARCH=falseのほか、カスタムのANTHROPIC_BASE_URLを使う構成、Google CloudのAgent Platform上でClaude 4.5世代より前のモデルを使う構成です。ANTHROPIC_BASE_URLがファーストパーティ以外のホストを指すときは既定で無効になり、ENABLE_TOOL_SEARCHを明示すれば上書きできます。CLAUDE_CODE_DISABLE_EXPERIMENTAL_BETASを設定した場合は、ENABLE_TOOL_SEARCHでも上書きできずオフのままです。こうした構成ではサーバーが落ちてもClaudeが気づかず、ツールが呼べない理由を説明しないまま作業が進むことがあります。ツールが急に使えなくなったのに原因が分からないときは、接続できない原因を4層で切り分ける手順と合わせて、tool searchが有効かどうかも見ると切り分けが早くなります。

まとめ

ツールが増えない、戻らないという症状は、まず通知ストリームの再オープン上限とリモートサーバーの再接続上限のどちらに当たっているかで分かれ、どちらも/mcpからの手動再接続で取り直せます。stdioサーバーだけは自動復旧がなく、tool searchを無効にした構成では失敗がClaudeに伝わりません。この2点は、原因を探る前に確かめておく価値があります。