How to troubleshoot MCP tool call failure: tutorials, troubleshooting and FAQ

After the MCP tool is connected, the AI Agent can read files, check databases, search documents, launch browsers, and access internal systems. However, during actual configuration, we often encounter an embarrassing situation: the tool is displayed as installed, and the tool name can also be seen in the model, but it fails as soon as it is called, or it simply does not appear in the tool list.

When troubleshooting MCP problems, don’t doubt the model from the very beginning. Most failures occur in more basic links: the server is not started, the command path is incorrect, the environment variable is not passed, insufficient permissions, the protocol mode does not match, the tool schema is written incorrectly, or the returned data is too large. By checking by layer, you can usually locate it quickly.

Let’s look at the MCP call link first

An MCP tool call generally goes through these steps:

The client reads the MCP configuration.
The client starts or connects to the MCP server.
Server exposed tool list.
Select a tool for the model.
The client passes the parameters to the server.
The server executes the tool and returns the results.
The client puts the results back into the model context.

Failure at any layer may ultimately manifest as “tool call failure.” Therefore, when troubleshooting, you must first determine which layer the failure occurred, instead of just focusing on the final error report.

Minimum check order

It is recommended to check in this order:

Can the MCP server be started separately?
Are the commands, parameters and paths in the client configuration correct?
Whether the environment variables are passed to the MCP server.
Whether the tool can appear in the client tool list.
Whether the tool parameters comply with the schema.
Is there any lack of permissions or dependencies when the server is executed?
Whether the returned content is too large or in the wrong format.
Whether the protocol modes of the client and server match.

If the first step fails, do not continue to change the prompt word. Start the server first.

Tutorial: Start the MCP server separately first

Assuming that your MCP server is a Node.js command, run it directly in the terminal:

1

npx -y example-mcp-server

If it is a local script:

1

node ./server.js

Python projects can first confirm dependencies and entries:

1

python -m your_mcp_server

This step mainly checks whether there are missing packages, wrong paths, wrong permissions, occupied ports, or missing API Keys. Only when the server can be started independently can the client call it normally.

Tutorial: Check client configuration

MCP configuration usually contains fields such as command, args, env, etc. A typical structure is similar to:

 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"
      }
    }
  }
}

Focus of investigation:

Whether command can be found in the current environment.
args Whether to split it into an array instead of writing it as a whole line of string.
Whether Windows paths are escaped correctly.
Whether the API Key is placed in an environment variable that can be read by the server.
Whether the client is restarted after the configuration file is modified.

Many problems are just that the configuration has been changed, but the client has not been reloaded.

Common error: server startup failed

Typical performance:

1
2
3
4


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

Common reasons:

node, python, npx are not in PATH.
The command was written incorrectly.
The local script path is written incorrectly.
Windows paths contain spaces but are not handled correctly.
The current working directory is different from what you think.

Troubleshooting method:

1
2
3


which node
which npx
which python

Windows PowerShell:

1
2
3


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

If the command cannot be found in the client, you can change it to an absolute path, or confirm that the client inherits the correct PATH when it starts.

Common error: Tool list is empty

The server seems to be started, but there are no tools in the client, usually the initialization phase failed.

Possible reasons:

The server outputs non-protocol logs, interfering with stdio communication.
The server reported an error during initialization but was swallowed.
Wrong transfer mode used.
Tool registration logic is not executed.
The client version does not support some capabilities of the server.

If it is a stdio MCP server, special attention should be paid: do not write ordinary logs directly to stdout. stdout should generally be reserved for protocol messages, and debug logs should be written to stderr or a file.

Common errors: JSON configuration format error

Typical performance:

1
2
3


Unexpected token
invalid JSON
failed to parse config

FAQ:

There are comments in JSON.
There is an extra comma at the end.
Windows path backslashes are not escaped.
Chinese full-width symbols are used for quotation marks. -Write the command parameters as a whole shell string.

The Windows path is recommended to be written as:

1

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

Or use forward slashes directly:

1

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

Don’t write:

1

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

This way of writing can easily be regarded as an escape character in JSON.

Common error: API Key not passed in

Many MCP servers need to access external services. Just because you can run it in the terminal does not mean that the same environment variables can be read when the client starts.

Typical performance:

1
2
3
4


missing API key
unauthorized
401
permission denied

Troubleshooting method:

Explicitly write the required variables in env in the MCP configuration.
Confirm that the variable names are case-sensitive.
Confirm that the client is restarted before testing again.
Do not print the key to the normal log.

If you set a variable temporarily in the shell, the GUI client may not inherit it. The most stable method is to write the configuration environment variables of the MCP server, or use a system-level secure key management method.

Common errors: Insufficient permissions

The tool can be called, but execution fails. The common reason is insufficient permissions.

For example:

The file system tool cannot access the target directory.
The database account does not have query permission.
There is no available profile for the browser automation tool.
The Git tool cannot write to the current repository.
The corporate network blocks access to internal APIs.

During the investigation, ask two questions first:

Which user does the MCP server process run as?
What are its working directory and permission boundaries?

Don’t just look at your own terminal permissions. The server started by the client may run in different environments.

Common error: Tool parameters do not conform to the schema

If the model can see the tool, but the parameters are wrong when called, it is usually because the schema is inconsistent with the actual implementation.

Typical performance:

1
2
3
4


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

Common reasons:

The tool definition requires path, and the model passes file_path.
The schema is written as a string, and is processed as an array in the implementation.
There are too many required fields and the model does not know how to fill them in.
The parameter description is unclear, causing the model to be transmitted in the wrong format.

