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)」で補います。中身は、サーバー接続直後に送るtools/list・prompts/list・resources/listなどの問い合わせ結果です。実際のネットワーク接続は、Claudeがそのサーバーのツールを初めて呼び出した瞬間まで先送りされます。
ツール自体は最初のメッセージから使える状態で見えるため、待ち時間が消えたように感じられますが、実際には接続のタイミングが「起動時」から「初回のツール呼び出し時」へ移っただけです。多数のリモートMCPサーバーを常時接続している構成ほど、起動時に並列接続する台数(既定20台の上限)を実際に使い切る機会が減り、恩恵を受けやすくなります。
alwaysLoadサーバーの起動待ちが解消される
alwaysLoad: trueを設定したMCPサーバーは通常、その挙動自体が起動時の待ちを発生させます。ツール検索を経由せず最初のプロンプトが組み立てられる時点でツールが揃っている必要があるため、Claude Codeは既定で5秒の接続タイムアウトを上限にそのサーバーの接続完了を待ちます。
ここにMCP_DISCOVERY_CACHEが例外を作ります。alwaysLoad: trueのリモートサーバーに有効なcachedエントリーがある場合、Claude Codeは接続を待たずキャッシュからツール一覧を供給します。この起動待ちが丸ごと発生しなくなるわけです。5秒という上限自体はMCP_CONNECT_TIMEOUT_MS(既定5000ミリ秒)で決まっています。alwaysLoadを使っていて起動が遅いと感じたら、発見キャッシュが効いているかを/mcpパネルのcached表示で確認する価値があります。
同じ例外は非対話モード(claude -p)にもあります。--mcp-configフラグを渡した-p実行では、通常MCP_TIMEOUT(既定30秒)を上限に未接続サーバーの接続完了を待ってから最初のターンを実行します。ただしcachedなツール一覧を持つサーバーはこの待ちをスキップし、初回利用時に接続する扱いになります。ヘッドレスでMCPサーバーを多数読み込むスクリプトほど、この差が実行時間に直結します。
cached表示が出る条件と見え方
対象になるのはリモートのHTTP・SSEサーバーだけです。ローカルのstdioサーバーはそもそも別枠で扱われます。並列接続数を決める変数も別で、stdioはMCP_SERVER_CONNECTION_BATCH_SIZE(既定3台)、リモートはMCP_REMOTE_SERVER_CONNECTION_BATCH_SIZE(既定20台)です。stdio側はMCP_DISCOVERY_CACHEの影響を受けません。
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が最初にそのツールを呼ぶまで実接続を待ちます。
claude mcp listやclaude mcp get <name>といったCLIコマンドの出力にcached表示は出てきません。確認したいときはセッション内で/mcpパネルか/pluginマネージャーを開く必要があります。
有効化と無効化のやり方
最も単純なのはシェルの環境変数として渡す方法です。
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に設定するのが確実です。
ロールアウトの対象になるかどうかはアカウント単位で決まるため、同じバージョンのClaude Codeを使っていても、チームメンバーによってcached表示の有無が揃わないことがあります。挙動をチーム全体で揃えたい場合は、各自のシェル設定任せにせず、管理設定(managed settings)にMCP_DISCOVERY_CACHEを明示しておくと確実です。
キャッシュの有効期限を決める3つの変数
MCP_DISCOVERY_CACHEをオンにしたときの細かい挙動は、名前が似た3つの変数で調整できます。
| 変数 | 既定値 | 効果 |
|---|---|---|
MCP_DISCOVERY_CACHE_TTL_S | 既定値900秒 | 効果この秒数を超えたキャッシュも使い続けるが、背後で再取得(バックグラウンド更新)する |
MCP_DISCOVERY_CACHE_MAX_STALE_S | 既定値14400秒(4時間) | 効果この秒数を超えるとキャッシュを破棄し、次の起動時にキャッシュを使わず直接接続する |
MCP_DISCOVERY_CACHE_STRIKES | 既定値1回 | 効果バックグラウンド更新が連続でこの回数失敗すると、キャッシュを破棄する |
3つの関係は「新しいキャッシュはそのまま使う → TTLを過ぎたキャッシュは使いつつ裏で更新する → 更新が続けて失敗すると諦めて破棄する → MAX_STALEを過ぎたキャッシュはそもそも使わず起動時接続に戻る」という段階構造です。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時間)で、かつ上限のキャップが無く任意の秒数を設定できました。MCP_DISCOVERY_CACHE_TTL_Sも同様に、v2.1.238より前は上限キャップがありませんでした。MCP_DISCOVERY_CACHE_STRIKESはv2.1.238以降でしか使えない変数です。ネットワーク接続が不安定な環境では、1回の失敗でキャッシュを捨ててしまわないよう、この値を大きくしておく使い方ができます。
/mcpパネルの操作がキャッシュに与える影響
/mcpパネルのサーバーメニューにある2つの操作は、キャッシュのエントリー自体を変更します。
- Reconnect:
cached状態のサーバーなら、次のツール呼び出しを待たずに今すぐ接続し、キャッシュのエントリーはそのまま保持します。ConnectedやFailed to connect状態のサーバーに対しては、再接続したうえでエントリーを破棄します - Clear authentication: サーバーの認証情報を取り消すと同時に、キャッシュのエントリーも破棄します
エントリーを破棄したあとは、次回そのサーバーのツール一覧をキャッシュからではなくサーバー本体から取得し直します。認証をやり直したのに古いツール一覧が表示され続けるような不整合は起きない設計です。
よくあるつまずき
cached表示が出ていても、そのサーバーへの実際の接続がまだ確立していないだけで、設定自体が壊れているわけではありません。接続できないトラブルと混同しないよう注意が必要です。実際に接続が失敗するケースの切り分けはMCPサーバーに接続できないときの切り分け手順を参照してください。
もう1つ紛らわしいのは、キャッシュの対象が「以前使ったことのあるリモートHTTP・SSEサーバー」に限られる点です。ローカルのstdioサーバーや、初めて追加したばかりのサーバーはMCP_DISCOVERY_CACHEをオンにしていてもcached表示にはならず、通常どおり起動時に接続されます。サーバーの追加やスコープの基本はClaude Code MCP設定ガイドにまとめています。
MCP_DISCOVERY_CACHE_STRIKESをv2.1.238より前のバージョンで設定しても効果はありません。バージョン依存の変数が多いため、期待どおりに動かないときはまずclaude --versionでバージョンを確認する価値があります。
単位の取り違えにも注意します。キャッシュ関連の3変数(_TTL_S・_MAX_STALE_S)は名前どおり秒単位です。一方MCP_CONNECT_TIMEOUT_MSやMCP_TIMEOUTはミリ秒単位で、同じMCP関連の変数群でも単位が揃っていません。
まとめ
MCP_DISCOVERY_CACHEは、リモートMCPサーバーへの接続を起動時から初回ツール呼び出し時へ遅らせ、/mcpパネルにcached表示を出す環境変数です。v2.1.238を境に既定値がオンからオフへ変わっているため、挙動を固定したいなら明示的に1か0を設定します。細かい有効期限はMCP_DISCOVERY_CACHE_TTL_S・MCP_DISCOVERY_CACHE_MAX_STALE_S・MCP_DISCOVERY_CACHE_STRIKESの3変数で調整でき、対象はリモートのHTTP・SSEサーバーに限られます。多くのMCPサーバーを常時接続している構成でセッション起動を軽くしたい場合に検討する価値がある設定です。