目次

MCP（Model Context Protocol）サーバを設定したのに、/mcp を開くとこんな状態で止まっていた——そんな経験はないだろうか：

/mcp

  filesystem      ✓ connected      (12 tools)
  github          ✗ failed
  notion          △ needs authentication
  my-server       ⏸ pending approval

MCP は Claude Code に 外部ツール（ファイル操作・GitHub・DB・各種API）を“手”として生やす仕組みだが、その接続は意外と詰まりやすい。原因は 「ローカルのサブプロセス起動失敗」「リモートの認証」「設定ファイルのミス」の大きく3系統に分かれ、/mcp のステータス表示がどれかを教えてくれる。本記事では、ステータスの読み方・原因別の対処・Windows特有の罠・切り分けワークフローまでを、公式情報をもとに整理する。

先に要点。① まず /mcp（と claude mcp list）で状態を見る——failed（起動失敗）か needs authentication（認証）か pending approval（承認待ち）かで対処がまったく違う。② ローカル（stdio）で最多なのはパスと環境変数、そして Windows の npx 問題。③ リモート（HTTP）で最多なのは OAuth 認証。④ 迷ったら claude --debug mcp でサーバのエラー出力（stderr）を見る。バージョンで挙動・既定値が変わる項目は、最新の公式で確認してほしい。

CLAUDE CODE · MCP STATUS

ステータスが対処を教える

— failed / needs auth / pending は、それぞれ直し方が違う

$ /mcp
✓ filesystem connected · 12 tools
✗ github failed → 起動・パス・npx
△ notion needs auth → /mcp で OAuth
⏸ my-server pending → 承認する

✗ failed＝ローカル起動の問題、△ needs auth＝リモート認証、⏸ pending＝承認待ち。
“繋がらない”を一括りにせず、まずステータスで分類するのが最短ルート。

1. このエラーは何を言っているのか

MCP サーバには大きく 2つの接続形態がある。① stdio（ローカル）——あなたのPC上で サブプロセスとしてサーバのコマンドを起動し、標準入出力で通信する。② HTTP（リモート）——クラウド上のサーバに URLで接続する（旧 SSE は非推奨）。「繋がらない」の中身は、この形態で大きく変わる。

ローカル（stdio）の失敗は、ほぼ「コマンドの起動そのものに失敗した」——パスが違う、npx が解決できない（特にWindows）、必要な環境変数が無くてサーバが即クラッシュ、など。リモート（HTTP）の失敗は、多くが「認証（OAuth）が済んでいない」——サーバが 401/403 を返し、needs authentication 状態になる。そして どちらでもないのに設定が効かない場合は、設定ファイルの場所・JSON の書き間違い・プロジェクト承認を疑う。

だから最初にやるべきは 「/mcp でステータスを見て、3系統のどれかを判別する」こと。エラーを一括りに「繋がらない」と捉えて手当たり次第にいじると遠回りになる。次章でステータスの読み方を押さえる。

2. まず /mcp でステータスを読む

セッション中に /mcp（シェルからは claude mcp list / claude mcp get <名前>）を叩くと、各サーバの状態が出る。代表的なステータスと意味はこうだ。

ステータス意味まず見るところ
✓ connected接続成功。横にツール数が出るツール数が 0 なら「接続はしたがツール未提供」→ 再接続/デバッグ
✗ failed起動に失敗、または再試行を使い切ったローカル起動＝コマンド・パス・npx・環境変数（§3・§4）
△ needs authenticationリモートが 401/403。OAuth未済/mcp から認証を実行（ブラウザで承認）
⏸ pending approvalプロジェクト用 .mcp.json サーバの承認待ち/mcp で承認。誤って却下したら claude mcp reset-project-choices
✗ rejected過去に却下したプロジェクトサーバ同上（reset-project-choices で再承認）

ポイントは 「failed なら起動の問題、needs authentication なら認証、pending なら承認」と、ステータスで打ち手が一意に決まること。とくに見落としがちなのが 「connected だがツール 0」——これは サーバは立ち上がったがツール一覧を返していない状態で、再接続か claude --debug mcp でのログ確認に進む。

