AIツール

MCP ツール呼び出しの失敗をトラブルシューティングする方法: チュートリアル、トラブルシューティング、および FAQ

サーバーの起動、stdio/HTTP 接続、JSON 構成、環境変数、権限、スキーマ、タイムアウト、過剰な戻りデータ、クライアントの適応問題をカバーする、MCP ツール呼び出し失敗のトラブルシューティング方法を整理します。

MCP ツールが接続されると、AI エージェントはファイルの読み取り、データベースのチェック、ドキュメントの検索、ブラウザの起動、内部システムへのアクセスが可能になります。ただし、実際の構成では、ツールがインストール済みとして表示され、モデルにもツール名が表示されるが、呼び出すとすぐに失敗したり、単にツールのリストに表示されなかったりするという、厄介な状況に遭遇することがよくあります。

MCP の問題をトラブルシューティングするときは、最初からモデルを疑ってはいけません。ほとんどの障害は、より基本的なリンクで発生します。サーバーが起動していない、コマンド パスが間違っている、環境変数が渡されない、アクセス許可が不十分、プロトコル モードが一致しない、ツール スキーマが正しく書かれていない、返されたデータが大きすぎるなどです。レイヤーごとにチェックすると、通常はすぐに見つけることができます。

まず MCP 通話リンクを見てみましょう

MCP ツールの呼び出しは通常、次の手順を実行します。

  1. クライアントは MCP 構成を読み取ります。
  2. クライアントが MCP サーバーを起動するか、MCP サーバーに接続します。
  3. サーバー公開ツールのリスト。
  4. モデルのツールを選択します。
  5. クライアントはパラメータをサーバーに渡します。
  6. サーバーはツールを実行し、結果を返します。
  7. クライアントは結果をモデル コンテキストに戻します。

どの層でも障害が発生すると、最終的には「ツール呼び出しの障害」として現れる可能性があります。したがって、トラブルシューティングを行うときは、最終的なエラー レポートだけに注目するのではなく、まずどの層で障害が発生したかを判断する必要があります。

最小小切手注文

次の順序で確認することをお勧めします。

  1. MCP サーバーを個別に起動できますか?
  2. クライアント設定のコマンド、パラメータ、パスは正しいですか?
  3. 環境変数が MCP サーバーに渡されるかどうか。
  4. ツールがクライアント ツール リストに表示されるかどうか。
  5. ツールのパラメータがスキーマに準拠しているかどうか。
  6. サーバーの実行時に権限や依存関係が不足していませんか?
  7. 返されたコンテンツが大きすぎるか、または間違った形式であるかどうか。
  8. クライアントとサーバーのプロトコル モードが一致しているかどうか。

最初のステップが失敗した場合は、プロンプトの単語を変更し続けないでください。まずサーバーを起動します。

チュートリアル: 最初に MCP サーバーを個別に起動します

MCP サーバーが Node.js コマンドであると仮定して、ターミナルで直接実行します。

1

npx -y example-mcp-server

ローカル スクリプトの場合:

1

node ./server.js

Python プロジェクトでは、まず依存関係とエントリを確認できます。

1

python -m your_mcp_server

このステップでは主に、不足しているパッケージ、間違ったパス、間違った権限、占有されているポート、または不足している API キーがないかどうかをチェックします。サーバーを独立して起動できる場合にのみ、クライアントはサーバーを通常どおり呼び出すことができます。

チュートリアル: クライアント構成を確認する

MCP 設定には通常、command、args、env などのフィールドが含まれます。一般的な構造は次のようになります。

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11

{
  "mcpServers": {
    "docs": {
      "command": "npx",
      "args": ["-y", "example-docs-mcp"],
      "env": {
        "DOCS_API_KEY": "your-api-key"
      }
    }
  }
}

調査の焦点:

  • 現在の環境で command が見つかるかどうか。
  • args 文字列の行全体として書き込むのではなく、配列に分割するかどうか。
  • Windows パスが正しくエスケープされているかどうか。
  • API キーがサーバーによって読み取れる環境変数に配置されているかどうか。
  • 構成ファイルの変更後にクライアントが再起動されるかどうか。

多くの問題は、構成が変更されただけで、クライアントがリロードされていないことです。

一般的なエラー: サーバーの起動に失敗しました

