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

MCPサーバーのツール一覧はどう自動更新されるか

MCPサーバーを設定したあと、接続が安定して動き続けるかどうかは意外と見落とされがちです。MCPサーバーはlist_changed通知を送ることで、接続を切り直さずにツール・プロンプト・リソースの一覧を動的に更新できます。Claude Codeはこの通知を受け取ると、そのサーバーの利用可能な機能を自動的に再取得します。切断と再接続を挟まずに一覧が入れ替わるので、サーバー側で新しいツールを追加してもユーザーは何もする必要がありません。データベース作成でツール一覧が変わりうる管理系サーバーの例としてRedis Cloud MCPサーバーがあります。

再取得のリクエストが失敗した場合、Claude Codeはそれまで発見済みだったツール・プロンプト・リソースを保持し続けます。次の再取得が成功するまで空にはなりません。Claude Code v2.1.214より前は、再取得中の一時的なエラーがサーバーの機能一覧を空リストで上書きしてしまう挙動でした。

v2ランタイムの通知ストリームが切れたときの再接続限度

新しいプロトコル改訂に対応したサーバーとのlist_changed通知は、Claude Codeが開いたままにしているストリーム経由で届きます。このストリームが閉じると、Claude Codeは再度開き直しますが、そこには2つの上限があります。

ストリームが再開するまでのあいだ、そのサーバーから最後に取得したツール・プロンプト・リソースはそのまま使い続けられます。変更を早く反映させたいときは、/mcpからそのサーバーを手動で再接続します。

起動時のツール一覧はキャッシュから読まれることもある

list_changed通知はサーバーに接続したあとの更新の話ですが、そもそも起動時に毎回サーバーへ接続してツール一覧を取り直しているとは限りません。以前に使ったことがあるリモート(HTTP・SSE)サーバーは、/mcpでcached 2h ago · connects on first use · 5 toolsのように表示されることがあります。これは前回のセッションで保存した発見キャッシュからツール一覧を読み込んだ状態で、実際の接続はClaudeがそのサーバーのツールを最初に呼び出すタイミングまで遅延します。ツール自体は最初のメッセージから使える状態なので、利用者側で何かする必要はありません。

この発見キャッシュ(Claude Code v2.1.221で導入)は、Claude Code v2.1.238より前は既定でオンでした。v2.1.238以降は、アカウントへの段階的ロールアウトが有効な場合を除き既定でオフです。MCP_DISCOVERY_CACHE=1で明示的にオンにでき、0にすればロールアウトが有効なアカウントでもオフのままにできます。/mcpのサーバーメニューにある「Reconnect」を選ぶと、cached状態のサーバーはその場で接続してキャッシュエントリを維持し、接続済みか失敗状態のサーバーは再接続したうえでキャッシュエントリを破棄します。「Clear authentication」を選ぶと認証情報の失効とあわせてキャッシュエントリも破棄されます。エントリが破棄されたあとは、キャッシュではなくサーバー本体からツール一覧を取得し直します。

v1ランタイムとv2ランタイムで挙動が変わる

ここまでのストリーム再接続の仕組みは、すべてのMCP接続で同じように動くわけではありません。Claude Codeは2つのクライアントランタイムを持っています。v1ランタイムはMCP TypeScript SDK 1.x、v2ランタイムは同じコードをMCP TypeScript SDK 2.0上で動かしたもので、MCPプロトコル改訂2026-07-28に対応しています。

Claude Code v2.1.232以降は既定でv2ランタイムを使いますが、次の条件ではv1のままです。

• Amazon Bedrock・AWS上のClaude Platform・Google CloudのAgent Platform・Microsoft Foundryで実行している(ホストプラットフォームがCLAUDE_CODE_PROVIDER_MANAGED_BY_HOSTを設定していない限り)
• Claude apps gateway経由でサインインしている
• feature-flag取得がオフになっている

v2ランタイムはHTTP接続とclaude.aiコネクタサーバーに対して新しいプロトコル改訂へ対応しているかを尋ね、対応していればそちらを使います。stdioサーバーに対してはMCP_PROTOCOL_NEGOTIATIONをautoに設定した場合だけ尋ねます。Claude Code on the webのセッションでも同様で、MCPコネクタへ新改訂への対応を尋ねるのはMCP_PROTOCOL_NEGOTIATION=autoのときだけです。ここまで説明してきた通知ストリームの再接続は、この新しい改訂で通信しているサーバーに対してだけ働く仕組みです。つまり、古いプロトコルのままのサーバーやv1ランタイムでは、この節の再接続上限は関係しません。Anthropicは特定のサーバーを、機能フラグによって意図的に旧プロトコルのまま、あるいは通知ストリームの対象外のまま維持することもできます。

