Claude Code の MCP が動かない・ツールが出ないとき——原因の切り分け手順

Claude Code に MCP(AIを自分のデータやツールにつなぐ仕組み)を設定したのに、ツールがまったく出てこない——。原因は大きく2種類あります。設定そのものが間違っている場合と、設定は正しいのに別の理由で出ていない場合です。この記事では、まず claude mcp list で接続状態を見て切り分ける手順を示し、そのうえで多くの解説記事が触れない後者(権限承認・接続タイミング・遅延ロード)を、私たちが実際にハマった例つきで解説します。

まず最初にやること: 接続状態を見る

いきなり設定ファイルをいじる前に、いまサーバーが「接続できているか」だけを先に確認します。ここを飛ばすと、正常な設定を壊してしまいがちです。

Claude Code なら claude mcp list で、登録されているサーバーと接続状態(connected か failed か)が一覧で出ます。詳しいコマンドやログの出し方は公式ドキュメントが正確です。

この4段の切り分けだけで、原因が「設定ファイル」なのか「それ以外」なのかがはっきりします。以下、上から順に見ていきます。

パターン1: 接続に失敗している(設定側の問題)

claude mcp list で failed と出るなら、サーバーが起動できていません。ここは他の解説記事とも共通する、いわば定番の落とし穴です。

ポイントは、エラーの正体を推測で埋めないことです。デバッグログを出せば「コマンドが見つからない」のか「起動して即終了した」のかまで分かります。ログの出し方は前掲の公式ドキュメントに従うのが確実です。

パターン2: 接続済みなのにツールが出ない(設定以外の問題)

ここからが本題です。claude mcp list は connected なのにツールが呼べない——このとき設定ファイルをいくらいじっても直りません。私たちが実際に時間を溶かしたのは、次の3つでした。

(1) 権限で許可されていない

Claude Code はツールを呼ぶ前に許可(承認)を求めます。許可リスト(allowedTools)に入っていないツールは、存在していても実行に進めません。

やっかいなのは部分的な許可です。あるサーバーの「クリックは許可、ダイアログ操作は不許可」のように一部だけ許すと、途中まで動いて特定の操作でだけ止まります。私たちはブラウザ自動化の MCP でこれを踏み、確認ダイアログの処理が不許可だったせいで操作全体が固まりました。設定ではなく許可の粒度が原因だった、という典型例です。

(2) まだ「接続中」なだけ

起動直後は、サーバーがまだ接続の途中で「ツールはもうすぐ出ます」という状態のことがあります。ここで焦って設定を疑い始めると、正しい設定を壊してしまいます。

Claude Code 側も「接続中のサーバーがあり、そのツールは間もなく現れる」と知らせてくれることがあります。数秒待ってから、もう一度ツール一覧を確認するだけで解決することは少なくありません。

(3) 遅延ロードで名前だけ出ている

近年の Claude Code には、ツールを最初から全部読み込まず、必要になったときに読み込む省メモリの仕組み(遅延ロード)があります。このとき、ツールは「名前は見えるが中身(呼び出しに必要な定義)は未ロード」という状態になります。

この状態でツールをいきなり呼ぶと、定義が無いため検証エラーで弾かれます。名前が見えている＝すぐ呼べる、ではないのです。専用の検索ツールでいったん読み込んでから呼ぶ必要があります。「設定は合っているのにエラーになる」ときは、これを疑うと早いです。

パターン3: 環境要因(設定もツールも問題ない)

設定も権限も正しく、ツールも読み込めているのに不安定——このときは実行環境そのものを疑います。

私たちは、あるブラウザ操作系の MCP で、接続先(デバッグ用ポート)は正常に応答しているのに、サーバーの初期化だけが繰り返しタイムアウトする現象に遭いました。同じ日に2回続いたので、設定ではなく環境(ポートの取り合い・プロセスの残骸)が原因と判断し、環境をリセットして復旧しました。

こうした自動実行の設計そのものは「Claude Code を定期実行して寝ている間に開発を進める」に、MCP という仕組み自体は「MCPとは何か——AIを自分のデータ・アプリに繋ぐ仕組み」にまとめています。

よくある質問

Q. claude mcp list が connected なのにツールが呼べません。設定のどこが悪いのですか?

設定が悪いとは限りません。connected の時点で「つながってはいる」ので、次に疑うのは権限(許可されているか)・接続タイミング(まだ読み込み中でないか)・遅延ロード(名前だけで未ロードでないか)の3つです。この記事のパターン2を上から確認してください。

Q. 設定ファイルを何度直してもツールが出ません。

claude mcp list が failed なら設定側、connected ならパターン2以降です。まず接続状態を確認せずに設定を書き換え続けると、正しい設定まで壊してしまいます。切り分けの順番を守るのが近道です。

Q. 手元では動くのに、スケジュール実行(cron など)だと MCP が動きません。

ログイン操作で認証するタイプのサーバーは、無人実行では認証情報が無く現れないことがあります。実行環境に認証情報を渡せるか、そのサーバーを自動実行では使わない設計にするかを検討してください。

Q. MCP そのものがよく分かりません。

まず仕組みの理解からで大丈夫です。「MCPとは何か——AIを自分のデータ・アプリに繋ぐ仕組み」で、MCP が何をつなぐものかを平易に解説しています。

まとめ

「MCP が動かない」は、設定ミスと設定は正しいのに出ないを分けて考えると一気に切り分けが速くなります。まず claude mcp list で接続状態を見て、failed なら設定(JSON・パス・コマンド)、connected なら権限・接続タイミング・遅延ロード、それも問題なければ環境要因——この順で当たれば、推測で設定をいじり回して時間を溶かすことはなくなります。