典型的なパフォーマンス:

1
2
3
4

MCP server failed to start
spawn ENOENT
command not found
No such file or directory

よくある理由:

  • node、python、npx が PATH にありません。
  • コマンドの記述が間違っています。
  • ローカルスクリプトのパスが正しく記述されていません。
  • Windows パスにスペースが含まれていますが、正しく処理されません。
  • 現在の作業ディレクトリが思っているものと異なります。

トラブルシューティング方法:

1
2
3

which node
which npx
which python

Windows PowerShell:

1
2
3

Get-Command node
Get-Command npx
Get-Command python

クライアントでコマンドが見つからない場合は、絶対パスに変更するか、クライアントの起動時に正しい PATH が継承されていることを確認できます。

一般的なエラー: ツール リストが空です

サーバーは起動しているように見えますが、クライアントにはツールがありません。通常、初期化フェーズが失敗しました。

考えられる理由:

  • サーバーは非プロトコル ログを出力し、stdio 通信を妨害します。
  • サーバーは初期化中にエラーを報告しましたが、飲み込まれました。
  • 間違った転送モードが使用されています。 ・ツール登録ロジックは実行されません。
  • クライアントのバージョンは、サーバーの一部の機能をサポートしていません。

stdio MCP サーバーの場合は、特別な注意を払う必要があります。通常のログを stdout に直接書き込まないでください。通常、stdout はプロトコル メッセージ用に予約され、デバッグ ログは stderr またはファイルに書き込まれる必要があります。

一般的なエラー: JSON 構成フォーマットのエラー

典型的なパフォーマンス:

1
2
3

Unexpected token
invalid JSON
failed to parse config

よくある質問：

・JSONでコメントが入っています。

  • 最後に余分なカンマがあります。
  • Windows パスのバックスラッシュはエスケープされません。
  • 引用符には中国語の全角記号が使用されます。
  • コマンドパラメータをシェル文字列全体として記述します。

Windows パスは次のように記述することをお勧めします。

1

"C:\\Users\\name\\mcp\\server.js"

または、スラッシュを直接使用します。

1

"C:/Users/name/mcp/server.js"

書かないでください:

1

"C:\Users\name\mcp\server.js"

この書き方は、JSON のエスケープ文字と見なされやすいです。

一般的なエラー: API キーが渡されませんでした

多くの MCP サーバーは外部サービスにアクセスする必要があります。ターミナルで実行できるからといって、クライアントの起動時に同じ環境変数を読み取れるわけではありません。

典型的なパフォーマンス:

1
2
3
4

missing API key
unauthorized
401
permission denied

トラブルシューティング方法:

  1. MCP 構成の env に必要な変数を明示的に書き込みます。
  2. 変数名で大文字と小文字が区別されていることを確認します。
  3. 再度テストする前に、クライアントが再起動されていることを確認します。
  4. 通常のログにキーを出力しないでください。

シェルで変数を一時的に設定すると、GUI クライアントがその変数を継承しない可能性があります。最も安定した方法は、MCP サーバーの構成環境変数を書き込むか、システムレベルの安全なキー管理方法を使用することです。

よくあるエラー: 権限が不十分です

ツールを呼び出すことはできますが、実行は失敗します。一般的な理由は、権限が不十分であることです。

例えば：

  • ファイル システム ツールがターゲット ディレクトリにアクセスできません。
  • データベース アカウントにはクエリ権限がありません。
  • ブラウザ自動化ツールに使用できるプロファイルがありません。
  • Git ツールは現在のリポジトリに書き込むことができません。
  • 企業ネットワークは内部 API へのアクセスをブロックします。

調査中は、まず次の 2 つの質問をします。

  • MCP サーバー プロセスはどのユーザーとして実行されますか?
  • 作業ディレクトリと権限の境界は何ですか?

自分の端末の権限だけを見てはいけません。クライアントによって起動されたサーバーは、異なる環境で実行される場合があります。

一般的なエラー: ツールのパラメーターがスキーマに準拠していません

モデルがツールを認識できるにもかかわらず、呼び出し時のパラメーターが間違っている場合、通常はスキーマが実際の実装と矛盾していることが原因です。

典型的なパフォーマンス:

1
2
3
4

invalid arguments
missing required field
expected string, got object
schema validation failed

