MCP error -32000: Connection closed—

Q: /mcp でfailedと出ます。何から見ればいいですか？

接続方式と Issue: を確認します。stdioならコマンド・パス・環境変数・stderr、HTTPならURL・ネットワーク・サーバ応答・認証を見ます。接続時に固定の Authorization ヘッダが401/403で拒否される場合もfailedなので、ローカル起動の問題と決めないでください。

Q: 「needs authentication」と出て、ツールが使えません。

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

Q: Windowsでnpxのサーバが繋がりません。

where.exe npx とNode/npmを確認し、同じパッケージ・引数で起動できるかを試します。.cmd の起動方法が原因なら cmd.exe /c npx ... を使えます。WSLでもLinux側の環境準備が必要です。OSを変えるだけで必ず解決するものではありません。

Q: connectedなのにツールが0個です。

そのサーバがツールを提供する設計かを確認してください。resourcesやpromptsだけなら0個でも異常とは限りません。ツールがあるはずなら、公開機能、権限、サーバ設定、ログを調べ、再接続します。stdioサーバの診断ログはプロトコル用のstdoutに混ぜず、stderrへ出します。

Q: 設定したのにサーバが使えません。

プロジェクト共有用の .mcp.json がプロジェクト直下にあるか、構文・適用範囲・承認状態を確認します。既定値のない未定義の ${VAR} は警告され、文字列のまま設定が読み込まれるため、起動や認証に失敗することがあります。HTTP設定は type も指定してください。拒否設定や管理ポリシーがある場合は、承認のやり直しだけでは解決しません。

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

1. このエラーは何を言っているのか
2. まず /mcp でステータスを読む
3. 繋がらない主な原因と対処
4. Windowsでnpxの起動を確認する
5. 切り分けワークフロー
6. 再発防止チェックリスト
まとめ
FAQ

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

/mcp

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

MCPはClaude Codeから外部ツールやデータを扱う仕組みです。接続に失敗したら、ステータスだけで原因を決めず、接続方式とエラー詳細を合わせて確認します。この記事ではローカルの起動、リモートの通信・認証、設定や承認を順に切り分けます。

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

CLAUDE CODE · MCP STATUS

ステータスと詳細から原因を探す

— failed は接続方式とエラー詳細も確認

$ /mcp

✓
filesystem
connected · 12 tools

✗
github
failed → Issue を確認

△
notion
needs auth → /mcp で OAuth

⏸
my-server
pending → 承認する

✗ failed＝接続失敗、△ needs auth＝認証を確認、⏸ pending＝承認待ち。
failedだけでは原因は決まりません。接続方式とエラー詳細を読みましょう。

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

例えばログに次のエラーが出ることがあります。文言だけでサーバの起動失敗と決めつけず、直前のログも確認してください。

MCP error -32000: Connection closed

MCP error -32000: Connection closed は、接続が閉じられたことを示します。MCPのTypeScript SDKでは -32000 を ConnectionClosed に割り当てています。サーバ終了や通信切断など、何が接続を閉じたかは直前のログで調べます。この文言だけでは、初期化前にプロセスが終了したのか、接続後に切れたのかは特定できません。根拠はSDKの接続終了処理です。

表示文言だけで原因を同一視しないでください。エラーはクライアント、バージョン、サーバによって異なります。別ツールの解説を使うときも、自分の接続方式とログに当てはまるかを確認します。

設定以外の不具合も候補になります。例えばIssue #20713には、Claude Code 2.1.19・macOSで初期化時の切断を経験した利用者の報告があります。利用者の原因推定を、Anthropicが認定した原因や現在の全環境に共通する不具合として扱わないことが大切です。報告するときはOS、バージョン、接続方式、秘密情報を除いたログを添えます。

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

ローカル（stdio）では、コマンドが見つからない、必要な変数がない、サーバが終了する、標準出力にログが混ざる、といった可能性を確認します。リモート（HTTP）では、URLの誤り、ネットワーク、5xx、タイムアウト、認証を確認します。どちらでも設定の場所・構文・適用範囲が関係します。発生頻度を根拠なく「ほぼ認証」「ほぼパス」と決めないでください。

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

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

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

ステータス	意味	まず見るところ
✓ connected	接続成功。横にツール数が出る	ツール提供を想定しているのに0個なら、公開機能・権限・ログを確認
✗ failed	ローカルまたはリモートへの接続に失敗	Issueの詳細と接続方式。HTTPなら通信・サーバ応答・固定認証ヘッダも確認
△ needs authentication	サインインや追加権限が必要。設定した認証方式も確認	`/mcp` から認証を実行（ブラウザで承認）
⏸ pending approval	プロジェクト用 `.mcp.json` サーバの承認待ち	`/mcp` で承認。誤って却下したら `claude mcp reset-project-choices`
✗ rejected	設定で拒否されているプロジェクトサーバ	disabledMcpjsonServersと管理ポリシーを確認。自分の承認選択を戻すならreset-project-choices

