Module 8: Debugging MCP Connections

---

When Things Go Wrong

MCP adds a layer between you and Claude. When something doesn't work, you need to know how to diagnose the problem. Is it the server? The configuration? The transport? This module gives you the debugging skills to find and fix issues quickly.

---

Debugging Mindset

When MCP isn't working, problems typically fall into these categories:

1. Configuration errors - JSON syntax, wrong paths
2. Server startup failures - Missing dependencies, bad environment
3. Connection issues - Transport problems, initialization failures
4. Runtime errors - Tool execution failures, invalid responses
5. Client issues - Claude Desktop/Code not loading servers

The key is systematically ruling out each category.

---

Configuration Validation

Start with the basics - is your configuration valid?

1. Validate JSON syntax

Use a JSON validator or your editor's built-in validation:

# Simple validation with Node
node -e "require('./claude_desktop_config.json')"

# Or with jq
cat claude_desktop_config.json | jq .

Common JSON errors:

• Trailing commas (not allowed in JSON)
• Missing quotes around keys
• Single quotes instead of double
• Unescaped special characters

2. Check required fields

Every server needs at minimum:

{
  "mcpServers": {
    "server-name": {
      "command": "some-command",
      "args": ["arg1", "arg2"]
    }
  }
}

3. Verify paths exist

# Check if the command exists
which npx

# Check if args point to valid paths
ls -la /path/in/args

---

Testing Servers Manually

Before involving Claude, test your server independently:

1. Run the server directly

# For npx-based servers
npx -y @modelcontextprotocol/server-filesystem /path/to/dir

# For local servers
node /path/to/your/server/dist/index.js

If the server crashes immediately, you'll see the error.

2. Check for missing dependencies

# For npm packages
npm install -g @modelcontextprotocol/server-filesystem

# Verify it's installed
npm list -g @modelcontextprotocol/server-filesystem

3. Verify environment variables

# Check if required env vars are set
echo $GITHUB_TOKEN
echo $BRAVE_API_KEY

# Run server with env vars
GITHUB_TOKEN=xxx npx -y @modelcontextprotocol/server-github

---

Claude Desktop Debugging

Claude Desktop doesn't show MCP errors directly, but you can find them:

macOS logs:

# View Claude Desktop logs
tail -f ~/Library/Logs/Claude/mcp*.log

# Or check system logs
log show --predicate 'process == "Claude"' --last 5m

Windows logs: Check Event Viewer or:

%APPDATA%\Claude\logs\

What to look for:

• "Failed to connect to server"
• "Server exited with code X"
• "Error initializing MCP server"
• Stack traces from server crashes

---

Claude Code Debugging

Claude Code provides better debugging visibility:

1. Use debug mode

claude --mcp-debug

This shows:

• Server connection attempts
• Initialization messages
• Tool calls and responses
• Errors in real-time

2. Check server status Ask Claude: "What MCP tools do you have available?"

If Claude doesn't mention expected tools, the server isn't connected.

3. Verbose output

claude --verbose

Shows additional information about what Claude Code is doing.

---

Common Issues and Solutions

Server Not Starting

Symptom: Server appears in config but Claude doesn't have access to its tools.

Check:

# Is the package installed?
npm list -g @modelcontextprotocol/server-xyz

# Can it run?
npx -y @modelcontextprotocol/server-xyz --help

# Are dependencies met?
npm -g outdated

Solution: Install missing packages, update npm, check Node version.

---

"Command not found"

Symptom: Error about command not being found.

Check:

# Where is npx?
which npx

# Is it in the right PATH?
echo $PATH

Solution: Use full path to command, or fix PATH in environment.

For Claude Desktop on macOS, the PATH might differ from your terminal. Use absolute paths:

{
  "command": "/usr/local/bin/npx",
  "args": ["-y", "@modelcontextprotocol/server-filesystem", "."]
}

---

Environment Variable Not Set

Symptom: Server needs API key but fails to authenticate.

Check:

# Is the variable set?
echo $GITHUB_TOKEN

# Is it in the right format?
echo ${GITHUB_TOKEN:0:10}...

Solution: Set the environment variable before starting Claude:

export GITHUB_TOKEN="ghp_..."
# Then start Claude Desktop from the same terminal
/Applications/Claude.app/Contents/MacOS/Claude

---

Permission Denied

