Claude CodeでMCPサーバーが繋がらない（failed/needs authentication）原因と対処

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

/mcp

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

MCPはClaude Codeから外部ツールやデータを扱う仕組みです。接続に失敗すると、ログには MCP error -32000: Connection closed という1行が出ることもあります。原因はステータス・接続方式・エラー詳細の3つを合わせると絞り込めます。この記事ではローカルの起動、リモートの通信・認証、設定や承認の順に切り分けます。

先に要点です。① /mcp と claude mcp get <名前> で状態と詳細を読みます。② failed はローカル・リモートの両方で出ます。stdioなら実行コマンドと環境変数、HTTPならURL・通信・サーバの応答・認証を見ます。③ 原因が見えなければ claude --debug=mcp で接続ログを取ります。直すのは実際のエラーに対応する箇所だけにして、再接続で結果を確かめます。

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

接続が閉じると、ログには次の1行が出ます。

MCP error -32000: Connection closed

MCP error -32000: Connection closed は、MCPの接続が閉じられたことを示します。MCPのTypeScript SDKは -32000 を ConnectionClosed に割り当て、接続が閉じたときにこの文言を出します（根拠はSDKの接続終了処理）。この1行が伝えるのは「閉じた」という結果だけで、閉じた理由は直前のログにあります。初期化の前にサーバのプロセスが終了したのか、接続後に通信が切れたのかを、そこで読み分けます。

設定が正しくても切れることがあります。Issue #20713 は、Claude Code 2.1.19・macOSで初期化中に接続が閉じた利用者の報告です。「競合状態」という原因は報告者の見立てで、このIssueは2026年4月に not planned としてクローズされています。自分で報告するときは、OS、バージョン、接続方式、秘密情報を除いたログを添えます。

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

ローカル（stdio）で起きるのは、コマンドが見つからない、必要な変数がない、サーバがすぐ終了する、標準出力にログが混ざる、といった失敗です。リモート（HTTP）では、URLの誤り、ネットワーク、5xx、タイムアウト、認証が原因になります。設定ファイルの場所・構文・適用範囲の誤りは、どちらの形態でも起きます。

最初に状態とエラー詳細を控え、stdioかHTTPかを見ます。設定を一度にいくつも変えると、どの変更が効いたか分からなくなります。次の表を入口に、該当する原因を1つずつ調べましょう。

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

セッション中に /mcp（シェルからは claude mcp list / claude mcp get <名前>）を実行すると、各サーバの状態が出ます。代表的なステータスと意味は次のとおりです。

failed はローカルの起動失敗でもリモートの通信失敗でも出ます。見分ける手がかりは詳細で、claude mcp list では ✘ Failed to connect の行末に、claude mcp get <名前> と /mcp の詳細画面では Issue: の行に、HTTPステータスやエラーコードとサーバが返したエラー本文が出ます。固定の Authorization ヘッダが接続時に401/403で拒否された場合も failed です。

リモートサーバがセッションの途中で切れると、Claude Code は自動で再接続を試み、その間 /mcp には pending と表示されます（承認待ちとは別の意味です）。5回とも失敗して failed になると MCP server "<名前>" disconnected · open /mcp to reconnect と通知されます（再認証が必要な場合は needs authentication になります）。stdioサーバは自動では再接続されないので、/mcp から手動で繋ぎ直します。また /mcp は、ツール機能を宣言しながらツールを1つも出さないサーバに印を付けます。resourcesやpromptsだけを提供するサーバは、ツールが0個でも正常です。詳しくは公式のステータス詳細を参照してください。

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

接続失敗や設定の不一致を調べるときの点検項目です。接続方式に当てはまる項目から順に見てください。

プロジェクト用 .mcp.json は共有できますが、秘密値は直接コミットしないでください。例えば ${API_KEY} を参照し、必要な値を各環境で設定します。リモートのURL・ヘッダでは、Claude Code自身の資格情報など一部の変数名は空として扱われます（公式の展開規則）。対話セッションではプロジェクトサーバの承認を求められますが、claude -p やSDKではそのプロンプトを出さずに読み込みます。それでも読み込ませたくないサーバは disabledMcpjsonServers に入れます（公式のproject scope）。関連：MCPの基本、A2A。

4. Windowsでnpxの起動を確認する

Windowsで spawn npx ENOENT が出たら、まず where.exe npx で実体とPATHを見ます。続けて、Node/npmが使えるか、指定パッケージを単体で起動できるかを試します。Nodeの公式説明によると、Windowsの .cmd ファイルは単体では実行できず、シェルか cmd.exe を経由させて起動します。

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

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

