MCP tool not foundエラー — --permission-prompt-toolの原因と対処

このTipsでできること

--permission-prompt-tool を指定した非対話(headless)実行が、最初に承認が必要な操作にぶつかった時点で次のエラーとともに終了することがあります。

Error: MCP tool mcp__permissions__approve (passed via --permission-prompt-tool) not found. Available MCP tools: none

この記事では、このエラーが指す2つの原因、-p実行で何も答えが返らないまま終わる理由、そして--permission-prompt-toolまわりの紛らわしい別エラーとの見分け方をまとめます。

エラーが指す2つの原因

--permission-prompt-tool に渡したツールが、実行が最初に権限確認を必要とした時点で、接続済みのMCPツールの中に見つからないと発生します。原因は次の2つのどちらかです。

1. そのツールを提供するはずのMCPサーバーが、権限確認の時点でまだ接続を終えていない
2. サーバーは接続しているが、指定した名前のツールをそもそも公開していない

メッセージ末尾の Available MCP tools: の後ろには、待ち合わせが終わった時点で接続済みだったMCPツールの一覧が並びます。上のサンプルのように none になっている場合は1番目、他のツール名が並んでいるのに目的のツールだけ無い場合は2番目を疑います。この一覧は待ち合わせが終わった瞬間のスナップショットなので、その後に接続が完了したサーバーがあっても表示には反映されません。

権限確認の前にどれだけ待つか

Claude Codeは、非対話実行が最初の権限確認にぶつかる前に、--permission-prompt-tool が指すサーバーの接続をMCP_TIMEOUTが決める上限(既定30秒)まで待ちます。サーバーの起動にそれ以上かかる場合、接続が終わる前に権限確認のタイミングが来てしまい、このエラーになります。

この待ち合わせ自体はv2.1.206で追加されたものです。前後の挙動を比較すると次のようになります。

v2.1.206より前は、サーバー自体は正常でも起動が遅いだけでこのエラーになるケースが珍しくありませんでした。現在のバージョンでこのエラーに当たった場合は、サーバーの起動が30秒の既定枠を超えて遅いか、名前の不一致かのどちらかに絞り込めます。MCP_TIMEOUTと、混同しやすいMCP_TOOL_TIMEOUTとの役割の違いはMCP_TIMEOUTとMCP_TOOL_TIMEOUTの違いで扱っています。

直し方

まず対象サーバーが実際に接続しているかを確認します。

claude mcp list

このコマンドを、--permission-prompt-tool を指定するのと同じディレクトリで実行し、目的のサーバーが接続済みと表示されるか確認します。接続していない、または表示が遅い場合はサーバー側の起動を疑います。サーバーの追加方法やスコープの選び方から見直したい場合はClaude Code MCP設定ガイドを参照してください。

次にツール名の形式を確認します。MCPのツール名は mcp__<サーバー名>__<ツール名> という名前空間で公開されます。--permission-prompt-tool に渡す名前がこの形式と一致しているか、サーバー名やツール名のスペルミスが無いかを見直してください。名前空間の書き方の全体像はClaude Code MCP権限ルールにまとめています。

サーバーの起動そのものに30秒以上かかる構成であれば、MCP_TIMEOUT を大きくしてから再実行します。依存パッケージのダウンロードやコンテナ起動を伴うサーバーでは、この既定30秒に収まらないことが珍しくありません。

MCP_TIMEOUT=60000 claude -p "タスクの内容" --permission-prompt-tool mcp__permissions__approve

--resumeするときは毎回渡し直す必要がある

--permission-prompt-tool はセッションを再開するたびに指定し直す必要があります。Claude Codeはこのフラグをセッションの状態として保存せず、再開時のコマンドラインに自動で引き継ぎません。

これが実際に効いてくる場面がclaude -p --resumeやclaude -p --continueでのplanモード再開です。非対話実行が保留中のplanをplanモードのまま再開するには、次の4条件すべてを満たす必要があります。

1. --permission-prompt-toolを渡している(承認をMCPツールに提示できるようにするため)
2. --permission-modeや--dangerously-skip-permissionsを渡していない
3. --fork-sessionを渡していない
4. channels経由の起動ではない

1つ目の条件からも分かるとおり、--permission-prompt-toolはplanの承認をどこかに提示するための仕組みとして使われる場面があります。前回の実行でこのフラグを渡していたからといって、再開時に省略すると条件を満たせなくなり、意図しないモードで再開されたり、承認が必要な場面で今回のエラーに当たったりします。

もう1つ知っておきたいのが、--permission-prompt-toolを含む一部の起動フラグは、対話セッション内で/tuiによるレンダラー切り替えを行うときのプロセス再起動にも引き継がれません。このフラグを付けて起動したセッションでは、/tui fullscreenのような切り替えコマンドが「Cannot switch renderers in this session」というメッセージとともに拒否されることがあります。直接の原因は別のエラーですが、根っこにあるのは同じ「このフラグは再起動をまたいで自動的には引き継がれない」という性質です。

