Skip to main content

Troubleshooting MCP

Module: MCP Servers | Lesson: 4 of 4 | Time: ~10 minutes

What You Will Learn​

  • How to diagnose MCP connection issues
  • Where to find MCP server logs
  • Common Windows-specific gotchas and fixes

Prerequisites​

When Things Go Wrong​

MCP servers are external processes that Claude Code launches and communicates with. Sometimes they fail to start, lose connection, or behave unexpectedly. This lesson covers the most common problems and how to fix them.

Problem: Server Will Not Start​

Symptoms: When you start Claude Code, the MCP server does not appear in /mcp, or you see an error about failing to connect.

Common causes and fixes:

1. The package is not installed or cannot be found​

If you are using npx to run the server, make sure Node.js is installed and npx is available:

node --version
npx --version

If these commands fail, you need to install Node.js first. Download it from nodejs.org.

2. The package name is wrong​

Double-check the exact package name. A typo in the npm package name will cause npx to fail silently or show an error:

# Correct:
npx -y @modelcontextprotocol/server-filesystem

# Wrong (missing scope):
npx -y server-filesystem

3. Network issues​

The first time you run an MCP server with npx, it needs to download the package from npm. If you are behind a corporate firewall or proxy, this may fail. Try downloading the package manually first:

npm install -g @modelcontextprotocol/server-filesystem

Problem: Tool Not Found​

Symptoms: The server connects, but Claude says it cannot find a specific tool, or the tool does not appear in the available tools list.

Fixes:

  1. Check the server status with /mcp — make sure the server shows as connected
  2. The tool name may differ from what you expect. Ask Claude: "What tools are available from the filesystem server?"
  3. Restart Claude Code — some servers need a fresh connection to update their tool list

Problem: Permission Denied​

Symptoms: The server starts, but tools fail with "permission denied" or "access denied" errors.

Fixes:

  1. File system permissions: Make sure the user running Claude Code has access to the directories or files the server needs
  2. API key missing or invalid: If the server requires an API key, verify it is correctly set in the environment or config:
{
  "mcpServers": {
    "github": {
      "command": "npx",
      "args": ["-y", "@modelcontextprotocol/server-github"],
      "env": {
        "GITHUB_PERSONAL_ACCESS_TOKEN": "ghp_check_this_is_valid"
      }
    }
  }
}
  1. Token permissions: Even if your API key is valid, it may not have the right scopes. For GitHub, make sure your token has the repo scope for repository access.

Windows-Specific Issues​

Windows users encounter a few unique problems with MCP servers. Here are the most common ones:

The npx.cmd Issue​

On Windows, npx is actually npx.cmd. Some configurations need you to specify npx.cmd instead of npx:

{
  "mcpServers": {
    "filesystem": {
      "command": "npx.cmd",
      "args": ["-y", "@modelcontextprotocol/server-filesystem", "C:\\Users\\YourName\\Documents"]
    }
  }
}
caution

If your MCP server works from the terminal but fails when launched by Claude Code, try changing "command": "npx" to "command": "npx.cmd". This is the single most common Windows MCP issue.

Path Format Issues​

Windows paths use backslashes (\), but in JSON files, backslashes are escape characters. You must either:

  • Double the backslashes: "C:\\Users\\YourName\\Documents"
  • Use forward slashes: "C:/Users/YourName/Documents"

Both work. Forward slashes are easier to read and less error-prone.

Spaces in Paths​

If your Windows username or folder path contains spaces, make sure the entire path is a single argument:

{
  "args": ["-y", "@modelcontextprotocol/server-filesystem", "C:\\Users\\Your Name\\Documents"]
}

In JSON, the path is already a quoted string, so spaces are handled automatically. But if you are using the CLI command, wrap the path in quotes:

claude mcp add filesystem -- npx -y @modelcontextprotocol/server-filesystem "C:\Users\Your Name\Documents"

WSL Considerations​

If you run Claude Code inside WSL but want to access Windows files, use the /mnt/c/ path format:

claude mcp add filesystem -- npx -y @modelcontextprotocol/server-filesystem /mnt/c/Users/YourName/Documents

Checking MCP Logs​

When an MCP server fails, logs are your best friend. Here is how to find them:

  1. In-session diagnostics: Type /mcp in Claude Code to see the status of all connected servers. Servers that failed to start will show an error.

  2. Verbose mode: Start Claude Code with the --verbose flag to see more detailed output about MCP connections:

claude --verbose
  1. Test the server directly: Run the MCP server command by itself in a terminal to see if it starts:
npx -y @modelcontextprotocol/server-filesystem C:\Users\YourName\Documents

If it outputs an error, you have found the problem. Fix it there first, then try again in Claude Code.

Systematic Debugging

When an MCP server is not working, follow this order:

  1. Check /mcp status inside Claude Code
  2. Run the server command directly in your terminal
  3. Verify your config JSON is valid (no missing commas, brackets)
  4. Try npx.cmd instead of npx on Windows
  5. Check that any required API keys are set and valid

Try It Yourself​

Practice diagnosing an MCP issue:

  1. Intentionally create a broken MCP configuration by misspelling a package name:
claude mcp add broken-test -- npx -y @modelcontextprotocol/server-does-not-exist
  1. Start Claude Code and type /mcp
  2. Observe the error for the broken-test server
  3. Remove the broken server:
claude mcp remove broken-test
  1. Verify it is gone with claude mcp list

This exercise helps you recognize what a failed MCP server looks like so you can diagnose real issues faster.

What You Learned​

  • Server startup failures are usually caused by missing packages, typos, or network issues
  • Tool not found errors mean the server may not be connected — check with /mcp
  • Permission errors often come from missing or invalid API keys
  • On Windows, use npx.cmd instead of npx if servers fail to start
  • Escape backslashes in JSON paths or use forward slashes instead
  • Use /mcp, --verbose, and direct server testing to diagnose issues systematically
Help Us Improve

How was this lesson? Take 2 minutes to share your feedback — it helps us make the tutorials better for everyone.

Give Feedback →

Next Up​

Next: Capstone: Extend Claude with MCP