Troubleshooting MCP Servers

1. Server Not Appearing in Claude Desktop

This is the most common issue. Your MCP server is configured but doesn't show up in Claude Desktop's tool list.

Check 1: Verify JSON Syntax

{
  "mcpServers": {
    "github": {
      "command": "npx",
      "args": ["-y", "@modelcontextprotocol/server-github"],
      "env": {
        "GITHUB_TOKEN": "ghp_token"
      }
    },  // ← Trailing comma causes error
  }
}

{
  "mcpServers": {
    "github": {
      "command": "npx",
      "args": ["-y", "@modelcontextprotocol/server-github"],
      "env": {
        "GITHUB_TOKEN": "ghp_token"
      }
    }
  }
}

Solution: Use a JSON validator like jsonlint.com to check your config file.

Check 2: Restart Claude Desktop Completely

Configuration changes only take effect after a full restart.

Check 3: Verify Config File Location

Make sure you're editing the correct configuration file:

# macOS - Open config file
open ~/Library/Application\ Support/Claude/claude_desktop_config.json

# Windows - Open config file
notepad %APPDATA%\Claude\claude_desktop_config.json

Check 4: Verify Server Command Exists

Test if the server command can be executed from your terminal:

# Test if npx can run the server
npx -y @modelcontextprotocol/server-github --help

# Should display help text, not an error

2. Connection Errors

Server appears but shows connection or authentication errors.

Authentication Failed

Solution 1: Verify API Key Format

Solution 2: Check Token Permissions/Scopes

Ensure your API token has the necessary permissions:

Solution 3: Check Token Expiration

• Verify token hasn't expired (check service dashboard)
• Regenerate token if necessary
• Update config file with new token
• Restart Claude Desktop

Permission Denied Errors

Token is valid but lacks access to specific resources.

3. Tools Not Working Properly

Tool Execution Errors

Server connects but specific tool calls fail.

Check Logs for Details

# macOS
tail -f ~/Library/Logs/Claude/mcp*.log

# Or view all recent logs
ls -lt ~/Library/Logs/Claude/mcp*.log | head -5
cat ~/Library/Logs/Claude/mcp-server-github.log

# Windows
# Logs in: %APPDATA%\Claude\Logs\
type %APPDATA%\Claude\Logs\mcp-server-github.log

Common Tool Errors

Unexpected Tool Behavior

Tool Returns Empty Results

• Notion: Check pages are shared with integration
• GitHub: Verify repo exists and token has access
• Database: Confirm query syntax and table names

Tool Changes Don't Persist

• Filesystem: Check file permissions (read-only?)
• Git: Verify repo isn't in detached HEAD state
• Database: Check transaction isn't rolling back

4. Performance Issues

Slow Response Times

Optimization Strategies

High Memory Usage

Claude Desktop or MCP servers consuming excessive memory.

• Restart Claude Desktop periodically for long sessions
• Close unused conversations
• Avoid loading massive files into context
• Limit concurrent MCP servers (disable unused ones)

5. Environment-Specific Issues

Windows-Specific Problems

Path Issues

// ❌ Wrong
"args": ["C:\Users\Me\code"]

// ✓ Correct option 1
"args": ["C:/Users/Me/code"]

// ✓ Correct option 2
"args": ["C:\\Users\\Me\\code"]

npx Not Found

If npx isn't recognized:

• Ensure Node.js is installed (download from nodejs.org)
• Add Node.js to PATH environment variable
• Restart Claude Desktop after installing Node.js

macOS-Specific Problems

Permission Issues

macOS may block MCP servers from accessing files:

• Grant Claude Desktop "Full Disk Access" in System Settings → Privacy & Security
• Allow access to specific folders when prompted

Homebrew-Installed Tools

If using Homebrew-installed commands:

{
  "command": "/opt/homebrew/bin/node",
  "args": ["/path/to/server.js"]
}

6. Debugging Techniques

Enable Verbose Logging

Some MCP servers support debug mode via environment variables:

{
  "mcpServers": {
    "github": {
      "command": "npx",
      "args": ["-y", "@modelcontextprotocol/server-github"],
      "env": {
        "GITHUB_TOKEN": "ghp_token",
        "DEBUG": "*",
        "MCP_LOG_LEVEL": "debug"
      }
    }
  }
}

Test Server Manually

Run the server directly in your terminal to see error messages:

# Set environment variables
export GITHUB_TOKEN="ghp_your_token"

# Run server
npx -y @modelcontextprotocol/server-github

# Watch for error messages in output

Minimal Config Test

Strip down to a minimal configuration to isolate the issue:

{
  "mcpServers": {
    "test": {
      "command": "npx",
      "args": ["-y", "@modelcontextprotocol/server-memory"]
    }
  }
}

If this works, gradually add back servers one at a time to find the problematic one.

7. Common Configuration Mistakes

8. Getting Help

Gather Diagnostic Information

Before asking for help, collect this information:

Where to Get Help

• MCP GitHub Discussions: github.com/modelcontextprotocol/discussions
• Anthropic Discord: discord.gg/anthropic (#mcp channel)
• Server-Specific Issues: Check individual server GitHub repos for issue trackers

9. Quick Reference: Error Messages

Prevention Tips

Best Practices to Avoid Issues

• Always validate JSON before saving config changes
• Use environment variables for secrets (keep them out of config file)
• Start with one server, verify it works, then add more
• Keep MCP packages updated (npx caches can be outdated)
• Document your setup (which servers, what they're for)
• Regularly check logs for warnings
• Test servers individually before combining them

Maintenance Checklist

Further Reading