Improvement method:

Keep tool parameters as few as possible.
Field names should be intuitive.
description clearly states the units, format and examples.
Set sensible default values for optional parameters.

A good tool schema should make it difficult to mistransmit the model.

Common error: call timeout

Typical performance:

1
2
3


timeout
request timed out
tool call exceeded limit

Common reasons:

The tool performed a long network request.
There is no limit for database queries.
Web scraping stuck.
Large file reading or vector retrieval is too slow.
There is no timeout control inside the server.

Processing method:

Add limit to the query.
Add timeout to network requests.
Return to summary first, then expand details as needed.
Break long tasks into two steps.
Make clear error returns for failed requests.

MCP tools are not always better. For agents, tools that are predictable and fail quickly are more reliable.

FAQ: Return data is too large

MCP tools returning too much content can bloat the context and make it impossible for the model to continue processing.

High risk returns:

The entire body of the web page.
Complete database table.
Large section of log.
Hundreds of search results.
Complete directory tree and all file contents.

Suggested return structure:

 1
 2
 3
 4
 5
 6
 7
 8
 9
10


{
  "summary": "Found 5 relevant results",
  "items": [
    {
      "title": "result title",
      "why_relevant": "matched auth config",
      "source": "path-or-url"
    }
  ]
}

Return the summary and index first and let the model decide whether to continue reading a certain detail.

Do not mix stdio and HTTP modes

Some MCP servers use stdio, some use HTTP or SSE. The client configuration must be consistent with the transmission mode supported by the server.

If the server is stdio, you usually configure command and args. If it’s HTTP, you need to configure the URL. Starting the HTTP server as a stdio command, or accessing the stdio server as an HTTP address will fail.

When troubleshooting, first confirm the transmission mode in the server document:

stdio: local process, communicates through standard input and output.
HTTP/SSE: Remote or local service, communicates via URL.

Don’t just copy other people’s configuration snippets, align them with how the current server is running.

Path and shell issues under Windows

There are more common pitfalls for Windows users:

The path has spaces.
The quoting rules for PowerShell and cmd are different.
npx is actually the .cmd wrapper command.
Node or Python is installed in the user directory and cannot be found by the GUI client.
Backslashes become escaped in JSON.

When troubleshooting, give priority to testing with simple paths, for example, put server in:

1

C:/mcp/server.js

If the simple path can run but the original path cannot, it is probably a path escaping or permissions issue.

Client version and server version do not match

The MCP ecosystem is updated very quickly. When the client, SDK, and server template versions are inconsistent, tool list abnormalities, parameter format changes, or incompatible capability statements may occur.

Troubleshooting method:

Upgrade the client to a newer version.
Check the MCP SDK version used by the server.
Read the server’s README configuration example.
Run the official minimum example first, and then connect the custom server.

If the official example can run but the custom server cannot, the problem is most likely in the custom implementation or configuration.

Recommended troubleshooting templates

If you encounter a failure to call the MCP tool, you can organize the information according to this template:

 1
 2
 3
 4
 5
 6
 7
 8
 9
10


MCP server name:
Transport mode: stdio / HTTP / SSE
Client:
Operating system:
Startup command:
Can it start independently:
Does it appear in the tool list:
Failed tool name:
Error message:
Recent changes:

With this information, asking the AI Agent or colleagues to help you troubleshoot will be much more efficient than just saying “the tool is broken.”

FAQ

The MCP tool does not display. Is it a model problem?

Usually not. Tools that are not displayed most often occur during the configuration reading, server startup, initialization, or tool registration stages. First check the client log and whether the server is started successfully.

Why can it run in the terminal but not in the client?

The PATH, environment variables, working directory, and user permissions when the client starts may be different from your terminal. Changing the command to an absolute path and explicitly passing the environment variables in the MCP configuration can usually solve some of the problems.

Can MCP server print logs?

Yes, but do not write ordinary logs to stdout in stdio mode. stdout is typically used for protocol communication, and debug logs should be written to stderr or a log file.

Should the tool call timeout be increased?

uncertain. First check whether there is too much data returned, there is no limit for the query, and there is no timeout for the network request. Blindly increasing the timeout will make Agent stuck for longer.

Is it good to have many tools on one MCP server?

uncertain. Too many tools will increase the cost of model selection and make troubleshooting more difficult. It is recommended to split it by scenario and expose only the tools that are really needed for the current workflow.

How detailed should the tool schema be?

Field descriptions should be clear, but not too many parameters. Prioritize the design of a small number of stable parameters and provide default values for optional options. The more intuitive the schema is, the less likely it is that the model will be mistransmitted.

Is it possible to return the complete file content?

Small files are fine, but large files are not recommended. A more stable approach is to return the summary, matching lines, and file paths first, and then let the model read the specific fragments on demand.

Is MCP suitable for accessing production systems?

Be cautious. Production system MCP tools require, at a minimum, permission isolation, read-only priority, audit logging, dangerous operation acknowledgment, and rate limiting. Do not expose high-privilege operations directly to the Agent.

summary

The MCP tool fails to be called. When troubleshooting, first check in layers: whether the server can be started, whether the client can connect, whether the tool can be registered, whether the parameters comply with the schema, whether there are permissions during execution, and whether the returned results are controllable. Don’t change the prompt words from the beginning, and don’t attribute all problems to the model.

A stable MCP tool should be able to run independently, have clear configuration, clear permissions, simple parameters, and restrained return results. First clear the smallest link, and then gradually increase the tool capabilities, troubleshooting will be much easier.