MCPサーバーを追加したのに認識されない──設定ファイル・スコープ・コマンド単体実行で切り分ける

MCPサーバーが認識されない時は、「設定ファイルが読まれているか」「どのスコープに書いたか」「そのコマンドは単体で起動するか」の順に潰すと短く終わる。厄介なのは1つ目で、置き場所を間違えた設定ファイルはエラーを出さずに無視される。Claude Code 2.1.246（macOS、Node v25.9.0）で .mcp.json を .claude/ の中に置いて claude mcp list を叩いたところ、返ってきたのは No MCP servers configured. の一行だけだった。MCPそのものの仕組みはMCP（Model Context Protocol）とはにあるので、この記事は繋がらない時に何を叩くかだけを扱う。

• プロジェクト用MCP設定は、リポジトリ直下の .mcp.json に mcpServers キーで書く。.claude/ の中に置く、servers キーにする、settings.json に書く、はいずれも読まれない（公式 Debug your configuration）
• claude mcp add の Added ... は「設定を書いた」の意味で、接続成功ではない。判定は claude mcp list の ✔ Connected / ! Needs authentication / ✘ Failed to connect / ⏸ Pending approval で行う
• 自環境で5パターンを再現した結果、キー名ミス・未設定の環境変数・予約語の名前はすべて理由付きで診断されたが、置き場所ミスだけが無言で失敗した

（本記事の情報は2026年8月27日時点、Claude Code 2.1.246 で確認したものです）

「Added」と出ても、つながっているとは限らない

公式ドキュメントは、claude mcp add が出す Added ... は設定が書き込まれたことを示すもので、接続の可否は claude mcp list が各サーバーの横に出す健全性ステータスで判断する、と明記している。失敗表示は「listコマンドが失敗した」ではなく「そのサーバーに接続できなかった」を意味する。

自環境でも同じだった。即座に終了するだけのダミースクリプトを登録すると、追加時は Added stdio MCP server relpath ... to user config と成功したように見えるが、claude mcp get の結果はこうなる。

relpath:
  Status: ✘ Failed to connect
  Issue: -32000: MCP error -32000: Connection closed
  Type: stdio

公式の filesystem サーバーを絶対パス付きで登録した場合は ✔ Connected になった。追加した時点で判断せず、必ず claude mcp list か /mcp を通す。なお WebSocket 型のサーバーは claude mcp list に出てこない仕様で、claude mcp get <name> か /mcp で見る。

症状から原因へ分岐する表

公式ドキュメントの記述と自環境の再現を突き合わせると、こう分岐する。

設定ファイルを.claude/に置くと、エラーすら出ない

意図的に壊した設定を段階的に直しながら claude mcp list を叩いた結果が以下だ。CLAUDE_CONFIG_DIR を使い捨てディレクトリに向けた隔離環境で実行しており、既存の設定には触れていない。

差が出たのは1行目だけだ。キー名の間違いも未設定の環境変数も予約語も、すべて「MCP config diagnostics」として理由付きで出る。ところがファイルの置き場所を間違えた場合だけ、警告も診断も出ず、単に「設定なし」として扱われる。VS Code の mcp.json を参考にして .claude/ の下に置く、あるいは VS Code 流に servers キーで書く、という取り違えは公式ドキュメントも「よくある原因」の表に載せている。設定を書いたのに何も起きない時は、まず ls でファイルの位置を確認するのが早い。

スコープを間違えると「あのプロジェクトでは動くのに」が起きる

Claude Code のMCP設定には3つのスコープがあり、保存先と適用範囲が違う。

claude mcp add は何も指定しないと local スコープに書く。「自分のマシンの他のリポジトリで見えない」の多くはこれで、--scope user で入れ直せば済む。逆にチームメンバーの環境で見えないなら --scope project を使い、.mcp.json をコミットする。

同名のサーバーが複数の場所で定義されている場合、Claude Code は最も優先度の高い定義ひとつだけを使い、スコープをまたいでフィールドをマージしない。優先順位は local → project → user → プラグイン提供サーバー → claude.ai コネクタの順で、3つのスコープは名前で、プラグインとコネクタはエンドポイントで重複を判定する。片方を直しても反映されない時は、上位に古い同名定義が残っていないかを疑う。

なお ~/.claude.json と ~/.claude/settings.json は別物で、permissions・hooks・env は後者に書く。この混同は当サイトでも事故を起こしており、経緯はClaude Codeがエラーで動かない時の切り分け手順に書いた。

コマンドを単体で実行すると、どちらが悪いかが決まる

✘ Failed to connect に一番効くのは、設定に書いたコマンドをそのままターミナルに貼って実行することだ。MCP公式のトラブルシューティングも、構文とパスの確認・ログ確認に続けて、手動実行してエラーが出ないか見る手順を挙げている。ここでエラーが出ればサーバー側、何事もなく起動すればクライアント側の設定という切り分けになる。

