Claude Code MCPが「接続できない」原因を、公式ドキュメントの症状別対処表で全部洗い出した
Claude CodeでMCPサーバーが「Failed to connect」になる原因を公式ドキュメントとGitHub Issueの実例から整理。/mcp・/doctorでの一次診断から、ENOENT・パス問題・env未伝播・承認待ちまで症状別に対処法をまとめた。
エンジニアのゆとです。
claude mcp listを叩いたら、設定したはずのサーバーの横に✘ Failed to connectと出ている。あるいは/mcpを開いたら接続はしてるのにツールが0件。心当たりは全部潰したつもりなのに直らない——という状態でここに来た人は多いと思う。
自分も一度、案件用に組んだstdioサーバーが「さっきまで動いてたのに急に繋がらなくなった」ことがあって、原因を追ったら自分のiCloud同期フォルダのパスにスペースが入ってたせいだった。エラーメッセージは「Failed to reconnect」としか言わないので、そこにたどり着くまでに小一時間溶かした。
MCPの接続エラーは原因のバリエーションが多い割に、日本語で読める情報は「設定方法」がメインで「なぜ繋がらないか」を体系的に扱った記事が少ない。公式ドキュメントのdebug-your-configページに症状別の原因表が用意されているので、そこをベースに、GitHub Issueで実際に報告されている事例を足しながら整理した。
まず結論 — 「接続できない」は診断コマンドで9割絞れる
MCPの接続トラブルは、闇雲に設定ファイルを見直す前に/mcpと/doctorを叩くのが一番早い。この2つで「どこで止まっているか」がほぼ特定できる。
/mcpはサーバーごとの接続ステータスを表示する。ターミナルからclaude mcp listを打った場合も同様で、サーバー名の横に次のいずれかが出る。
| 表示 | 意味 |
|---|---|
✔ Connected | 正常に接続済み |
! Needs authentication | OAuth認証待ち。/mcpから認証フローを通す |
✘ Failed to connect | 起動または接続に失敗 |
⏸ Pending approval | プロジェクトスコープのサーバーが承認待ち |
✘ Rejected | 過去に拒否された（disabledMcpjsonServersを確認） |
「Failed to connect」なら起動プロセス自体の失敗、「ツールは0件だが接続済み表示」ならサーバーは起動できているのにツール一覧を返せていない、という別問題になる。この記事では前者を中心に、後者にも触れる。
/doctor（ターミナルからはclaude doctor）はインストール・設定ファイル・MCP設定エラーをまとめて診断してくれる。設定ファイルのJSON構文が壊れている場合はここで真っ先に引っかかる。
症状別 原因と対処 早見表
公式ドキュメントの「Check common causes」に載っているMCP関連の項目を軸に、現場でよく踏む地雷を追加してまとめた。
サーバーが.mcp.jsonに書いてあるのに読み込まれない
原因は配置場所の勘違いが大半だ。プロジェクト共有用のMCP設定はリポジトリ直下の.mcp.jsonに置く必要があって、.claude/配下やClaude Desktop形式の設定ファイルに書いても読まれない。同様に、settings.jsonにmcpServersキーを書いても無視される。settings.jsonはそのキーを読む仕様になっていない。プロジェクト共有ならリポジトリ直下の.mcp.json、ユーザー個人の設定ならclaude mcp add --scope userで追加するのが正解になる。
プロジェクトスコープのサーバーが「追加したのに出てこない」
.mcp.json経由のプロジェクトスコープサーバーは、初回だけ承認プロンプトが出る。このプロンプトを閉じてしまうと、サーバーは⏸ Pending approvalのまま止まる。claudeを対話モードで起動し直して承認すれば動き出す。
チーム開発でよく踏むのが、コミットされていない.claude/settings.jsonのenableAllProjectMcpServersをワークスペース未信頼の状態で使おうとするケースだ。クローンしたばかりのリポジトリは「信頼されていないフォルダ」扱いで、claudeを実行してワークスペース信頼のダイアログを通すまでこの設定は無視される。「他の人の環境では動くのに自分だけ承認待ちのまま」という報告の多くはこれが原因になっている。
特定のディレクトリから起動すると接続に失敗する
GitHub Issueで報告例がある。.mcp.jsonのcwdをきれいなパスに指定していても、Claude Code自体を起動したディレクトリにスペースや特殊文字（~など）が含まれていると、サブプロセスの起動処理に失敗してFailed to reconnect to [server-name]になる。iCloud同期フォルダのMobile Documentsのようなパスが典型例だ。
/Users/user/Library/Mobile Documents/iCloud~md~obsidian/Documents/MyVault/このIssueでの再現手順は、まさにこの手のパスからclaudeを起動して/mcpを叩くというもの。ワークアラウンドはシンプルで、スペースや特殊文字を含まないディレクトリにcdしてから起動すること。
# NG: パスにスペースが入っている
cd ~/Library/Mobile\ Documents/... && claude
# OK: クリーンなパスから起動
cd ~/Projects/myrepo && claude自分がハマったのもこのパターンだった。プロジェクト自体はクリーンなパスに置いていても、Finderの「最近使った項目」経由でiCloud側のショートカットから開いていたのが原因で、地味に気づきにくい。
commandやargsに相対パスを書いている
/mcpで見て「サーバーとして定義はされているのにFailed to connect」と出るとき、多いのがこのパターンだ。commandやargsに相対パスのスクリプトを指定していると、そのパスはClaude Codeを起動したディレクトリを基準に解決される。.mcp.jsonが置いてある場所を基準にするわけではない。ローカルスクリプトは絶対パスで書くのが安全で、npxやuvxのようにPATH上にある実行ファイルはそのままで問題ない。
spawn uvx ENOENT / spawn npx ENOENT
「サーバー自体は正しく設定してるのに起動時エラー」というときは、コマンド本体がマシンに入っていないだけ、というオチも多い。実際にDevelopersIOの検証記事では、ローカルMCPサーバー設定でこのエラーが出て、原因は単純にuv（Pythonのパッケージ管理ツール）が未インストールだったというケースが報告されている。
# コマンドが実際に存在するか確認
which uvx
which npx
# 入っていなければ入れる（uvの例）
brew install uvWindows環境だと、npxがシェルスクリプトではなく.cmdラッパー経由で解決される都合上、同じ設定でもmacOS/Linuxとは違う失敗の仕方をすることがある。Windows固有の詰まりが多い人は、環境ごと見直したほうが早いこともある。
環境変数がMCPサーバーに渡っていない
settings.jsonのenvキーに書いた環境変数は、Claude Code本体には渡るがMCPの子プロセスには伝播しない。これは仕様で、バグではない。MCPサーバーに環境変数を渡したいなら、.mcp.jsonのそのサーバーのエントリに直接envを書く必要がある。
{
"mcpServers": {
"github": {
"command": "npx",
"args": ["-y", "@modelcontextprotocol/server-github"],
"env": {
"GITHUB_TOKEN": "ghp_xxxxxxxxxxxx"
}
}
}
}トークン管理をこのファイルに直書きするのが気になる人は、Vault経由で都度注入する運用のほうが安全だ。MCPの基本設定まわりはこちらにまとめてある。
「接続済みなのにツールが0件」問題
/mcpでサーバーが✔ Connectedと出ているのに、ツール一覧が空という現象もある。これは起動自体は成功しているが、ツールリストを返す処理でつまずいているケースだ。
公式の対処手順はこう。
/mcpパネルから対象サーバーを選び、Reconnectを実行する- それでもツール数が0のままなら、
claude --debug mcpでセッションを開始してサーバーのstderr出力を直接確認する
サーバー側がtoolsケイパビリティを宣言しているのにツールを1つも返していない場合、/mcpパネル側にもその旨の警告が出るようになっている。自作サーバーでこの現象が起きるなら、大体はサーバー実装側のtools/listハンドラのバグを疑ったほうがいい。
タイムアウトと自動再接続の仕組み
「さっきまで繋がってたのに急に切れた」系のトラブルは、トランスポートの種類によって挙動が違うことを知っておくと切り分けが速い。
HTTP/SSEサーバーは接続が切れると自動で再接続を試みる。最大5回、1秒から始めて倍々に間隔を伸ばす指数バックオフ方式で、5回失敗すると/mcp上で失敗扱いになり、そこからは手動で再接続する必要がある。初回接続自体が5xx・接続拒否・タイムアウトで失敗した場合も同様に最大3回まで自動リトライされるが、認証エラーや404系は設定変更が要るエラーなので自動リトライの対象外になっている。
stdioサーバーはローカルプロセスなので、切断されても自動では再接続されない。ローカルスクリプト側がクラッシュしたら/mcpから手動でReconnectするしかない。
タイムアウトの挙動は環境変数で調整できる。
MCP_TIMEOUT: サーバー起動時のタイムアウト（ミリ秒）MCP_TOOL_TIMEOUT: ツール実行の待ち時間上限（デフォルトは約28時間とかなり長い）- サーバー個別の
timeoutを.mcp.jsonのエントリに書けば、そのサーバーだけ上書きできる
重い処理を投げるMCPサーバーで頻繁にタイムアウトする場合は、まずこの3つのどれが効いているかを切り分けるところから始めるといい。
それでも直らない時 — クリーンな状態と比較する
ここまでの個別チェックで直らない場合、最後の手段は「自分の設定を全部外した状態」と比較することだ。
# 全カスタマイズを無効化して起動（CLAUDE.md・skills・plugins・hooks・MCPサーバー全部オフ）
claude --safe-mode--safe-modeで問題が消えるなら、原因はCLAUDE.md・skills・plugins・hooks・MCPサーバーのどれかにあると分かる。そこから該当箇所を1つずつ戻していけば犯人を特定できる。
さらに疑わしい場合は、設定ディレクトリごと空にして比較する。
cd /tmp && CLAUDE_CONFIG_DIR=/tmp/claude-clean claudeこれで~/.claude配下を丸ごとバイパスした、完全にまっさらな状態のセッションが立ち上がる。この状態でも症状が出るなら、原因はユーザー・プロジェクトの設定の外側（管理者側のmanaged settingsや、Claude Code自体のバージョン起因の不具合）にある可能性が高い。
Claude Code自体が長時間セッションで不安定になる話は別記事で実測データを元に扱っているので、MCP以外の要因も疑うならこちらも合わせて見ておくと切り分けが早い。
サンドボックスのネットワーク制限がMCPサーバーの通信をブロックして、結果的にClaude Code本体がexited with code 1で落ちるという別パターンもある。「接続エラーというより、そもそもプロセスごと落ちる」場合はこちらを確認したほうが早い。
FAQ
claude mcp listと/mcp、どっちを使えばいい?
claude mcp listはターミナルから設定状況を一覧で確認するときに使う。/mcpはセッション中に接続ステータスの詳細やツール数を見たり、Reconnect・認証・承認をその場で操作したりするときに使う。トラブルシュート中はセッション内で/mcpを開きっぱなしにしておくと状態変化がすぐ見える。
WebSocketサーバーだけclaude mcp listに出てこないのはなぜ?
仕様。WebSocketサーバー(type: "ws")はclaude mcp listの一覧には表示されない。状態を見たいときはclaude mcp get <name>か/mcpパネルを使う必要がある。
設定ファイルを直したのに反映されない
.mcp.jsonやサーバー個別のenvを書き換えた場合は、Claude Codeの再起動が必要になることが多い。セッションを維持したまま設定だけ変えても、次回起動まで反映されないケースがある。反映されたかどうかは/mcpを開いて該当サーバーのステータスを見れば確認できる。
MCPの接続トラブルは「エラーメッセージが原因を教えてくれない」という一点に尽きる。Failed to connectもどのパターンも表示は同じで、中身は設定ミス・パス問題・未インストール・承認待ちとバラバラだ。だからこそ/mcpと/doctorで状態を可視化してから当たりを付ける、という順番を崩さないのが結局一番早い。
Claude Code自体は更新頻度が高いツールなので、この対処表も半年後にはズレている可能性がある。最終的には公式のMCPリファレンスとトラブルシューティングページを一度読んでおくと、今後別の症状に当たったときも自分で当たりを付けやすくなる。
