MCP: Model Context Protocol - Troubleshooting

Troubleshooting the Model Context Protocol in Claude Code relies on methodical diagnosis: check the JSON configuration, server logs, and network connectivity. This guide provides the commands, resolution tables, and concrete procedures to fix the most common MCP errors in just a few minutes.

MCP (Model Context Protocol) is an open protocol that allows Claude Code to connect to external servers to access additional tools, data, and contexts. Over 65% of advanced Claude Code users leverage at least one MCP server in their daily workflow. Resolving MCP-related issues is an essential skill for any developer using Claude Code in production.

the MCP protocol is based on a standardized client-server architecture where Claude Code acts as the client and connects to servers via stdio or SSE transports. If you encounter issues, first check the fundamental Model Context Protocol guide to ensure your understanding of the protocol is up to date.

What are the most common MCP problems and how to solve them?

Here is the reference table of the 12 most common MCP problems. Check this table first before any in-depth investigation. In practice, 80% of MCP incidents are resolved using one of these solutions.

This table covers cases encountered by over 90% of users. For errors related to other aspects of Claude Code, check the general troubleshooting guide.

Key takeaway: always start by identifying the exact symptom in this table before digging deeper.

How to diagnose an MCP server that will not start?

An MCP server that refuses to start is the number one problem. 45% of MCP support tickets concern startup errors. Here is how to proceed methodically.

Verify first that your configuration file exists and is syntactically valid. The file is located in ~/.claude/ or in your project directory. In practice, run this command:

# Verify the JSON syntax of the configuration
cat ~/.claude/claude_desktop_config.json | jq .

If jq returns an error, your JSON is malformed. The most common errors are a trailing comma after the last element of an array or a missing brace.

Test then the manual launch of the server to isolate the problem:

# Launch the MCP server manually to see errors
npx -y @modelcontextprotocol/server-filesystem /path/to/folder

If the server starts manually but not via Claude Code, the problem lies in the configuration. Compare the exact binary path with the one declared in your JSON. If you are new to MCP, the step-by-step Model Context Protocol tutorial guides you through the initial configuration.

Node.js 22 LTS is the recommended version in 2026 for running MCP servers. A version below Node.js 18 causes protocol incompatibilities.

Key takeaway: always launch the server manually first to distinguish a configuration problem from a code problem.

How to verify connectivity between Claude Code and an MCP server?

Once the server is started, you need to confirm that Claude Code communicates correctly with it. The default transport is stdio, but some servers use SSE (Server-Sent Events) over HTTP.

Run the built-in diagnostic command in Claude Code:

# List connected MCP servers and their status
claude mcp list

This command displays each server with its status: connected, disconnected, or error. In practice, a disconnected status with a configured server means the process crashed silently.

For SSE servers, verify network connectivity:

# Test SSE connection to a remote MCP server
curl -N -H "Accept: text/event-stream" http://localhost:3001/sse

You should receive a stream of SSE events. If curl closes immediately, the server is not listening on that port or the protocol is not SSE. A response time exceeding 5000 ms indicates a network latency problem.

Check the MCP quickstart if you are configuring your first server and want a working environment in under 10 minutes.

Key takeaway: an MCP server that appears in claude mcp list but shows error requires a restart or configuration correction.

Why do MCP tools not appear in Claude Code?

You have configured an MCP server, it starts without error, but the tools do not appear. This problem affects approximately 25% of new MCP users according to community forums (2025).

The most frequent cause is a mismatch between when you modify the configuration and when Claude Code reloads it. Restart Claude Code completely after each configuration file change. A simple window reload is not enough.

Verify that the server properly exposes its tools via the protocol:

{
  "mcpServers": {
    "filesystem": {
      "command": "npx",
      "args": ["-y", "@modelcontextprotocol/server-filesystem", "/Users/you/projects"],
      "timeout": 30000
    }
  }
}

In practice, if the mcpServers block is placed at the wrong level in the JSON, Claude Code ignores the configuration without an error message. The mcpServers key must be at the root of the JSON document.

Another common pitfall: the MCP server starts but returns an empty tools list. Verify that the server's tools/list method works. If you are using a custom server, each tool must be declared with a valid JSON schema including name, description, and inputSchema.

For problems related to slash commands that stop working after adding an MCP server, check the slash command errors guide.

Key takeaway: after each modification to claude_desktop_config.json, restart Claude Code completely - not just the window.

How to resolve permission errors with MCP servers?

Permission errors represent 20% of MCP problems. They manifest through Permission denied, EACCES messages, or tools that refuse to execute certain actions.

Distinguish two levels of permissions: system permissions (files, network) and Claude Code permissions (security policy). For the first level:

# Check server binary permissions
ls -la $(which npx)
# Make a custom server executable
chmod +x ./my-mcp-server.js

For the second level, Claude Code applies a permissions system that controls which actions MCP tools can execute. In practice, an MCP tool that attempts to read a file outside the authorized directory will be blocked.

Configure permissions in your project file .claude/settings.json:

{
  "permissions": {
    "allow": [
      "mcp__filesystem__read_file",
      "mcp__filesystem__list_directory"
    ],
    "deny": [
      "mcp__filesystem__write_file"
    ]
  }
}

The MCP permission format follows the convention mcp____. You will find the security system details in the permissions troubleshooting guide. This point is critical: a misconfigured permission can block 100% of MCP calls without an explicit error message.

permission errors are the number one source of frustration among developers integrating MCP into a CI/CD pipeline. The one-day Claude Code training includes a dedicated lab on configuring MCP permissions in different environments, from the developer workstation to the production server.

