Claude CodeのMCP接続エラーを切り分ける確認手順

MCP接続エラーの結論

Claude CodeでMCPに接続できない時は、まず状態表示を確認し、設定・承認・認証・通信を分けて調べます。承認待ちのサーバーはそもそも接続を試していない場合があります。設定を削除して再登録する前に、表示と変更点を残してください。

MCPはClaude Codeと外部ツールをつなぐための仕組みです。接続先が同じでも、手元のプログラムを起動するstdioと、URLへ接続するHTTPでは調べる場所が違います。2026年11月2日に確認した公式文書を基に、原因を狭める順序を整理します。

状態を確認する三つの操作

ターミナルでは一覧と詳細を確認し、Claude Codeの対話画面では接続状態を確認します。次の二行目のserver-nameは、一覧に表示された対象名へ置き換えてください。外部ツールの実行や設定の削除を目的とするコマンドではありません。

claude mcp list
claude mcp get server-name

対話画面で使うのは/mcpです。接続できた最後の時刻、失敗した時刻、直前の設定変更も記録します。画面を共有する前に、トークン、認証ヘッダー、非公開のURLや顧客名が含まれていないか確認してください。

表示から次の確認先を決める

公式MCP文書では、通信結果を表す表示と、設定上の判断を表す表示が区別されています。例えばPending approvalを通信タイムアウトと同じ方法で直そうとしても、原因は解消しません。

企業の管理ポリシーによって拒否される場合もあります。許可リストなどの制限では、サーバー自体が一覧に出ないこともあるため、表示がないだけで設定ファイルの破損とは断定できません。管理者へ対象名と必要な業務を伝えて確認します。

MCP接続を切り分ける9手順

1. 対象を一つに絞ります。一覧と詳細の表示を保存し、他の接続先にも同じ問題があるか確認してください。全サーバーの設定を一括で書き換えず、失敗する一件を調べます。
2. 直前の変更を確認します。Claude Codeの更新、ネットワークの切り替え、設定の編集、資格情報の更新を時系列で並べます。最後の成功時と違う項目を一つずつ確かめてください。
3. HTTPかstdioかを確認します。URLに接続する設定と、ローカルのコマンドを起動する設定を混同しないようにします。提供元の現行の設定例と、項目名や引数を照合します。
4. プロジェクト設定の承認を確認します。信頼していないフォルダに置かれた設定だけで、そのリポジトリが自分自身を承認することはできません。内容を確認してから対話画面で判断します。
5. 認証先を確認します。認証が必要という表示なら、対象アカウント、組織、期限、必要な権限を確認してください。ログインできたことと、目的のリソースを読めることは分けて扱います。
6. HTTPの接続先を確認します。提供元が案内するURL、通信方式、社内プロキシ、VPN、証明書に関するエラーを調べます。社内の制限を回避するために別経路へ切り替えないでください。
7. stdioの起動条件を確認します。実行ファイルの場所、引数、必要な環境変数、依存するプログラムを照合します。シェルでは動いてもClaude Codeから起動できない場合は、その実行環境の違いを調べます。
8. 承認した範囲だけ変更します。変更前の設定を残し、一度に一項目を直して同じ操作で確認してください。トークンの再発行や権限の拡大は、他の利用者への影響を確認してから判断します。
9. 安全な読み取りで結果を確認します。Connectedの表示に加えて、期待するツールと読み取り結果を確認してください。書き込みや削除を試験代わりに実行せず、原因と変更内容を記録します。

HTTP設定とstdio設定の違い

公式文書では、JSONにURLがあってもtypeを省くとstdioとして解釈され、設定エラーになると説明されています。HTTPサーバーではtype: "http"を指定します。streamable-httpもhttpの別名として使えます。URLだけを貼り付けた設定なら、この項目を先に確認してください。

SSEは非推奨とされています。ただし、提供元がSSEだけを公開している場合まで、URLを推測してHTTPへ書き換えてはいけません。提供元の案内と利用中のバージョンに合う方式を選びます。基本設定はMCPの使い方でも確認できます。

stdioでは、Claude Code側のオプションとサーバーへ渡す引数を--で区切る設定例が公式に示されています。コピーしたコマンドを直す時は、どちらの引数を変えるかを区別してください。必要なツールを導入する場合も、提供元、権限、費用を確認してから進めます。

承認待ちと認証切れへの対応

Pending approvalは、.mcp.jsonで指定されたプロジェクト単位のサーバーが未承認であることを示します。設定に書かれたURLや起動コマンドを確認し、信頼できるフォルダと接続先だけを承認します。拒否や無効化の理由が分からない場合は、有効化せず管理者へ確認してください。

Needs authenticationなら、まず認証の案内に従って対象アカウントを確認します。サーバーを削除すると、Claude Codeが保存したOAuthトークンやクライアント登録も削除されます。一方、発行元でトークンが失効するとは限りません。削除を認証のやり直しと同じ操作だと考えないでください。

この違いは退職者の権限を停止する時にも重要です。ローカル設定を消しただけで発行元の権限を停止したと判断せず、提供元の失効手順を確認します。日常の接続確認と権限管理の違いはClaude Codeの権限設定を参照してください。

復旧確認と管理者への引き継ぎ

復旧後は、接続表示、必要なツール、安全な読み取り、想定外の書き込みがないことを確認します。再起動後も同じ設定で接続できるかを確かめ、正常時の表示を一度保存してください。単に設定を保存できただけでは、接続や業務上の利用まで成功したことにはなりません。

Claude Code全体が応答しない場合について、公式TroubleshootingはCtrl+Cによる中断と、必要に応じた再起動を案内しています。中断する対象の処理を確認し、同じディレクトリでclaude --resumeから会話を再開できます。ただし、会話を再開できてもMCPの障害が直ったとは限りません。

管理者へ渡す情報は、時刻、OS、バージョン、サーバー名、通信方式、状態表示、最後の成功時刻、変更点、確認した結果です。秘密値を含む設定の全文は添付しません。接続先や権限の判断にはMCPのセキュリティ確認も併用してください。

よくある質問

設定を追加できたのに接続できないのはなぜですか

追加成功は設定が保存されたことを示します。承認、認証、通信まで成功した証拠ではないため、一覧と/mcpの状態を確認してください。

Pending approvalなら待つだけで直りますか

未承認の設定を確認する操作が必要です。通信の再試行を繰り返すのではなく、対話画面で接続先と設定内容を確認して判断します。

サーバーを削除すればトークンも無効になりますか

Claude Code内の保存情報の削除と、発行元での失効は別です。権限を停止する場合は、提供元が案内する失効方法も確認してください。

公式情報と導入相談

設定と状態表示は公式MCPガイド、応答しない時の対応は公式Troubleshootingを確認しています。表示や機能はバージョンにより変わるため、調査時の環境を記録してください。

社内で接続先や復旧担当を決められていない場合は、Miraigentの無料診断で、利用業務、必要な権限、障害時の担当を整理するところからご相談いただけます。