よくある理由:

  • ツール定義には path が必要で、モデルは file_path に合格します。
  • スキーマは文字列として記述され、実装では配列として処理されます。
  • 必須フィールドが多すぎるため、モデルはフィールドに入力する方法がわかりません。
  • パラメータの説明が不明瞭なため、モデルが間違った形式で送信されます。

改善方法:

  • ツールパラメータはできるだけ少なくしてください。
  • フィールド名は直感的である必要があります。
  • 説明には単位、形式、例が明確に記載されています。
  • オプションのパラメータに適切なデフォルト値を設定します。

優れたツール スキーマにより、モデルの誤送信が困難になります。

よくあるエラー: 通話タイムアウト

典型的なパフォーマンス:

1
2
3

timeout
request timed out
tool call exceeded limit

よくある理由:

  • ツールが長いネットワーク リクエストを実行しました。
  • データベースクエリに制限はありません。
  • Web スクレイピングが停止します。
  • 大きなファイルの読み込みやベクトルの取得が遅すぎる。
  • サーバー内部にはタイムアウト制御がありません。

加工方法：

  • limit をクエリに追加します。
  • ネットワークリクエストにタイムアウトを追加します。
  • 最初に概要に戻り、必要に応じて詳細を展開します。
  • 長いタスクを 2 つのステップに分割します。
  • 失敗したリクエストに対して明確なエラーが返されるようにします。

MCP ツールが必ずしも優れているとは限りません。エージェントにとっては、予測可能ですぐに失敗するツールの方が信頼性が高くなります。

FAQ: 返されるデータが大きすぎます

MCP ツールが返すコンテンツが多すぎると、コンテキストが肥大化し、モデルが処理を続行できなくなる可能性があります。

ハイリスクリターン:

  • Web ページの本文全体。
  • 完全なデータベーステーブル。
  • ログの大部分。
  • 数百件の検索結果。
  • 完全なディレクトリ ツリーとすべてのファイルの内容。

推奨される戻り構造:

 1
 2
 3
 4
 5
 6
 7
 8
 9
10

{
  "summary": "找到 5 条相关结果",
  "items": [
    {
      "title": "result title",
      "why_relevant": "matched auth config",
      "source": "path-or-url"
    }
  ]
}

最初に概要とインデックスを返し、特定の詳細の読み取りを続けるかどうかをモデルに決定させます。

stdio モードと HTTP モードを混合しないでください

MCP サーバーには、stdio を使用するものと、HTTP または SSE を使用するものがあります。クライアント設定は、サーバーがサポートする送信モードと一致している必要があります。

サーバーが標準入出力の場合、通常は command および args を構成します。 HTTP の場合は、URL を設定する必要があります。 HTTP サーバーを stdio コマンドとして起動したり、HTTP アドレスとして stdio サーバーにアクセスしたりすると失敗します。

トラブルシューティングを行う場合は、まずサーバーのドキュメントで送信モードを確認してください。

  • stdio: ローカル プロセス。標準入出力を通じて通信します。
  • HTTP/SSE: リモートまたはローカル サービス。URL 経由で通信します。

他の人の構成スニペットを単にコピーするのではなく、現在のサーバーの実行方法に合わせて調整してください。

Windows でのパスとシェルの問題

Windows ユーザーにはさらに一般的な落とし穴があります。

  • パスにスペースが含まれています。
  • PowerShell と cmd では引用符のルールが異なります。
  • npx は、実際には .cmd ラッパー コマンドです。
  • ノードまたは Python がユーザー ディレクトリにインストールされており、GUI クライアントで見つけることができません。
  • JSON ではバックスラッシュがエスケープされます。

トラブルシューティングを行うときは、単純なパスでのテストを優先します。たとえば、サーバーを次の場所に置きます。

1

C:/mcp/server.js

単純なパスは実行できるが、元のパスは実行できない場合は、パスのエスケープまたは権限の問題である可能性があります。

クライアントのバージョンとサーバーのバージョンが一致しません

MCP エコシステムは非常に迅速に更新されます。クライアント、SDK、およびサーバー テンプレートのバージョンに一貫性がない場合、ツール リストの異常、パラメーター形式の変更、または互換性のない機能ステートメントが発生する可能性があります。