このとき効く公式の注意点が3つある。作業ディレクトリは未定義になりうる（macOSでは / になることがある）ため絶対パスを使うべきだとされ、Claude Code 側も command や args の相対パスは .mcp.json の場所ではなく起動したディレクトリを基準に解決される、と明記している。環境変数は、stdio で起動されたサーバーが限られた一部しか継承しない（集合はプラットフォーム依存）ため、必要な値をエントリ内の env に直接書く。そして claude mcp add では Claude 側のオプションとサーバー起動コマンドを -- で区切る。区切らないと、サーバー側の --port のようなフラグを Claude Code が自分のオプションとして解釈しようとする。

クライアントを介さずサーバー単体を叩くなら MCP Inspector がある。公式によると npx @modelcontextprotocol/inspector --cli <コマンド> --method tools/list でツール一覧だけ取って終了でき、Node 22.19.0 以上が必要とされている。

接続はしたのに使えない時に見る場所

ステータスは緑なのにツールが0個、というケースは別枠だ。公式はこれを「起動には成功しているがツール一覧を返していない」状態と説明し、まず /mcp のメニューから Reconnect を選び、それでも0のままなら claude --debug=mcp で起動して ~/.claude/debug/<session-id>.txt のサーバー stderr を読む、という順番を示している。起動が遅いだけのこともあり、起動タイムアウトは MCP_TIMEOUT で調整できる。

リモートサーバーの認証については、公式は「サーバーが 401 Unauthorized または 403 Forbidden を返したとき、Claude Code はそのサーバーを要認証としてマークする」と書いている。403だから権限問題と決め打ちせず、まずサインインし直す価値がある。v2.1.186 以降は claude mcp login <name> でシェルから直接OAuthフローを実行できる。ただし自分で headers.Authorization を設定していてサーバーがそれを拒否した場合は、OAuthにフォールバックせず接続失敗として報告される、とも明記されている。要認証ではなく ✘ Failed to connect で出るので、トークンの有効性を確認するか、ヘッダーを外してOAuthに任せる。

Claude Desktop で見えない場合は、そもそも見る場所が違う。公式ドキュメントによると設定は macOS が ~/Library/Application Support/Claude/claude_desktop_config.json、Windows が %APPDATA%\Claude\claude_desktop_config.json。ログは macOS が ~/Library/Logs/Claude、Windows が %APPDATA%\Claude\logs で、mcp.log に接続失敗、mcp-server-<サーバー名>.log に各サーバーの stderr が入る。こうした「AIに外部ツールを渡す」構成の位置づけ自体はAIエージェントとはとClaude Codeとはで扱っている。

この手順で切り分けられないこと

正直に書くと、この記事の再現ログは Claude Code 2.1.246 / macOS / Node v25.9.0 という1環境の結果で、他のバージョンやOSで同じ文言が出る保証はない。公式ドキュメント自体が「v2.1.196 から」「v2.1.219 以前は」といったバージョン境界を多数併記しており、表示文字列もリトライ回数も変わりうる。手元のバージョンは claude --version で確認したうえで読んでほしい。

また -32000: Connection closed は「プロセスが接続を確立せずに終了した」以上を教えてくれない。今回はダミースクリプトで意図的に起こしたが、実際の原因が依存パッケージの欠落なのか、権限なのか、サーバー側の不具合なのかは、この文字列だけでは決まらない。そこから先はコマンドの単体実行とサーバーのログに移るしかない。Cursor や VS Code など他のMCPクライアントの挙動、および個別のサードパーティ製サーバー固有の不具合は今回検証していない。設定ファイル名やキーの扱いはクライアントごとに違うため、この記事の表をそのまま流用することはできない。

出典と但し書き

• Connect Claude Code to tools via MCP（Claude Code公式ドキュメント）
• Debug your configuration（Claude Code公式ドキュメント）
• Troubleshooting（Claude Code公式ドキュメント）
• Connect to local MCP servers（Model Context Protocol 公式ドキュメント）
• Debugging（Model Context Protocol 公式ドキュメント）
• MCP Inspector（Model Context Protocol 公式ドキュメント）

公式ドキュメントの記述は2026年8月27日に上記URLを取得して確認した。再現ログは同日、Claude Code 2.1.246（macOS 24.1.0 / Node v25.9.0）で、CLAUDE_CONFIG_DIR を使い捨てディレクトリに向けた隔離環境で取得したもの。MCPの仕様もClaude Codeの実装も更新が速く、ステータス文言やタイムアウトの既定値は変わる可能性がある。本記事は特定の環境での復旧を保証するものではない。