failed だけではローカル起動かリモート通信かを判定できません。claude mcp get <名前> の Issue: や /mcp の詳細にHTTPコード・エラー本文があれば読みます。固定の Authorization ヘッダが接続時に401/403で拒否されても failed です。また、resourcesやpromptsだけを提供するサーバなら、ツールが0個でも異常とは限りません。ツール提供を想定したサーバかを先に確認しましょう。詳しくは公式のステータス詳細を参照してください。

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

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

ROOT CAUSES

接続方式別の確認項目

① パス／PATH

相対パスは起動ディレクトリ基準でズレる。ローカルスクリプトは絶対パスに。実行ファイルが見つからないと spawn ... ENOENT。

② 環境変数の渡し漏れ

stdioサーバ固有の変数はそのサーバの env で指定。settings.json の env もセッションと子プロセスに適用されるため、そちらの値も確認します。

③ 起動タイムアウト

重いサーバは起動が間に合わず失敗。MCP_TIMEOUT（ミリ秒）を上げて起動。例：MCP_TIMEOUT=10000 claude。

④ 設定の場所・JSON

プロジェクト用 .mcp.json はプロジェクト直下（.claude/ 下や settings.json ではない）。既定値のない未定義の ${VAR} は警告され、文字列のまま残ります。

⑤ stdout を汚す

stdioサーバが標準出力にログを書くとプロトコルが壊れる。ログはstderrへ。

⑥ リモート認証

OAuthのサインインが必要なら /mcp で認証。固定の認証ヘッダが拒否されるとfailed 扱いになる点に注意。

ローカルは実行コマンド・環境変数・ログを確認。
リモートはURL・通信・サーバ応答・認証を確認し、実際のエラーに沿って切り分けます。

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

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

Windowsで spawn npx ENOENT が出たら、まず where.exe npx で実体とPATHを確認します。Node/npmが使えるか、指定パッケージを起動できるかも確認してください。Nodeの公式説明では、.cmd はそのまま実行できず、シェルや cmd.exe 経由で起動する方法を示しています。ただし、すべてのClaude Code環境でnpxの直接指定が失敗するという意味ではありません。

起動方法が原因の場合：cmd.exe /c 経由を試す

.cmd の起動方法が原因なら、次の形を試せます。パッケージ名は接続先の公式手順にあるものへ置き換えてください：

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

WSLを使う場合も、Linux側のNode・パッケージ・環境変数が必要です。WSLに変えれば必ず直るわけではありません。接続先サーバの対応環境と、利用中のClaude Codeのバージョンも確認しましょう。

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

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

DIAGNOSE

上から順に切り分ける

/mcp と claude mcp list / get でステータスを確認し、Issue: と接続方式も読む。

claude --debug=mcp でMCPの初期化・接続ログを確認。stdioサーバはstderrも確認します。

stdioなら設定と同じコマンド・変数で単体起動を確認。HTTPならURL・通信経路・応答コードを確認します。

MCP Inspector（npx @modelcontextprotocol/inspector）でサーバ単体をUI検証。ツール一覧や呼び出しを確認できる。

変更後に再接続して、必要な操作を試す。失敗が続くならバージョン・接続方式・秘密情報を除いたログを添えて報告します。

単体起動できることと、MCP接続・必要な操作が成功することは別です。
起動できても、プロトコル互換性、権限、ツール一覧取得、クライアント側の不具合が残りえます。

補足：MCP サーバを増やしすぎると、ツール定義がコンテキストを食う（とくに常時ロード設定の場合）。Claude Code は既定でツール検索により定義を遅延ロードするので影響は小さいが、使わないサーバは無効化しておくのが無難だ。コンテキストを圧迫して 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エラー集。

FAQ

Q. /mcp でfailedと出ます。何から見ればいいですか？
A. 接続方式と Issue: を確認します。stdioならコマンド・パス・環境変数・stderr、HTTPならURL・ネットワーク・サーバ応答・認証を見ます。接続時に固定の Authorization ヘッダが401/403で拒否される場合もfailedなので、ローカル起動の問題と決めないでください。

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

Q. Windowsでnpxのサーバが繋がりません。
A. where.exe npx とNode/npmを確認し、同じパッケージ・引数で起動できるかを試します。.cmd の起動方法が原因なら cmd.exe /c npx ... を使えます。WSLでもLinux側の環境準備が必要です。OSを変えるだけで必ず解決するものではありません。

Q. connectedなのにツールが0個です。
A. そのサーバがツールを提供する設計かを確認してください。resourcesやpromptsだけなら0個でも異常とは限りません。ツールがあるはずなら、公開機能、権限、サーバ設定、ログを調べ、再接続します。stdioサーバの診断ログはプロトコル用のstdoutに混ぜず、stderrへ出します。

Q. 設定したのにサーバが使えません。
A. プロジェクト共有用の .mcp.json がプロジェクト直下にあるか、構文・適用範囲・承認状態を確認します。既定値のない未定義の ${VAR} は警告され、文字列のまま設定が読み込まれるため、起動や認証に失敗することがあります。HTTP設定は type も指定してください。拒否設定や管理ポリシーがある場合は、承認のやり直しだけでは解決しません。

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