Claude CodeのSkipping connectionが出る原因と再接続の手順
プラグインのMCPサーバーに「Skipping connection (recent failure cached…)」と出たときの意味と、15分待たずに再接続する方法を、実行形態別にまとめます。
Skipping connectionは「前回の失敗を覚えていて、今回は試さない」という表示
claude -p、claude mcp list、claude mcp getの出力に次の文言が出ることがあります。
Skipping connection (recent failure cached; retries automatically in 15 min, or edit the plugin config to retry now)意味は単純です。プラグインが提供するstdioのMCPサーバーへの接続が15分以内に失敗しているので、Claude Codeは今回その接続を試さずに飛ばした、という通知です。サーバーが壊れていると断定する表示ではありません。
セッションはそのサーバーのツールなしで続きます。ここで見落としやすい点が1つあります。15分が過ぎても、同じセッションの中では自動で再接続しません。新しいセッションかclaude -pを、直近の失敗から15分以上あけて起動したときに、はじめて接続を試します。文言の「retries automatically」は、この「次の起動で」という意味です。
この表示が出るのは、次の条件がすべて重なったときです。
- 対象がプラグインに同梱されたMCPサーバーである
- 接続方式がstdio(手元でコマンドを起動する形式)である
- 直近15分以内に、そのサーバーへの接続が失敗している
自分でclaude mcp addしたサーバーや、HTTP・SSEのリモートサーバーは対象外です。リモートサーバーは初回接続が一時的な失敗なら最大3回再試行されます。
本当の原因は「最初の失敗」の側にある
この文言は、失敗そのものを説明しません。公式の記述では、失敗した接続のエラーをこの文言が置き換えます。新しい試行がまた失敗した場合は、その試行のエラーが表示されます。
つまり読者が見るべきものは次の2つです。
- 最初に接続が失敗した理由(コマンドが見つからない、起動直後に終了した、など)
- 失敗の記録が残っている15分間にどう再試行するか
1つ目は、記録が切れた後の最初の接続で出るエラーが手がかりになります。claude mcp listは各サーバーに✔ Connectedや✘ Failed to connectのような状態を付け、失敗時は理由を同じ行に足します。claude mcp get <name>ならIssue:の行に、HTTPステータスやエラーコード、サーバーが返した文面が出ます(v2.1.219以降。それ以前は失敗の状態だけです)。
プラグイン同梱のstdioサーバーは、claude mcp getで設定値が伏せ字になる点に注意してください。コマンドはCommand: stdio、引数は空のArgs:、環境変数はNAME=[REDACTED]と表示されます。認証情報を含みうるためです。実際の設定を見たいときは、プラグインをディスク上で探し、その.mcp.jsonかplugin.jsonを読みます。
15分待たずに再接続する方法は実行形態で違う
ここが実務の分かれ目です。使い方ごとに、公式が示す手段は次のとおりです。
| 使い方 | 今すぐ再試行する手段 |
|---|---|
| 対話セッション | 今すぐ再試行する手段/mcpでサーバーを選び、Reconnectを選ぶ |
| Agent SDKアプリ | 今すぐ再試行する手段TypeScriptはreconnectMcpServer()、PythonはClaudeSDKClient.reconnect_mcp_server()にサーバー名を渡す |
claude -p | 今すぐ再試行する手段同じプラグインを読み込む対話セッションで/mcpから再接続する |
| プラグイン開発中 | 今すぐ再試行する手段.mcp.jsonまたはplugin.jsonでcommand・args・envのどれかを変える |
claude -pだけは遠回りになる
claude -pには/mcpの画面がありません。そのため、同じマシン・同じOSアカウント・同じCLAUDE_CONFIG_DIRの値で対話セッションを開き、同じプラグインを読み込んで、そこでReconnectします。接続に成功すれば、次のclaude -pの実行から接続が試されます。
条件を揃える理由は、手順の文面にあります。CIのコンテナで落ちたclaude -pを、別のマシンやアカウントの対話セッションで直しても、手順が想定する「同じ条件」から外れます。
プラグインを開発している場合
command、args、envのいずれかを書き換えると、変更後のエントリを読み込む次のセッションかclaude -pで接続が試されます。ドキュメントがこの方法で挙げているのはこの3項目です。ほかの項目を変えたときの挙動は書かれていません。
プラグインでMCPサーバーを作る流れはmcp-server-devプラグインの記事にまとめています。設定の取りこぼしを事前に見つけたいときは、claude plugin validateでMCP設定を検査する方法が使えます。
通常のstdioサーバーとの違いは、飛ばされる15分があるかどうか
stdioサーバーの初回接続が失敗したとき、対話セッションではサーバーが失敗の状態になり、/mcpのReconnectで起動し直すのが基本です。claude -pでは、実行をやり直せば再試行されます。プラグイン提供のサーバーに限って、やり直しても15分の間は飛ばされます。
| 場面 | 通常のstdioサーバー | プラグイン提供のstdioサーバー |
|---|---|---|
claude -pで初回接続が失敗 | 通常のstdioサーバー次の実行で再試行される | プラグイン提供のstdioサーバー15分は飛ばされる |
| 対話セッションで初回接続が失敗 | 通常のstdioサーバー/mcpのReconnectで起動し直す | プラグイン提供のstdioサーバー同じ |
claude -pを定期実行したり、CIでMCPツールを使わせたりしている環境で、この差が効いてきます。
再接続まわりの周辺情報
同じ表示の周りで、あわせて知っておくと迷いにくい点を挙げます。
失敗したサーバーをまとめて再接続する
対話セッションで/mcp reconnect allを実行すると、失敗したサーバーと認証が必要なサーバーをまとめて再試行できます。v2.1.284以降の機能で、それ以前のバージョンではMCP server "all" not foundと表示されます。
スリープや時計の変更で出る別のメッセージ
ノートPCがスリープしたり、時計が進んだりした直後に接続が失敗すると、別の文言が出ます。
MCP server "<name>" connection timed out. Your computer went to sleep or its clock changed while connecting.Claude Codeは、スリープなのか時計の変更なのかを区別できないため、両方を名指しします。この場合の対処は、PCを起こしたまま接続し直すことです。接続できれば直すものはありません。シェルでは、claude -pやclaude mcp listを再実行し、その結果がSkipping connection (recent failure cachedで始まるなら15分待って再実行します。v2.1.307より前は、MCP server "<name>" connection timed out after <N>msというタイムアウトの文言でした。
Claudeにはどう伝わるか
ツール検索(tool search)が有効な既定の構成では、接続に失敗したサーバーの名前と接続エラーがClaudeに伝わります。そのため、Claudeが応答の中で「このサーバーは接続できていません」と報告することがあります。ツール検索を使わない構成では、失敗したサーバーはClaudeに伝わりません。
プラグインの変更を反映するとき
セッション中にプラグインを有効化・無効化すると、変更が適用された時点でそのMCPサーバーも接続・切断されます。再読み込みでは、設定が変わっていないサーバーの接続は保たれます。対話端末のないセッションでは、/reload-pluginsでプラグインのMCPサーバーは接続も切断もされず、変更は次のセッションで有効になります。そのため、claude -pの中から/reload-pluginsで再接続させることはできません。
ツール名とサーバー名の見え方
プラグイン同梱のMCPツールはmcp__plugin_<plugin-name>_<server-name>__<tool-name>という名前で呼ばれます。サーバー自体はplugin:<plugin-name>:<server-name>の名前で登録されます。権限ルールやフックのマッチャーに書くときは、この完全な名前を使います。サーバーのキーだけを書いたマッチャーは、プラグイン同梱のサーバーでは発火しません。
リモート型のプラグインサーバーでは別の表示になる
プラグインが同梱するHTTP・SSE型のサーバーは、この15分ルールの対象ではありません。以前に使ったことのあるサーバーなら、/mcpにcached 2h ago · connects on first use · 5 toolsのような状態が出ることがあります。起動時には接続せず、保存済みのツール一覧を使い、Claudeが最初にそのツールを呼んだときに接続します。この発見キャッシュはv2.1.221以降の機能で、環境変数MCP_DISCOVERY_CACHEで有効・無効を切り替えられます。
起動の待ち時間を延ばしたいとき
起動時の接続タイムアウトは環境変数MCP_TIMEOUT(ミリ秒)で変えられます。MCP_TIMEOUT=10000 claudeなら10秒です。遅いだけのサーバーが毎回タイムアウトで失敗し、そのたびに15分の記録が残る、という状況では、この値を見直す選択肢があります。
切り分けの順番
表示が出たときは、次の順で確かめると無駄がありません。
Skipping connectionが出たときの切り分け
- Q対象はプラグイン提供のstdioサーバーか?答えがリモートサーバーや自分で追加したサーバーは別の経路です。対話ならReconnect、claude -pなら実行し直します
再び失敗したら、その試行のエラーが出ます。それが本当の原因です。
CIや定期実行での扱い方の例
claude -pを繰り返し実行する環境では、1回目の失敗が15分間「伝染」します。ジョブがリトライするたびに同じ文言で飛ばされるので、リトライ間隔が短いと、失敗の原因を見ないまま全部のリトライが空振りします。
次はシェルでの確認の一例です。公式の手順ではなく、文言が出力に含まれるかを見る例です。
claude mcp list 2>&1 | grep -i "skipping connection" \
&& echo "プラグインMCPが失敗の記録で飛ばされています"見つかったら、リトライを重ねるより、対話セッションで同じ条件のまま/mcpからReconnectして原因のエラーを確かめるほうが早く片づきます。
まとめ
Skipping connectionは、プラグイン提供のstdioサーバーの失敗を15分間覚えているという表示で、原因そのものは別のところにあります。自動では次の起動まで再接続されず、同じセッションでは15分たっても戻りません。急ぐなら/mcpのReconnect、Agent SDKなら再接続のメソッド、claude -pなら同じ条件の対話セッションを経由します。
失敗した接続自体のエラーが読めたら、そこが直すべき箇所です。リモートサーバーの認証切れが疑わしいならMCP OAuthのConnection expired、起動の並列数が気になるならMCP_SERVER_CONNECTION_BATCH_SIZEの記事も参考になります。