原因が分からないときは、上から順に進めます。Claude Code側を疑う前に、まずサーバ単体で動くかを確かめるのがコツです。

補足：Claude Code は既定でツール検索により定義を必要時に読み込むので、サーバを増やしてもコンテキストへの影響は小さく抑えられます。ただし alwaysLoad を指定したサーバやツール検索が無効な構成では定義が最初から載るため、使わないサーバは /mcp disable <名前> で無効化しておくと安全です。コンテキストを圧迫すると Prompt is too long につながります。

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

MCP接続でつまずかないための運用のコツです。

① stdioの実行ファイルやスクリプトは実体のパスで書く。② stdioの変数とHTTPの認証ヘッダを区別し、共有ファイルに秘密値を書かない。③ Windowsは where.exe npx とNode/npmを見て、起動方法に問題がある場合だけ cmd.exe /c を試す。④ .mcp.json はプロジェクト直下に置き、JSON構文・変数・承認を点検。⑤ stdioのログはstdoutではなくstderrへ。⑥ 変更は1つずつ行い、再接続と必要な操作で結果を確かめます。

まとめ

Claude CodeのMCP接続エラーは、ステータス・接続方式・エラー詳細を合わせて調べます。failed はローカルの起動失敗に限らず、HTTPの通信失敗や固定認証ヘッダの拒否でも出ます。needs authentication は認証、pending approval はプロジェクトサーバの承認を見直す入口です。

切り分けは状態と Issue: を読む → 接続方式に合ったログを読む → 単体・通信を検証 → 再接続して操作を試すの順です。デバッグのカテゴリ指定は claude --debug=mcp です。--debug-file ./claude-mcp-debug.log を併用すればログを保存できます。ログを共有する前に秘密情報を除いてください。関連：MCPとは、MCPサーバの収益化、Claude Codeエラー集。

Codexアプリで履歴は見えるのに送信だけが失敗する症状は、MCPではなく会話状態の問題です。Codex「thread not found」の対処法と復旧事例で扱っています。

FAQ

Q. /mcp でfailedと出ます。何から見ればいいですか？
A. 接続方式と Issue: を見ます。stdioならコマンド・パス・環境変数・stderr、HTTPならURL・ネットワーク・サーバ応答・認証が候補です。固定の Authorization ヘッダが接続時に401/403で拒否された場合も failed になり、Issue: にHTTPステータスが出ます。

Q. 「needs authentication」と出て、ツールが使えません。
A. 対処は認証方式で分かれます。 OAuthを使うサーバなら/mcpから認証します。独自認証のheadersHelperでは、ツール呼び出しが401/403を返したあと、資格情報を取り直して再試行しても失敗するとこの状態になります。helperがAuthorizationを返す構成ではOAuthへ切り替わらないため、取得元と返す資格情報を直して再接続します。Microsoft 365・Gmail・Google カレンダーなどのAnthropic提供コネクタはClaude CodeからのローカルOAuthに対応していません。claude mcp add や .mcp.json で追加して /mcp からサインインすると is Anthropic-hosted and doesn't support local OAuth と表示されるので、その登録を外してclaude.aiのコネクタ設定で接続します。根拠は公式の独自認証の説明です。

Q. Windowsでnpxのサーバが繋がりません。
A. where.exe npx とNode/npmを見て、同じパッケージ・引数で起動できるかを試します。.cmd の起動方法が原因なら cmd.exe /c npx ... で起動できます。WSLで動かす場合は、Linux側にNodeとパッケージを用意します。

Q. connectedなのにツールが0個です。
A. まずそのサーバがツールを提供する設計かを見ます。resourcesやpromptsだけを提供するサーバなら0個で正常です。ツール機能を宣言しているのに0個なら /mcp がそのサーバに印を付けるので、公開機能、権限、サーバ設定、ログを調べて再接続します。stdioサーバの診断ログはプロトコル用のstdoutに混ぜず、stderrへ出します。

Q. 設定したのにサーバが使えません。
A. プロジェクト共有用の .mcp.json がプロジェクト直下にあるか、構文・適用範囲・承認状態を見直します。既定値のない未定義の ${VAR} は警告されたうえで文字列のまま読み込まれるため、起動や認証の失敗につながります。HTTP設定には type も書きます。claude mcp get <名前> が ✘ Rejected を返すなら、どれかの設定ファイルの disabledMcpjsonServers に入っているので、承認をやり直すだけでなくその項目を外します。

設定とコマンドの参照：env設定、CLIリファレンス、MCP接続リファレンス。