ランタイムを明示的に選びたい場合はMCP_SDK_GENERATIONをv1またはv2に設定し、新改訂を尋ねるかどうかはMCP_PROTOCOL_NEGOTIATIONをautoまたはlegacyに設定します。既定でv1になる環境でMCP_SDK_GENERATION=v2だけを設定しても、Claude Codeは新改訂を尋ねには行きません。尋ねさせたいならMCP_PROTOCOL_NEGOTIATION=autoも一緒に設定する必要があります。

新しいプロトコル改訂には制約もあります。MCPサーバーからセッションへメッセージを直接送り込むChannels連携を組んでいる場合、そのサーバーが新しい改訂で接続していると、Claude Codeはチャンネルサーバーとして登録しません。新改訂はチャンネルメッセージを運べない設計だからです。MCP_PROTOCOL_NEGOTIATIONを未設定のままにするかlegacyにしておけば、stdioサーバーは従来のハンドシェイクにとどまり、この制約を避けられます。

セッション中に接続が切れたリモートサーバーはどう復旧するか

Claude Codeは、セッション途中で切れたリモートサーバーの接続を指数バックオフで復旧します。最大5回まで試行し、最初の待機は1秒、以降は倍々に伸びていきます。挙動の見え方は実行形態によって変わります。

• 対話セッション: /mcpが再接続中のサーバーを「保留中」として表示します。5回失敗するとサーバーは「失敗」、認証が必要な場合は「要認証」として扱われ、/mcpから手動で再試行できます
• claude -pとAgent SDKセッション: 同じスケジュールで再接続しますが、試行状況を表示する/mcpパネルはありません

stdioサーバーはローカルプロセスのため、この自動再接続の対象外です。プロセスが落ちれば手動での再起動が必要になります。

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

HTTP・SSEサーバーへの最初の接続が、5xx応答・接続拒否・タイムアウトのような一時的なエラーで失敗した場合、Claude Codeは最大3回まで再試行します。それでも失敗すればサーバーを「失敗」として扱います。この再試行は起動時だけでなく、セッション途中でサーバーを追加したとき(クラウドセッションの設定から追加されるサーバーや、Agent SDKのsetMcpServers()で追加するサーバーを含む)にも同じように働きます。

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

• WebSocketサーバーの最初の接続
• 認証エラーまたはnot-foundエラー: 設定変更が必要なため再試行しても解決しません。ただしheadersHelperがサーバーのAuthorizationヘッダーの唯一の取得元になっている場合は例外で、試行のたびにヘルパーを再実行して新しい認証情報を取得し直せるので、認証エラーでも再試行します。リモートMCPのOAuth認証を組んでいる場合は、この再試行の有無がトークン切れの体感を左右します

サーバーが接続したあと、Claude Codeはtools/list・prompts/list・resources/listといった機能検出リクエストを送ります。一時的なネットワークエラーやサーバーエラーに対しては、短いバックオフを挟んで最大3回まで再試行しますが、認証エラー・4xx応答・リクエストタイムアウトは再試行しません。

Claudeはサーバーの失敗をどう知るか

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

この差は実務上の見え方に直結します。tool searchを無効にした構成(ENABLE_TOOL_SEARCH=falseや、カスタムのANTHROPIC_BASE_URLを使う構成など)では、MCPサーバーが落ちていてもClaudeがそれに気づかず、ツールが呼べない理由を説明しないまま作業を進めることがあります。ツールが急に使えなくなったのに原因が分からないときは、まず接続できない原因を4層で切り分ける手順を参照しつつ、tool searchが有効かどうかも確認すると切り分けが早くなります。

まとめ

MCPサーバーのツール一覧はlist_changed通知で動的に更新され、再取得に失敗しても直前の一覧を保持し続けます(v2.1.214以降)。v2ランタイムの通知ストリームには再オープンの上限があり、上限に達すると数時間単位で待機が発生するため、変更をすぐ反映させたいなら/mcpからの手動再接続が近道です。接続が切れたリモートサーバーは最大5回・指数バックオフで自動復旧し、最初の接続失敗も一時的なエラーなら最大3回まで再試行されます。認証エラーとWebSocketの初回接続だけは自動再試行の対象外です。サーバーの失敗がClaudeに伝わるかどうかはtool searchの有効・無効で変わるため、切り分けに迷ったらまずそこを確認します。