MCP_DISCOVERY_CACHEとは — MCPサーバー接続をcached表示で遅らせる環境変数
MCP_DISCOVERY_CACHEはリモートMCPサーバーへの接続を初回ツール呼び出しまで遅らせる環境変数です。cached表示の条件、有効期限を決める3つの関連変数、v2.1.238でのデフォルト変更をまとめます。
MCP_DISCOVERY_CACHE は、リモートのMCPサーバーへの接続タイミングを変える環境変数です。オンにすると、以前使ったことのあるHTTP/SSEサーバーは起動時ではなく最初のツール呼び出し時に接続されるようになり、/mcpパネルにはcachedという状態表示が出ます。ロールアウト対象なら既定で有効になっている場合もあるため、まず自分の環境の挙動を確認してから設定するのが安全です。
MCP_DISCOVERY_CACHEが変えるもの
Claude Codeは元々、MCPサーバーへの起動時接続を非ブロッキングで行う設計です。リモートのHTTP・SSEサーバーは最大20台まで並列に接続され、各サーバーのツールはハンドシェイクが終わったサーバーから順に使えるようになります。まだ接続中のサーバーが持つツールをClaudeが必要とした場合は、ToolSearch(既定)またはWaitForMcpServersツールの中で、そのサーバーの接続完了を待ちます。
MCP_DISCOVERY_CACHEをオンにすると、以前のセッションで一度接続したことのあるリモートHTTP・SSEサーバーについては、この起動時の実接続そのものを省略します。省略した分は「発見キャッシュ(discovery cache)」で補います。保存されるのは前回接続時のツール一覧です。
接続のタイミングはどう変わるか
キャッシュなし
起動時にリモートサーバーへ接続します。接続が済んだサーバーから、ツールが使える状態になります。
キャッシュあり
前回のセッションで保存したツール一覧を使います。実接続は、Claudeがそのサーバーのツールを初めて呼ぶときです。
ツールは最初のメッセージから使える状態で見えます。
alwaysLoadサーバーの起動待ちが解消される
alwaysLoad: trueを設定したMCPサーバーは通常、その挙動自体が起動時の待ちを発生させます。ツール検索を経由せず最初のプロンプトが組み立てられる時点でツールが揃っている必要があるため、Claude Codeは5秒のタイムアウト(MCP_CONNECT_TIMEOUT_MSの既定値)を上限に、そのサーバーの接続完了を待ちます。
ここにMCP_DISCOVERY_CACHEが例外を作ります。alwaysLoad: trueのリモートサーバーに有効なcachedエントリーがある場合、Claude Codeは接続を待たずキャッシュからツール一覧を供給します。alwaysLoadでないサーバーは既定でバックグラウンド接続です。MCP_CONNECTION_NONBLOCKING=0を設定すると、そちらも起動が待つ側に回ります。alwaysLoadを使っていて起動が遅いと感じたら、発見キャッシュが効いているかを/mcpパネルのcached表示で確かめられます。
同じ例外は非対話モード(claude -p)にもあります。--mcp-configフラグを渡した-p実行では、通常MCP_TIMEOUT(既定30秒)を上限に未接続サーバーの接続完了を待ってから最初のターンを実行します。ただしcachedなツール一覧を持つサーバーはこの待ちをスキップし、初回利用時に接続する扱いになります。system/initメッセージでは、そのサーバーはpendingと表示されます。Agent SDKのoptions.mcpServersで渡したサーバーも同じ扱いで、キャッシュ済みのリモートサーバーは最初のターンを遅らせません。stdioサーバーとキャッシュのないHTTP・SSEサーバーは、接続が済むまで最初のターンを待たせ、上限はMCP_TIMEOUT(既定30秒)です。SDKではenvオプションにCLAUDE_CODE_MCP_STARTUP_WAIT_MSを加えると、最初のターンの待ち時間を自分で指定できます。Claude Code v2.1.274以降が必要です。この待ちの上限の違いは、MCP_TIMEOUTとMCP_TOOL_TIMEOUTの違いで扱っています。
cached表示が出る条件と見え方
並列接続数を決める変数は、stdioとリモートで別です。stdioはMCP_SERVER_CONNECTION_BATCH_SIZE(既定3台)、リモートはMCP_REMOTE_SERVER_CONNECTION_BATCH_SIZE(既定20台)です。stdio側はMCP_DISCOVERY_CACHEの影響を受けませんが、stdioサーバーには渡す環境変数そのものを絞るCLAUDE_CODE_MCP_ALLOWLIST_ENVという別の設定があります。
cached状態が表示されるのは/mcpパネル(サーバーごとのメニューを含む)と、/pluginマネージャーの中です。表示形式は次のような1行になります。
cached 2h ago · connects on first use · 5 tools「2時間前にキャッシュされ、初回利用時に接続、5個のツールを持つ」という意味です。この表示が出る条件は3つです。
- 対象サーバーがリモートのHTTPまたはSSEサーバーであること(ローカルのstdioサーバーは対象外)
- そのサーバーに過去のセッションで一度接続したことがあること
- Claude Code v2.1.221以降であること
すべてそろう必要があります。プラグインが提供するリモートサーバーも同じ扱いで、/pluginマネージャー上でcached表示になり、Claudeが最初にそのツールを呼ぶまで実接続を待ちます。
有効化と無効化のやり方
最も単純なのはシェルの環境変数として渡す方法です。
export MCP_DISCOVERY_CACHE=1
claude明示的にオフへ固定したい場合は0を設定します。後述のとおりロールアウトで既定オンになっている環境でも、0を設定すれば強制的にオフに戻せます。
チームで固定値を共有したいときはsettings.jsonのenvキーに書きます。
{
"env": {
"MCP_DISCOVERY_CACHE": "1"
}
}~/.claude/settings.jsonならユーザー個人の全プロジェクトに、リポジトリ直下の.claude/settings.jsonならプロジェクトの全メンバーに適用されます。組織全体で統一したい場合は管理設定(managed settings)に同じ内容を書くと、開発者側の個人設定より優先されます。Claude Code環境変数全体の設定方法や優先順位の詳細はClaude Code環境変数リファレンスにまとめています。
デフォルト挙動はv2.1.238で逆転した
MCP_DISCOVERY_CACHEの既定値はバージョンによって違います。v2.1.238より前は、発見キャッシュは既定でオンでした。v2.1.238以降は既定でオフに変わり、Anthropic側の段階的なロールアウトで自分のアカウントが対象になっている場合だけ、明示設定なしでもオンの状態になります。
つまり同じ「何も設定していない」状態でも、使っているバージョンとアカウントのロールアウト状況によって挙動が変わり得ます。オン・オフのどちらかに固定したい場合は、ロールアウトの有無に依存せずMCP_DISCOVERY_CACHEを明示的に1か0に設定するのが確実です。管理設定(managed settings)に書けば、チーム全体で揃います。
ロールアウトの対象になるかどうかはアカウント単位で決まるため、同じバージョンのClaude Codeを使っていても、チームメンバーによってcached表示の有無が揃わないことがあります。クラウドセッションでは、v2.1.285から、settingsファイルではなくクラウド環境の変数としてMCP_DISCOVERY_CACHE=1を設定した場合に、コネクターのツール一覧がセッション再開後に再利用されます。ほかのMCPサーバーはキャッシュされず、起動時に接続されます。
キャッシュの有効期限を決める3つの変数
MCP_DISCOVERY_CACHEをオンにしたときの細かい挙動は、名前が似た3つの変数で調整できます。
| 変数 | 既定値 | 効果 |
|---|---|---|
MCP_DISCOVERY_CACHE_TTL_S | 既定値900秒 | 効果この秒数以内のキャッシュは更新せずに使う。超えても使い続けるが、背後で再取得(バックグラウンド更新)する |
MCP_DISCOVERY_CACHE_MAX_STALE_S | 既定値14400秒(4時間) | 効果この秒数を超えるとキャッシュを破棄し、起動時に直接接続する。上限は7日 |
MCP_DISCOVERY_CACHE_STRIKES | 既定値1回 | 効果バックグラウンド更新が連続でこの回数失敗すると、キャッシュを破棄して次の起動時に接続する |
MCP_DISCOVERY_CACHE_TTL_SはMCP_DISCOVERY_CACHE_MAX_STALE_Sの値で頭打ちになります。TTLをMAX_STALEより大きく設定しても、MAX_STALEの値が使われます。
バージョン差もあります。v2.1.238より前はMCP_DISCOVERY_CACHE_MAX_STALE_Sの既定値が86400秒(24時間)で、値の上限はありませんでした。v2.1.238以降はMCP_DISCOVERY_CACHE_MAX_STALE_Sが7日で頭打ちになります。MCP_DISCOVERY_CACHE_TTL_Sも、v2.1.238より前は上限がなく、以降はMAX_STALEが上限です。MCP_DISCOVERY_CACHE_STRIKESはv2.1.238以降でしか使えない変数です。ネットワーク接続が不安定な環境では、1回の失敗でキャッシュを捨ててしまわないよう、この値を大きくしておく使い方ができます。
/mcpパネルの操作がキャッシュに与える影響
/mcpパネルのサーバーメニューにある3つの操作は、キャッシュのエントリー自体を変更します。
- Reconnect:
cached状態のサーバーなら、次のツール呼び出しを待たずに今すぐ接続し、キャッシュのエントリーはそのまま保持します。ConnectedやFailed to connect状態のサーバーに対しては、再接続したうえでエントリーを破棄します - Clear authentication: サーバーの認証情報を取り消すと同時に、キャッシュのエントリーも破棄します
- Disable: サーバーを無効にするときも、エントリーを破棄します
エントリーを破棄したあとは、次回そのサーバーに接続するとき、ツール一覧をキャッシュからではなくサーバー本体から取得し直します。
よくあるつまずき
cached表示が出ていても、そのサーバーへの実際の接続がまだ確立していないだけで、設定自体が壊れているわけではありません。接続できないトラブルと混同しないよう注意が必要です。実際に接続が失敗するケースの切り分けはMCPサーバーに接続できないときの切り分け手順を参照してください。stdioサーバーの同時接続数はMCP_SERVER_CONNECTION_BATCH_SIZEで変えられます。
サーバーの追加やスコープの基本はClaude Code MCP設定ガイドにまとめています。
バージョン依存の変数が多いため、期待どおりに動かないときはまずclaude --versionでバージョンを確かめます。
単位の取り違えにも注意します。キャッシュ関連のうち_TTL_Sと_MAX_STALE_Sは名前どおり秒単位で、_STRIKESは失敗の回数です。一方MCP_CONNECT_TIMEOUT_MSやMCP_TIMEOUTはミリ秒単位で、同じMCP関連の変数群でも単位が揃っていません。
まとめ
起動待ちが気になるのは、alwaysLoad: trueのリモートサーバーを持つ構成と、claude -p --mcp-configで多数のリモートサーバーを読むスクリプトです。そうした構成では、/mcpパネルのcached表示の有無を見て、MCP_DISCOVERY_CACHEを明示的に1か0に揃えるところから始められます。