Symptom: Server starts but can't access requested resources.

Check:

# File permissions
ls -la /path/to/directory

# Can your user read it?
cat /path/to/file

Solution: Fix file permissions or adjust configured paths.

---

Server Crashes After Starting

Symptom: Server connects briefly then disconnects.

Check:

# Run manually and watch for errors
npx -y @modelcontextprotocol/server-xyz args 2>&1 | head -50

Common causes:

• Invalid configuration in args
• Missing required environment variables
• Database connection failures
• Incompatible Node.js version

---

Tools Not Showing Up

Symptom: Server connects but tools aren't available.

Check:

1. Is the server declaring its capabilities correctly?
2. Is the client requesting tools list?
3. Are there errors in tool registration?

Debug approach: Add logging to your custom server:

server.setRequestHandler(ListToolsRequestSchema, async () => {
  console.error("Tools list requested");
  const tools = [/* your tools */];
  console.error("Returning tools:", JSON.stringify(tools));
  return { tools };
});

---

Network Debugging

For remote MCP servers or servers that make network calls:

1. Check connectivity

# Can you reach the API?
curl https://api.example.com/health

# DNS resolution
nslookup api.example.com

2. Firewall issues

# Test specific port
nc -zv api.example.com 443

3. Proxy configuration If behind a corporate proxy:

export HTTP_PROXY=http://proxy:port
export HTTPS_PROXY=http://proxy:port

---

Logging Best Practices

Add logging to your custom servers:

// Use stderr for logs (stdout is for MCP messages)
function log(level: string, message: string, data?: object) {
  const entry = {
    timestamp: new Date().toISOString(),
    level,
    message,
    ...data,
  };
  console.error(JSON.stringify(entry));
}

// Usage
log("info", "Server starting");
log("debug", "Tool called", { tool: "my_tool", args: { ... } });
log("error", "Operation failed", { error: error.message });

Log levels:

• error - Failures that need attention
• warn - Potential issues
• info - Normal operations
• debug - Detailed debugging info

---

Testing Individual Components

Test tool execution:

// Add a test mode to your server
if (process.argv.includes("--test")) {
  // Call your tool directly
  const result = await myToolFunction({ param: "test" });
  console.log("Test result:", result);
  process.exit(0);
}

Run with:

node dist/index.js --test

Test resource reading:

# Manually verify the resource exists
cat /path/to/resource

# Check it's valid JSON/format
cat /path/to/data.json | jq .

---

Debugging Checklist

When MCP isn't working:

• Is the JSON configuration valid?
• Does the command exist and is executable?
• Are all paths valid and accessible?
• Are required environment variables set?
• Can the server run manually without errors?
• Did you restart Claude after config changes?
• Are there errors in client logs?
• Does the server initialize successfully?
• Are tools listed when you ask Claude?
• Do tool calls return expected results?

---

Creating Debug Configurations

For development, create a debug-enabled config:

{
  "mcpServers": {
    "my-server-debug": {
      "command": "node",
      "args": [
        "--inspect",
        "/path/to/server/dist/index.js"
      ],
      "env": {
        "DEBUG": "true",
        "LOG_LEVEL": "debug"
      }
    }
  }
}

Then attach a debugger:

1. Start Claude with this config
2. Open Chrome DevTools for Node (chrome://inspect)
3. Attach to the Node process
4. Set breakpoints and debug

---

MCP Inspector Tool

Anthropic provides an MCP inspector for testing servers:

npx @modelcontextprotocol/inspector your-server-command args

The inspector:

• Connects to your server
• Lists available tools, resources, prompts
• Lets you test tool calls interactively
• Shows raw JSON-RPC messages

This is invaluable for debugging custom servers.

---

Key Takeaways

1. Start simple - Check config syntax first, then server startup

2. Test manually - Run servers outside Claude to see errors

3. Check logs - Claude Desktop and Claude Code have log locations

4. Use debug mode - claude --mcp-debug shows MCP activity

5. Add logging - Log to stderr in your custom servers

6. Systematic approach - Work through the checklist methodically

7. Inspector tool - Use MCP inspector for testing servers

---

Looking Ahead

Debugging is a skill that improves with practice. The more you work with MCP, the faster you'll diagnose issues. In the next module, we'll cover best practices - patterns that prevent problems before they occur.

---

Next up: Module 9 - MCP Best Practices