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

1

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.

2

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.

3

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.

4

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.

5

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.

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.

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.

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.