> 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/en-us/advanced-basic/extensions/mcp/troubleshooting.md).
# MCP Troubleshooting
MCP problems usually occur in four areas: the server has not started, the runtime environment is incomplete, authentication or address is incorrect, or the Agent is not bound. Check them in order; that is faster than repeatedly reinstalling.
Check in order: first confirm the server itself can run, then look at the Agent call chain.
## Quick check
| Symptom | Check first | Common causes |
| -------------------------------------------------------- | ------------------------------------------------------- | ----------------------------------------------------------------------------------- |
| Server fails to start | \[Settings] → \[MCP] → Server details → Logs | Command does not exist, parameters are incorrect, environment variables are missing |
| Remote connection failed | URL, network proxy, authentication | Incorrect address protocol, service unreachable, token expired |
| Server is normal but has no tools | Tool list in server details | The service did not return any tools or permissions are insufficient |
| Tools exist but the Agent does not know how to call them | Agent \[MCP] | Not bound, tools disabled, configuration not taking effect from the next message |
| Call stalls while waiting | Agent permission request and the \[Status] on the right | Manual approval is required or the background task has not finished |
| Call returns an error | Input, output, and status of the call chain | Parameters do not match the tool definition, server-side error |
## Troubleshooting order
{% stepper %}
{% step %}
### 1. Verify the server separately on the MCP settings page
Confirm the status is normal and that you can see tools, resources, or prompts. If none of these are present, do not adjust the Agent first.
{% endstep %}
{% step %}
### 2. Check the runtime environment
Local commands need the corresponding runtime and executable. When the path or command contains spaces, split the command and parameters according to the server instructions; do not treat the entire configuration as a single path.
{% endstep %}
{% step %}
### 3. Check authentication and network
Confirm the URL, token, proxy, and certificate. Do not post the full secret in a public issue; if necessary, keep only a few characters at the beginning and end for identification.
{% endstep %}
{% step %}
### 4. Check Agent binding and permissions
Confirm the server is enabled in Agent \[MCP], and check the current permission mode. Send a new minimal test instruction that calls only one tool.
{% endstep %}
{% step %}
### 5. Use the call chain to locate the request
If you still cannot determine the issue, open \[Settings] → \[System] → \[Developer Mode], restart the app and reproduce once, then check the MCP service name, type, input, output, and status in the call chain.
{% endstep %}
{% endstepper %}
## Example case: tools are visible, but the Agent does not call them
First confirm in the MCP details that the tool exists, then go to Agent \[MCP] to confirm it is already bound. Send a new minimal instruction that only asks to call that tool; if it stalls while waiting, check for permission approval; if a call node appears but returns an error, then check the parameters and server logs. Do not reinstall the server at the beginning.
### Completion criteria for troubleshooting
You can clearly identify which link the problem is in among “server startup, connection authentication, Agent binding, permission approval, tool execution,” and keep a repeatable minimal test instruction.
{% hint style="danger" %}
Before sharing logs, remove the API Key, Authorization, email address, local username, full file paths, and business data. If a problem can be explained with placeholders, do not upload real credentials.
{% endhint %}
Why can the same configuration run in the terminal but fail in Cherry Studio?
The application process and the logged-in terminal may have different environment variables and PATH. Write the environment variables explicitly required by the service into the MCP configuration, and make sure the command is an executable that the app can find.
Should I delete and re-add the server?
First check the logs and fix issues one by one. Only delete and rebuild if the configuration is already in a mess and the source can be obtained again; before deleting, save a copy of the configuration without secrets.
---
# 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/en-us/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.