エラー後、非対話実行はどう終わるか

-p を使った非対話実行では、このエラーが出ても実行全体が異常終了で止まるとは限りません。最初に承認が必要な操作にぶつかった時点で終了コード1を返し、それ以上の処理は行われません。ここが見落としやすい点で、リクエスト自体は送られているのに、答えが1つも返らないまま終わることになります。パイプラインやCIでこのコマンドを使っている場合、終了コードだけを見ていると「何も起きなかった」ように見えてしまうため、標準エラー出力のメッセージも合わせて確認する運用にしておくと気づきやすくなります。

似た別エラーと混同しない

--permission-prompt-tool まわりにはもう1つ、名前の似た別のエラーがあります。MCPサーバー側のツールが _meta["anthropic/requiresUserInteraction"] を true に設定して「必ず人の承認を経由させる」と宣言している場合、--permission-prompt-tool 経由での allow 判定はそのまま通らず、次のメッセージとともに拒否に変換されます。

MCP tool requires user interaction; not supported via --permission-prompt-tool

これは「ツールが見つからない」のではなく、「ツールは見つかったが、この起動経路では承認を許可しない設計になっている」という別の状況です。--permission-prompt-tool はプロンプトを人に渡す仕組みそのものを持たないため、こうしたツールを非対話実行の中で承認する手段はありません。人の判断を必ず介在させたい場合は、Agent SDKのcanUseToolコールバックを使う実装に切り替えると、呼び出しをアプリケーション側でユーザーに提示できます。目的のツールがこの制約付きツールに該当するかどうかは、サーバー側のドキュメントか実装で確認してください。この指定はMCPサーバー側のtools/list応答に含まれるメタ情報なので、クライアント側の設定を変えても外せません。自分でMCPサーバーを実装していて、あるツールだけは必ず人の承認を経由させたい場合に使う仕組みです。

CI環境では組織のMCP制御も疑う

CI・パイプラインのような無人環境で--permission-prompt-toolを使っている場合、claude mcp listで確認しても手元の対話セッションでは接続できているのに、CI側の実行だけで「MCP tool not found」になることがあります。この場合、サーバーの起動遅延やツール名の不一致に加えて、組織が管理するMCPポリシーによってその環境からの接続だけがブロックされていないかも確認してください。管理MCP構成の対象になっている環境では、許可リストに無いサーバーは接続自体が成立せず、Available MCP tools:の一覧から漏れます。組織のMCP制御の仕組み全体はMCPセキュリティガイドにまとめています。

よくある質問

Available MCP toolsがnoneと表示されるのに、少し待つと接続します

MCP_TIMEOUT の既定枠(30秒)以内にサーバーの起動が終わっていないケースです。claude mcp list で接続完了までの実際の時間を確認し、それに合わせて MCP_TIMEOUT を大きくしてください。

対話セッションでは同じサーバーで問題なく動いています

対話セッションには「権限確認の前に接続を待つ」という制約自体がありません。起動が遅くても、接続でき次第そのツールが使えるようになるだけで、エラーにはなりません。この待ち合わせと終了条件は非対話(-p)実行かつ--permission-prompt-toolを指定した場合に固有の挙動です。

ツール名は合っているはずなのに見つからないと言われます

mcp__<サーバー名>__<ツール名> の大文字小文字やハイフン・アンダースコアの違いまで含めて、claude mcp list で実際に公開されているツール名と1文字ずつ突き合わせてください。サーバー側の実装変更でツール名自体が変わっている可能性もあります。

--resumeするたびに毎回フラグを付け直すのは面倒です。省略できませんか

現状、--permission-prompt-toolはセッションの起動フラグとして毎回明示する必要があり、前回の起動内容から自動で引き継がれる仕組みはありません。頻繁に再開するワークフローであれば、起動コマンドをスクリプトやエイリアスにまとめておき、--resumeや--continueのたびに同じフラグ一式を渡す運用にしておくと取りこぼしを防げます。

まとめ

「MCP tool not found」は、--permission-prompt-tool に渡したツールが、権限確認の時点で接続済みのMCPツールに含まれていないときに出ます。v2.1.206以降はMCP_TIMEOUT(既定30秒)まで接続を待ってから判定するため、現在のバージョンで当たった場合はサーバーの起動遅延かツール名の不一致のどちらかに絞り込めます。エラー後は終了コード1で実行が止まり、答えが返らないまま終わる点に注意してください。名前が似た「requires user interaction」エラーは原因も対処もまったく別物なので、メッセージの文言を必ず確認してから対処に進んでください。--permission-prompt-toolはセッション再開時に自動で引き継がれないフラグでもあるため、--resumeや--continueを使う運用では、毎回のコマンドに含め忘れていないかも合わせて見直す価値があります。