トラブルシューティング方法:

  • クライアントを新しいバージョンにアップグレードします。
  • サーバーで使用されている MCP SDK のバージョンを確認します。
  • サーバーの README 構成例を読みます。
  • 最初に公式の最小限のサンプルを実行してから、カスタム サーバーに接続します。

公式サンプルは実行できるが、カスタム サーバーは実行できない場合、問題はカスタム実装または構成にある可能性が高くなります。

推奨されるトラブルシューティング テンプレート

MCP ツールの呼び出しに失敗した場合は、次のテンプレートに従って情報を整理できます。

 1
 2
 3
 4
 5
 6
 7
 8
 9
10

MCP server 名称：
传输模式：stdio / HTTP / SSE
客户端：
操作系统：
启动命令：
是否能单独启动：
是否出现在工具列表：
失败工具名：
错误信息：
最近改动：

この情報があれば、AI エージェントや同僚にトラブルシューティングの協力を依頼する方が、単に「ツールが壊れている」と言うよりもはるかに効率的になります。

よくある質問

MCP ツールが表示されません。機種の問題でしょうか？

通常はそうではありません。表示されないツールは、ほとんどの場合、構成の読み取り、サーバーの起動、初期化、またはツールの登録の段階で発生します。まずクライアント ログを確認し、サーバーが正常に起動したかどうかを確認します。

ターミナルでは実行できるのに、クライアントでは実行できないのはなぜですか?

クライアント起動時のPATH、環境変数、作業ディレクトリ、ユーザー権限は端末とは異なる場合があります。コマンドを絶対パスに変更し、MCP 構成で環境変数を明示的に渡すと、通常は問題の一部を解決できます。

MCP サーバーはログを出力できますか?

はい、ただし、通常のログを stdio モードで stdout に書き込まないでください。 stdout は通常、プロトコル通信に使用され、デバッグ ログは stderr またはログ ファイルに書き込まれる必要があります。

ツール呼び出しのタイムアウトを増やす必要がありますか?

不確かな。まず、返されるデータが多すぎるかどうか、クエリに制限がないこと、ネットワーク リクエストにタイムアウトがないことを確認します。むやみにタイムアウトを増やすと、エージェントが長時間スタックすることになります。

1 つの MCP サーバー上に多数のツールがあるのは良いことですか?

不確かな。ツールが多すぎると、モデル選択のコストが増加し、トラブルシューティングがより困難になります。シナリオごとに分割し、現在のワークフローに本当に必要なツールのみを公開することをお勧めします。

ツールのスキーマはどの程度詳細にする必要がありますか?

フィールドの説明は明確にする必要がありますが、パラメータが多すぎないように注意してください。少数の安定したパラメータの設計を優先し、オプションのオプションにデフォルト値を提供します。スキーマが直感的であればあるほど、モデルが誤って送信される可能性は低くなります。

ファイルの完全な内容を返すことはできますか?

小さいファイルは問題ありませんが、大きいファイルはお勧めできません。より安定したアプローチは、最初に概要、一致する行、およびファイル パスを返し、次にモデルにオンデマンドで特定のフラグメントを読み取らせることです。

MCP は実稼働システムへのアクセスに適していますか?

注意してください。運用システムの MCP ツールには、少なくとも、権限の分離、読み取り専用の優先順位、監査ログ、危険な操作の確認、およびレート制限が必要です。高い特権の操作をエージェントに直接公開しないでください。

まとめ

MCP ツールの呼び出しに失敗します。トラブルシューティングを行うときは、まずレイヤーをチェックします。サーバーが起動できるかどうか、クライアントが接続できるかどうか、ツールを登録できるかどうか、パラメータがスキーマに準拠しているかどうか、実行中に権限があるかどうか、返された結果が制御可能かどうかです。プロンプトの言葉を最初から変更しないでください。また、すべての問題をモデルのせいにしないでください。

安定した MCP ツールは、独立して実行でき、明確な構成、明確な権限、シンプルなパラメーター、および抑制された結果が返される必要があります。最初に最小のリンクをクリアし、次にツールの機能を徐々に増やすと、トラブルシューティングがはるかに簡単になります。

© 2022 - 2026 KnightLiブログ
记录并分享
Hugo で構築されています。
テーマ Stack は Jimmy によって設計されています。