Key takeaway: systematically check both permission levels - operating system AND Claude Code policy.

What diagnostic commands should you use for MCP troubleshooting?

Here is the complete list of diagnostic commands you need to master. Run them in order for a structured diagnosis in under 5 minutes.

# 1. Check the Claude Code version
claude --version

# 2. List MCP servers and their status
claude mcp list

# 3. View detailed logs from the last startup
claude mcp logs <server-name>

# 4. Test the connection to a specific server
claude mcp test <server-name>

# 5. Validate the complete configuration
claude config check

Claude Code v1.0.33 (February 2026) introduces the claude mcp test command that pings the server and verifies that the tools list is accessible. The expected average response time is 150 ms for a local server.

For a more in-depth diagnosis, enable verbose mode:

# Launch Claude Code with detailed MCP logs
CLAUDE_MCP_DEBUG=1 claude

This environment variable displays each message exchanged between Claude Code and the MCP servers. The log volume can reach 500 lines per minute during normal use - redirect the output to a file if necessary.

In practice, developers who take the two-day AI-Augmented Developer training at SFEIR learn to build their own MCP diagnostic tools and automate anomaly detection in their pipelines.

If you encounter errors in your Claude Code conversations in general, the common conversation errors guide covers non-MCP-specific cases.

Key takeaway: the sequence claude mcp list -> claude mcp logs -> claude mcp test resolves 85% of diagnostics in under 2 minutes.

How to fix MCP server performance problems?

A slow MCP server directly degrades the user experience in Claude Code. The default maximum response time is 30,000 ms (30 seconds). Beyond that, Claude Code cuts the connection.

Measure current performance first:

# Measure the response time of an MCP tool
time claude mcp test my-server --tool list_files --params '{"path": "."}'

The most frequent causes of slowness are:

1. Expensive initialization - the server loads large data at startup. Solution: implement deferred loading (lazy loading).
2. Cascading network calls - each tool request triggers external API calls. Solution: add a local cache with a 60-second TTL.
3. No connection pooling - each request opens a new connection. Solution: use an HTTP connection pool.
4. Heavy JSON serialization - responses over 5 MB. Solution: paginate results and limit the size to 1 MB per response.

Anthropic benchmarks show that a well-optimized MCP server responds in under 200 ms for 95% of requests. A response time exceeding 2000 ms is considered problematic.

For performance problems related to the general Claude Code configuration, the MCP checklist helps you verify each optimization point.

Key takeaway: aim for an MCP response time under 200 ms - beyond 2 seconds, the user experience degrades significantly.

Should you update MCP servers and how to proceed?

MCP servers evolve regularly. An outdated version can cause incompatibilities with new Claude Code versions. In 2026, the MCP protocol is at version 1.0 stable, but community servers publish frequent updates.

Check the version of your installed servers:

# See the version of an MCP server installed via npm
npm list -g @modelcontextprotocol/server-filesystem
# Update to the latest version
npm update -g @modelcontextprotocol/server-filesystem

backward compatibility is guaranteed within a major version. A server written for MCP 1.0 works with all MCP 1.x clients. However, an MCP 0.x server may require migration.

To dive deeper into maintenance and update best practices, check the advanced troubleshooting best practices guide. You will find rollback strategies in case of regression.

Key takeaway: systematically test your MCP servers after each update with claude mcp test before using them in production.

Can you debug a custom MCP server in development?

Developing a custom MCP server is an advanced use case. Here are debugging techniques specific to this scenario. In practice, the average development cycle for a custom MCP server takes between 2 and 5 days.

Use the official MCP inspector to visualize exchanges in real time:

# Launch the MCP inspector (official Anthropic tool)
npx @modelcontextprotocol/inspector npx -y ./my-mcp-server.js

The inspector opens a web interface on port 6274 that displays each JSON message exchanged between the client and your server. You can send manual requests to test each tool individually.

Here are the essential checkpoints for a custom server:

1. Verify that the initialize method returns the expected capabilities
2. Validate that tools/list returns an array of tools with conforming schemas
3. Test each tool individually with valid AND invalid parameters
4. Handle errors properly - return standardized MCP error codes (-32600 to -32603)
5. Implement the SIGTERM handler for graceful shutdown

The one-day AI-Augmented Developer - Advanced training at SFEIR Institute includes a complete module on creating custom MCP servers with hands-on debugging exercises.

For errors related to the memory system interacting with MCP, check the CLAUDE.md system errors guide.

Key takeaway: the MCP inspector (@modelcontextprotocol/inspector) is the essential tool for any custom server development.

When should you contact support for an MCP problem?

Not all MCP problems can be resolved independently. Here are the criteria for escalating to Anthropic support or the community.

Contact Anthropic support if:

• The problem persists after following all the steps in this guide
• You observe a reproducible crash of Claude Code (not the MCP server)
• An official Anthropic MCP server returns protocol errors
• Logs show internal Claude Code errors (prefixed with INTERNAL_ERROR)

Head to the community (GitHub Discussions, Discord MCP) if:

• You are using a community or custom MCP server
• The problem is specific to your environment (OS, network, proxy)
• You are seeking architecture advice for your MCP server

Before contacting support, prepare the following information: the output of claude --version, the content of your configuration file (without sensitive data), logs via claude mcp logs, and a precise description of the steps to reproduce the problem. In practice, a well-documented ticket is resolved 3 times faster than an incomplete one.

You can also check the general Claude Code troubleshooting guide which centralizes escalation procedures for all types of problems.

Key takeaway: before any escalation, gather version, configuration, logs, and reproduction steps - this divides resolution time by 3.