> For the complete documentation index, see [llms.txt](https://docs.cherryai.com.cn/llms.txt). Markdown versions of documentation pages are available by appending `.md` to page URLs; this page is available as [Markdown](https://docs.cherryai.com.cn/docs/jp/advanced-basic/extensions/mcp/troubleshooting.md).
# MCP トラブルシューティング
MCP の問題は通常、4つの段階のどこかにあります。サーバーが起動していない、実行環境が不完全、認証またはアドレスが間違っている、Agent がバインドされていない。順番に確認するほうが、何度も再インストールするより早いです。
## 迅速な判断
| 現象 | まず確認 | よくある原因 |
| ----------------------- | ---------------------- | ------------------------------------- |
| サーバーが起動できない | 【設定】→【MCP】→サーバー詳細→ログ | コマンドが存在しない、引数が間違っている、環境変数が不足している |
| リモート接続に失敗する | URL、ネットワークプロキシ、認証 | アドレスのプロトコルが間違っている、サービスに到達できない、トークンが無効 |
| サーバーは正常だがツールがない | サーバー詳細内のツール一覧 | サービスがツールを返していない、または権限が不足している |
| ツールは存在するが Agent が呼び出せない | Agent【MCP】 | 未バインド、ツールが無効、設定が次のメッセージに反映されていない |
| 呼び出しが待機で止まる | Agent の権限リクエストと右側の【状態】 | 手動承認が必要、またはバックグラウンドタスクが完了していない |
| 呼び出しが異常終了する | 呼び出しチェーンの入力、出力、状態 | パラメータがツール定義に合っていない、サーバー側エラー |
## 確認手順
{% stepper %}
{% step %}
### 1. MCP 設定ページでサーバーを個別に検証する
状態が正常で、ツール、リソース、またはプロンプトが表示されることを確認します。ここに何もない場合は、まず Agent を調整しないでください。
{% endstep %}
{% step %}
### 2. 実行環境を確認する
ローカルコマンドには対応するランタイムと実行ファイルが必要です。パスやコマンドにスペースが含まれる場合は、サーバーの説明に従ってコマンドと引数を分け、設定全体を1つのパスとして扱わないでください。
{% endstep %}
{% step %}
### 3. 認証とネットワークを確認する
URL、トークン、プロキシ、証明書を確認します。完全なキーを公開 Issue に載せないでください。必要に応じて、識別用に先頭と末尾の少数文字だけを残します。
{% endstep %}
{% step %}
### 4. Agent のバインドと権限を確認する
サーバーが Agent【MCP】で有効になっていることを確認し、現在の権限モードもチェックします。最小限のテスト指示を新しく送信し、1つのツールだけを呼び出します。
{% endstep %}
{% step %}
### 5. 呼び出しチェーンでリクエストを特定する
まだ判断できない場合は、【設定】→【システム】→【開発者モード】を開き、アプリを再起動して再現した後、呼び出しチェーンで MCP のサービス名、種類、入力、出力、状態を確認します。
{% endstep %}
{% endstepper %}
## 適用例：ツールは見えるのに Agent が呼び出さない
まず MCP 詳細でツールが存在することを確認し、次に Agent【MCP】でバインド済みか確認します。次に、そのツールだけを呼び出す最小指示を送ります。待機状態で止まる場合は権限の承認を確認し、呼び出しノードはあるがエラーが返る場合はパラメータとサーバーログを確認します。最初からサーバーを再インストールしないでください。
### トラブルシューティング完了の基準
問題が「サーバー起動、接続認証、Agent バインド、権限承認、ツール実行」のどの段階で止まっているかを明確にでき、再現可能な最小テスト指示を1つ残せていること。
{% hint style="danger" %}
ログを共有する前に、API Key、Authorization、メールアドレス、ローカルユーザー名、完全なファイルパス、業務データを削除してください。プレースホルダーで説明できる内容は、実際の認証情報をアップロードしないでください。
{% endhint %}
なぜ同じ設定がターミナルでは動くのに、Cherry Studio では失敗するのですか？
アプリのプロセスとログイン中のターミナルでは、環境変数や PATH が異なる場合があります。サービスが明示的に必要とする環境変数を MCP 設定に書き込み、コマンドがアプリから見つけられる実行ファイルであることを確認してください。
サーバーを削除して再追加すべきですか？
まずログを見て、項目ごとに修正してください。設定がすでに混乱していて、ソースも再取得できる場合に限り、削除して再構築します。削除前に、秘密鍵を含まない設定のコピーを保存してください。
---
# Agent Instructions
This documentation is published with GitBook. GitBook is the documentation platform designed so that both humans and AI agents can read, navigate, and reason over technical content effectively. Learn more at gitbook.com.
## Querying This Documentation
If you need additional information that is not directly available in this page, you can query the documentation dynamically by asking a question.
Perform an HTTP GET request on the current page URL with the `ask` query parameter, and the optional `goal` query parameter:
```
GET https://docs.cherryai.com.cn/docs/jp/advanced-basic/extensions/mcp/troubleshooting.md?ask=&goal=
```
`ask` is the immediate question: it should be specific, self-contained, and written in natural language.
`goal` is optional and describes the broader end goal you are ultimately trying to accomplish on behalf of the user. GitBook uses it to tailor the answer towards what is most useful for that goal.
The response will contain a direct answer to the question and relevant excerpts and sources from the documentation.
Use this mechanism when the answer is not explicitly present in the current page, you need clarification or additional context, or you want to retrieve related documentation sections.