3. 繋がらない主な原因と対処

とくに failed（ローカル起動失敗）と設定系の代表的な原因を、対処とセットで挙げる。

ROOT CAUSES

failed・設定系の主因

① パス／PATH
相対パスは起動ディレクトリ基準でズレる。ローカルスクリプトは絶対パスに。実行ファイルが見つからないと spawn ... ENOENT。
② 環境変数の渡し漏れ
サーバ用のAPIキー等はサーバごとの env（.mcp.json や --env）に。settings.json の env はMCPに伝わらない。
③ 起動タイムアウト
重いサーバは起動が間に合わず失敗。MCP_TIMEOUT（ミリ秒）を上げて起動。例：MCP_TIMEOUT=10000 claude。
④ 設定の場所・JSON
プロジェクト用 .mcp.json はリポジトリ直下（.claude/ 下や settings.json ではない）。未定義の ${VAR} があると設定解析に失敗。
⑤ stdout を汚す
stdioサーバが標準出力にログを書くとプロトコルが壊れる（接続したのにツール0等）。ログはstderrへ。
⑥ リモート認証
401/403＝needs authentication。/mcp から OAuth。固定の認証ヘッダが拒否されるとfailed 扱いになる点に注意。

ローカルは ①パス → ②環境変数 → ④設定場所の順に確認。
リモートは ⑥認証がほぼ全て。次章の Windows の罠も超頻出。

プロジェクト用 .mcp.json は git で共有でき、初回に承認プロンプトが出る。これをうっかり閉じるとサーバが無効のままになる（pending/rejected）。claude mcp reset-project-choices で承認をやり直せる。MCP の基本や、エージェント間連携の A2A も合わせて押さえると、接続周りの全体像が見える。

4. Windowsで繋がらない（最頻出の罠）

Windows ネイティブ環境で npx 系の MCP サーバが spawn npx ENOENT / Failed to connect で繋がらない——これは極めて多い。原因は、Windows の npx が実体としてバッチ（npx.cmd）で、Node のプロセス起動が .cmd を直接解決できないことにある。

対処：cmd /c でラップする

command を npx 直ではなく cmd にし、/c npx ... を引数で渡す：

{
  "command": "cmd",
  "args": ["/c", "npx", "-y", "@scope/your-mcp-server"]
}

あるいは WSL で動かすのも確実。where npx でパスが出ているのに失敗するなら、まずこの .cmd 問題を疑う。なお一部バージョンで起きた既知の不具合は後続版で修正されている可能性があるため、繋がらない時は最新版への更新も試す。

5. 切り分けワークフロー

原因が分からない時は、上から順に。「Claude Code のせい」と決める前に、まずサーバ単体で動くかを確かめるのがコツだ。

DIAGNOSE

上から順に切り分ける

1
/mcp と claude mcp list / get でステータスを確認（failed か auth か pending か）。
2
claude --debug mcp でサーバの stderr（エラー出力）を見る。クラッシュ理由が大抵ここに出る。
3
サーバを単体で起動（同じシェルで npx ... 等が通るか）。通らなければ Claude Code 以前の問題。
4
MCP Inspector（npx @modelcontextprotocol/inspector）でサーバ単体をUI検証。ツール一覧や呼び出しを確認できる。
5
Claude Desktop なら設定変更後に完全終了→再起動（ウィンドウを閉じるだけでは反映されない）。ログは mcp*.log。/doctor でも点検可。

鉄則：「単体で動くサーバか」を先に確定させる。
そこさえ切り分ければ、残りは設定（パス・env・場所）か認証に絞れる。

補足：MCP サーバを増やしすぎると、ツール定義がコンテキストを食う（とくに常時ロード設定の場合）。Claude Code は既定でツール検索により定義を遅延ロードするので影響は小さいが、使わないサーバは無効化しておくのが無難だ。コンテキストを圧迫して Prompt is too long を招くこともある。

