MCP を設定したのに動かない・無視される(エラーも出ない)時の原因と直し方

.mcp.json にサーバーを書いた。claude mcp add もした。なのに、そのツールが会話に出てこない。Claude も使ってくれない。そしてエラーも出ない——一番もやもやする詰まり方です。このページは、何が起きているかを /mcp で確かめてから、原因を起こりやすい順に切り分ける手順を、公式の MCP ドキュメントを出典に整理します。

まず `/mcp` を見る(「沈黙」の大半はここで声が出ている)

「エラーも出ない」と感じても、状態は /mcp パネル(または端末で claude mcp list)に出ていることがほとんどです。会話を始める前に、まずここを見てください。各サーバーの横に状態が出ます。

表示	意味
名前 + ツール数	接続済み。ツール数が出ていれば使える状態。
`⏸ Pending approval`(承認待ち)	プロジェクトの `.mcp.json` のサーバーが、まだ承認されていない。これが「設定したのに無視される」の最大の原因。
`⏸ Pending auth`(認証待ち)	HTTP のサーバーで OAuth のログインがまだ。`/mcp` から認証する。
`✗ Rejected`(拒否)	以前あなたが承認を拒否した。あとで戻せる(後述)。
`failed`(失敗)	起動・接続に失敗。多くは PATH やコマンドの問題(後述)。

正直な限界: 公式ドキュメントの範囲では、/mcp は failed とは出しても「なぜ失敗したか」(コマンドが見つからない/タイムアウト/401 など)の詳細までは出しません。ここは切り分けで埋めます。

最大の原因: プロジェクトのサーバーは「承認」しないと黙って動かない

設定は正しいのに、何も起きない

公式は明記しています——「セキュリティ上の理由から、Claude Code は .mcp.json のプロジェクトのサーバーを使う前に承認を求める」。つまり、チームの誰かが .mcp.json をコミットし、あなたが git pull しても、あなたが承認するまでそのサーバーは不活性のままです。承認の前は claude mcp list で ⏸ Pending approval と出るだけで、赤いエラーは出ません。これが「設定したのに無視される」の正体であることが非常に多いです。

直し方

claude を対話で起動すると、承認のプロンプトが出ます。承認すると有効になります。
間違って拒否してしまった(✗ Rejected)場合は、承認の選択をやり直せます:
```
claude mcp reset-project-choices
```

次に多い: スコープの取り違え(別の場所に登録されている)

MCP サーバーには3つのスコープがあり、どこに書いたかで「どのプロジェクトで読まれるか」が変わります。期待した場所に出ていないなら、スコープが原因のことがあります。

スコープ	保存先	読まれる範囲
Local(ローカル)	`~/.claude.json` のそのプロジェクトの項目	今のプロジェクトだけ・自分だけ
Project(プロジェクト)	プロジェクト直下の `.mcp.json`(git で共有)	今のプロジェクト・チーム共有(要承認)
User(ユーザー)	`~/.claude.json` の全体の項目	全プロジェクト・自分だけ

優先順位は Local > Project > User(さらにプラグイン提供のもの、最後に claude.ai のコネクタ)。同じ名前のサーバーを別スコープに書いていると、優先順位の高い方の定義だけが効きます。claude mcp get <名前> でどの定義が効いているかを確認できます。

「失敗」の中身: 静かに落ちる/はっきり落ちるの切り分け

失敗の出方は原因で違います。どれが静かに(沈黙)落ち、どれが声を出す(明示/状態表示)かを知っておくと早いです。

原因	出方
stdio のコマンドが PATH に無い/起動できない	静か:接続が pending のあと `failed` に。stdio は自動で再接続しません。
サーバーは起動するがツールを1つも公開しない	/mcp に出る:「tools の能力はあるが公開ゼロ」と表示。
HTTP のサーバーで認証(401/403)が未完	状態表示:`⏸ Pending auth`。OAuth を促される。
`.mcp.json` の JSON の文法エラー	はっきり失敗:設定の読み込みでエラー。
必須の環境変数が未設定で既定値も無い	はっきり失敗:公式いわく「設定の解析に失敗する」。
起動に時間がかかりタイムアウト	静かに `failed`:`MCP_TIMEOUT` で延ばせる(下記)。

HTTP/SSE のサーバーは指数バックオフで最大5回まで自動再接続し、超えると failed になります。認証エラーは再試行されません(設定の修正が必要)。

stdio が `failed` の時: まず単体で動くか確かめる

.mcp.json の command を、同じ環境の素の端末でそのまま実行してみる。command not found なら PATH の問題です。npx や uvx やフルパスで起動するか確認します。
Claude Code が起動するサーバーの作業ディレクトリやログインシェルは、あなたの端末と違うことがあります。絶対パスや、確実に解決できるコマンド名を使うと安定します。
起動が遅いサーバーは、既定のタイムアウトで切られている可能性があります。延ばして試す:
```
MCP_TIMEOUT=15000 claude
```

環境変数の展開でつまずく時

.mcp.json では ${VAR} と ${VAR:-既定値} が使えます(command / args / env / url / headers の中で展開)。注意点:

必須の変数が未設定で既定値も無いと、設定全体の解析に失敗します(静かではなく、はっきり失敗)。鍵などは ${API_KEY} でなく、未設定時の挙動を意識して書く。
プロジェクト/ローカルのスコープで ${CLAUDE_PROJECT_DIR} を使うときは、既定値つきの ${CLAUDE_PROJECT_DIR:-.} の形が要ります。

切り分けの順番(まとめ)

/mcp または claude mcp list で状態を見る。
⏸ Pending approval なら承認する(最頻の原因)。✗ Rejected なら claude mcp reset-project-choices。
claude mcp get <名前> で、効いている定義とスコープを確認する。期待と違えば書く場所を直す。
failed なら、command を素の端末で実行して PATH を確認。必要なら MCP_TIMEOUT を延ばす。
⏸ Pending auth なら /mcp から OAuth を完了する。
「ツール公開ゼロ」と出るなら、サーバー側の問題。サーバーのバージョンや起動引数を見る。
JSON の文法と、必須の環境変数(既定値の有無)を確認する。

正直な限界(公式ドキュメントの範囲): 専用の MCP デバッグのフラグや、ログの保存先は公式には明記されていません。上の「素の端末で command を実行」「MCP_TIMEOUT を延ばす」「/mcp の状態表示」が、現状で確実な切り分けの手立てです。詳細なエラー理由が /mcp に出ないのは改善の余地のある点です。

Claude Code の事故を予防する

npx cc-safe-setup

破壊的な操作・秘密の漏洩・費用の暴走を、実行の前に止める無料の hook。MCP の設定の問題そのものは直しませんが、外部のサーバーに権限を渡す運用の安全を支えます。

GitHub · npm

本ページは公開された公式の MCP ドキュメントに基づきます。挙動は版で変わりうるので、実際の設定の前に最新を確認してください。cc-safe-setup は Anthropic とは無関係の独立したオープンソースです。

さらに詳しく: 事故防止の実践ガイド(Zenn) · 全ツール