6. 再発防止チェックリスト

MCP 接続でハマらない運用のコツ。

① ローカルスクリプトは 絶対パスで指定。② サーバ用のキーはサーバごとの env に書く（settings.json ではない）。③ Windows は cmd /c npx ... でラップ（または WSL）。④ .mcp.json はリポジトリ直下、JSON の構文と ${VAR} の未定義に注意。⑤ サーバは標準出力にログを出さない（stderr へ）。⑥ 設定変更後は再読込（Desktopは完全再起動、プロジェクトサーバは承認しなおし）。⑦ 繋がらない時は claude --debug mcp とサーバ単体起動で切り分け、必要なら最新版に更新。

まとめ

Claude Code の MCP サーバ接続エラーは、まず /mcp のステータスで3系統に分類するのが最短だ。✗ failed はローカル起動の問題（パス・環境変数・タイムアウト・設定場所、そして Windows の npx は cmd /c でラップ）、△ needs authentication はリモートの OAuth（/mcp から認証）、⏸ pending approval はプロジェクトサーバの承認待ち（/mcp で承認、誤却下は claude mcp reset-project-choices）。

切り分けは ① /mcp でステータス → ② claude --debug mcp で stderr → ③ サーバ単体起動 → ④ MCP Inspector → ⑤ Desktopは完全再起動の順。「Claude Code のせい」と決める前に、サーバが単体で動くかを先に確定させれば、残りは設定か認証に絞れる。環境変数はサーバごとの env に、.mcp.json はリポジトリ直下に、ログは stderr に——この3点だけでも事故は激減する。関連：MCPとは、MCPサーバの収益化、Claude Codeエラー集。

FAQ

Q. /mcp で「failed」と出ます。何から見ればいいですか？
A. failed はローカルサーバ（stdio）の起動失敗が大半です。順に、① コマンド/スクリプトのパス（絶対パスにする）、② 必要な環境変数（サーバごとの env に書く）、③ Windows なら cmd /c npx ... でラップを確認します。原因が見えなければ claude --debug mcp でサーバの stderr を確認し、まず同じシェルでサーバ単体が起動するかを試してください。

Q. 「needs authentication」と出て、ツールが使えません。
A. これはリモート（HTTP）サーバが認証を求めている状態（401/403）です。/mcp を開いて該当サーバの認証を実行すると、ブラウザで OAuth の承認に進みます。完了すればトークンは安全に保存・自動更新されます。なお Microsoft 365・Gmail・Google カレンダー等、一部のサービスは Claude Code からのローカル認証に対応せず、claude.ai の設定→コネクタ側で接続する形になります。

Q. Windows で npx のサーバがどうしても繋がりません。
A. Windows の npx は実体がバッチ（npx.cmd）で、そのままでは起動に失敗し spawn npx ENOENT になりがちです。command を cmd に、args を ["/c","npx","-y","パッケージ名"] に変えてラップしてください。WSL で動かすのも確実です。where npx でパスが見えるのに失敗するなら、ほぼこの .cmd 問題です。最新版で修正済みのこともあるので更新も試してください。

Q. 「connected」なのにツールが0個です。
A. サーバの起動には成功したが、ツール一覧を返していない状態です。よくある原因は stdio サーバが標準出力（stdout）にログを書いてプロトコルを壊していること——ログは必ず stderr に出してください。まず /mcp から再接続し、直らなければ claude --debug mcp でサーバの出力を確認します。

Q. 設定したのに /mcp にサーバが出てきません。
A. 設定ファイルの場所が違う可能性が高いです。プロジェクト共有用は .mcp.json をリポジトリ直下に置きます（.claude/ の下や settings.json の中では読まれません）。また未定義の ${VAR} があると設定解析に失敗します。プロジェクト用サーバは初回の承認が必要で、プロンプトを閉じると pending のままになります——claude mcp reset-project-choices で承認をやり直してください。