MCP Server Troubleshooting: Complete Configuration & Error Resolution Guide 2025

Introduction

Model Context Protocol (MCP) servers can encounter configuration issues, connection problems, or protocol errors that prevent them from working properly. This comprehensive troubleshooting guide covers the most common MCP server issues—including the frequently searched "MCP error -32000: Connection closed", request timeouts, failed to build actions from MCP endpoint" errors, and MCP Inspector proxy connection problems.

Whether you're using Claude Desktop, Claude Code, Cursor, Cline, VS Code, or any other MCP client, this guide provides step-by-step solutions to diagnose and resolve issues quickly.

Prerequisites

Before troubleshooting MCP server issues, ensure you have:

System Requirements

Claude Desktop, Claude Code, VS Code, Cursor, or Cline with MCP support
Node.js 18.0.0 or higher (for Node.js-based servers)
Python 3.8+ (for Python-based servers)
Basic command line knowledge for debugging steps

Verification Steps

# Check Node.js version
node --version
# Should output: v18.0.0 or higher

# Check Python version
python --version
# Should output: Python 3.8.0 or higher

# Find exact Node.js path (critical for configuration)
which node        # macOS/Linux
where node        # Windows

# Find exact Python path
which python3     # macOS/Linux
where python      # Windows

# Verify MCP server installation
npm list -g | grep @modelcontextprotocol

MCP JSON-RPC Error Codes Reference

MCP uses JSON-RPC 2.0 for communication. Understanding error codes helps quickly identify root causes.

Standard JSON-RPC Error Codes (Reserved Range: -32768 to -32000)

| Code | Name | Meaning | Common Causes | |------|------|---------|---------------| | -32700 | Parse Error | Invalid JSON syntax | Malformed JSON in request/response | | -32600 | Invalid Request | Request structure violates protocol | Missing required fields | | -32601 | Method Not Found | Requested operation doesn't exist | Typo in method name, server not implementing method | | -32602 | Invalid Params | Parameters failed validation | Wrong parameter types or missing required params | | -32603 | Internal Error | Server implementation issue | Uncaught exceptions in server code |

MCP Implementation-Specific Codes (-32000 to -32099)

| Code | Name | Meaning | Solutions | |------|------|---------|-----------| | -32000 | Connection Closed | Transport layer connection terminated | See Error -32000 section | | -32001 | Request Timeout | Request exceeded timeout (default 60s) | See Error -32001 section | | -32002 | Resource Not Found | Requested resource unavailable | Check file paths, URIs, database connections | | -32050 | Rate Limited | Too many requests | Implement exponential backoff |

Custom Application Error Codes

Implementations may define custom codes outside the reserved range:

-31xxx range: Authentication errors (e.g., -31001 AUTH_REQUIRED)
-30xxx range: Resource access errors (e.g., -30001 RESOURCE_LOCKED)

MCP Error -32000: Connection Closed

This is the most common MCP error. When you see "MCP error -32000: Connection closed", it means the transport layer failed to maintain the connection between your MCP client and server.

Symptoms

Server exits immediately after starting
"Process exiting early" error messages
Connection timeouts in MCP clients
Error message: MCP error -32000: Connection closed

Root Cause Analysis

97% of connection failures are caused by:

Incorrect Node.js paths (43%)
NVM configuration issues (28%)
Syntax errors in configuration JSON (15%)
Missing dependencies (9%)
Permission problems (5%)

Solution 1: Fix stdout Pollution (Most Common)

The #1 cause of -32000 errors is writing to stdout instead of stderr.

MCP's stdio transport uses stdout exclusively for JSON-RPC messages. Any non-protocol output corrupts the message stream.

# ❌ WRONG - Corrupts protocol stream
print("Server starting...")
print(f"Debug: {variable}")

# ✅ CORRECT - Use stderr for all logging
import sys
print("Server starting...", file=sys.stderr)
sys.stderr.write(f"Debug: {variable}\n")

// ❌ WRONG - Uses stdout
console.log("Server starting...");

// ✅ CORRECT - Uses stderr
console.error("Server starting...");

// ✅ CORRECT - Dedicated stderr logging
process.stderr.write("Debug info\n");

Solution 2: Windows Command Interpreter Fix

On Windows, npx and similar tools are batch scripts (.cmd files) that require cmd.exe to execute. Direct spawning fails.

// ❌ WRONG - Fails on Windows
{
  "mcpServers": {
    "github": {
      "command": "npx",
      "args": ["@modelcontextprotocol/server-github"]
    }
  }
}

// ✅ CORRECT - Use cmd /c wrapper
{
  "mcpServers": {
    "github": {
      "command": "cmd",
      "args": ["/c", "npx", "-y", "@modelcontextprotocol/server-github"]
    }
  }
}

Alternative: Use absolute paths to bypass npx entirely:

{
  "mcpServers": {
    "github": {
      "command": "C:\\Program Files\\nodejs\\node.exe",
      "args": [
        "C:\\Users\\YourName\\AppData\\Roaming\\npm\\node_modules\\@modelcontextprotocol\\server-github\\dist\\index.js"
      ]
    }
  }
}

Solution 3: Use Module Invocation for Python

// ❌ WRONG - May fail to initialize properly
{
  "mcpServers": {
    "myserver": {
      "command": "python",
      "args": ["main.py"],
      "cwd": "C:\\path\\to\\server"
    }
  }
}

// ✅ CORRECT - Module invocation with full path
{
  "mcpServers": {
    "myserver": {
      "command": "C:\\path\\to\\venv\\Scripts\\python.exe",
      "args": ["-m", "myserver.main"],
      "cwd": "C:\\path\\to\\server",
      "env": {
        "PYTHONUNBUFFERED": "1"
      }
    }
  }
}

Solution 4: Fix Path Issues

GUI applications (Claude Desktop, VS Code) don't inherit shell PATH. Always use absolute paths.

# Find your exact paths
which node        # macOS/Linux: e.g., /opt/homebrew/bin/node
where node        # Windows: e.g., C:\Program Files\nodejs\node.exe
which python3     # macOS/Linux
where python      # Windows

// ✅ CORRECT - Absolute paths
{
  "mcpServers": {
    "myserver": {
      "command": "/opt/homebrew/bin/node",
      "args": ["/Users/yourname/mcp-servers/myserver/index.js"]
    }
  }
}

Solution 5: NVM Wrapper Script (macOS/Linux)

NVM is a shell function, not an executable. Create a wrapper script:

#!/bin/bash
# Save as ~/bin/node-wrapper.sh and chmod +x
export NVM_DIR="$HOME/.nvm"
[ -s "$NVM_DIR/nvm.sh" ] && . "$NVM_DIR/nvm.sh"
nvm use default > /dev/null 2>&1
exec node "$@"

{
  "mcpServers": {
    "myserver": {
      "command": "/Users/yourname/bin/node-wrapper.sh",
      "args": ["server.js"]
    }
  }
}

Solution 6: Keep Process Alive

Ensure your server doesn't exit prematurely:

// Keep stdin open for stdio transport
process.stdin.resume();

// Handle shutdown gracefully
process.on('SIGINT', () => {
  console.error('Shutting down...');
  process.exit(0);
});

Debugging Steps for Error -32000

Test server directly in terminal:

# Run the exact command from your config
node /path/to/server/index.js
python -m myserver.main
npx @modelcontextprotocol/server-github

Check for immediate errors:

# Redirect stderr to see errors
node server.js 2>&1 | head -20

Validate JSON configuration:

# Python JSON validator
python3 -m json.tool claude_desktop_config.json

# Node.js validator
node -e "console.log(JSON.parse(require('fs').readFileSync('config.json', 'utf8')))"

Check Claude Desktop logs:

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

# Windows (PowerShell)
Get-Content "$env:APPDATA\Claude\logs\mcp.log" -Wait

MCP Error -32001: Request Timeout

MCP error -32001 occurs when requests exceed the timeout limit (default: 60 seconds).

Symptoms

Error: MCP error -32001: Request timed out
Error details: { code: -32001, data: { timeout: 60000 } }
Long-running operations fail

Solution 1: Increase Timeout Configuration

Claude Desktop:

{
  "mcpServers": {
    "long-running-server": {
      "command": "python",
      "args": ["-m", "myserver"],
      "timeout": 300000,
      "env": {
        "MCP_SERVER_REQUEST_TIMEOUT": "300"
      }
    }
  }
}

Environment Variables:

export MCP_REQUEST_TIMEOUT=300      # seconds
export MCP_CONNECTION_TIMEOUT=30    # seconds

Python FastMCP:

from fastmcp import FastMCP

mcp = FastMCP(
    "myserver",
    version="0.1.0",
    request_timeout=300  # 5 minutes
)

Solution 2: Send Progress Notifications

For long-running operations, send progress updates every 5-10 seconds:

# Python with progress reporting
async def long_running_tool(ctx):
    total_steps = 100
    for i in range(total_steps):
        # Do work...
        await ctx.report_progress(
            i + 1,
            total_steps,
            f"Processing step {i + 1}/{total_steps}"
        )

Note: TypeScript SDK has a hard 60-second limit that doesn't reset with progress updates. Use Python SDK for very long operations.

Solution 3: Implement Pagination

For large data operations, break into smaller chunks:

@server.call_tool()
async def search_large_dataset(query: str, page: int = 1, limit: int = 100):
    """Search with pagination to avoid timeout."""
    offset = (page - 1) * limit
    results = await db.query(query, offset=offset, limit=limit)
    return {
        "results": results,
        "page": page,
        "hasMore": len(results) == limit
    }

Failed to Build Actions from MCP Endpoint

This error commonly occurs with OpenAI's Agent Builder, ChatGPT Actions, and n8n when connecting to MCP servers.

Symptoms

Error: "Failed to build actions from MCP endpoint"
Error: "Error creating connector"
HTTP 424 "Failed Dependency" status
Connection works in MCP Inspector but fails in platform

Solution 1: Verify Protocol Compliance

Ensure your MCP server returns valid JSON-RPC 2.0 responses:

# Test with curl
curl -X POST http://localhost:8080/mcp \
  -H "Content-Type: application/json" \
  -d '{"jsonrpc":"2.0","method":"tools/list","id":1}'

Expected response format:

{
  "jsonrpc": "2.0",
  "id": 1,
  "result": {
    "tools": [...]
  }
}

Solution 2: Check Required Actions

Some platforms require specific actions to be implemented:

# Ensure required methods are implemented
@server.list_tools()
async def list_tools():
    return [
        {
            "name": "search",  # Some platforms require 'search'
            "description": "Search functionality",
            "inputSchema": {
                "type": "object",
                "properties": {
                    "query": {"type": "string"}
                },
                "required": ["query"]
            }
        }
    ]

Solution 3: Fix Authentication Flow

For OAuth-protected endpoints:

{
  "mcpServers": {
    "authenticated-server": {
      "command": "node",
      "args": ["server.js"],
      "env": {
        "API_KEY": "your-api-key",
        "OAUTH_CLIENT_ID": "your-client-id",
        "OAUTH_CLIENT_SECRET": "your-client-secret"
      }
    }
  }
}

Solution 4: Verify Endpoint Accessibility

# Check if endpoint is reachable
curl -I http://localhost:8080/mcp

# Check for CORS issues (for web-based clients)
curl -H "Origin: https://chat.openai.com" \
     -H "Access-Control-Request-Method: POST" \
     -X OPTIONS http://localhost:8080/mcp

Error Connecting to MCP Inspector Proxy

The MCP Inspector is essential for debugging, but proxy connection errors can prevent testing.

Symptoms

Error: "Error Connecting to MCP Inspector Proxy - Check Console logs"
Error: "Connection Error - Check if your MCP server is running"
ERR_CONNECTION_REFUSED in browser console
Inspector frontend shows connection error

Solution 1: Use the Auth Token URL

The MCP Inspector requires authentication. Use the URL with the token:

# When you start the inspector, look for this line:
# "Open inspector with token pre-filled: http://localhost:6274/?MCP_PROXY_AUTH_TOKEN=..."

# Copy and use that FULL URL, not just http://localhost:6274

Solution 2: Use npx Directly Instead of mcp dev

# ❌ May fail to connect
mcp dev server.py

# ✅ Works more reliably
npx @modelcontextprotocol/inspector uv run server.py

# For Node.js servers
npx @modelcontextprotocol/inspector node server.js

Solution 3: Check Port Conflicts

The Inspector uses two ports: 6274 (UI) and 6277 (proxy).

# Check for port conflicts
lsof -i :6274
lsof -i :6277
netstat -an | grep -E "6274|6277"

# Kill conflicting processes if needed
kill $(lsof -t -i:6274)
kill $(lsof -t -i:6277)

Solution 4: Configure Custom Ports

# Use custom ports if defaults are occupied
CLIENT_PORT=8080 SERVER_PORT=9000 npx @modelcontextprotocol/inspector node server.js

Solution 5: Fix Remote Access Issues

For remote servers, set environment variables:

HOST=0.0.0.0 \
ALLOWED_ORIGINS=http://your-client-ip:6274 \
npx @modelcontextprotocol/inspector python /path/to/server.py

Solution 6: Use External Terminal

VS Code integrated terminal can cause issues. Try external terminal:

Open external terminal (Terminal.app, PowerShell, etc.)
Run the inspector command there
Access the inspector URL from browser

Solution 7: Append /mcp/ for SSE/HTTP Transport

When using SSE or Streamable HTTP:

# ❌ WRONG - Missing trailing path
http://localhost:8080

# ✅ CORRECT - Include /mcp/ suffix
http://localhost:8080/mcp/

Claude Code MCP Server Troubleshooting

Claude Code has specific requirements for MCP server configuration.

Common Claude Code MCP Issues

Issue: "Server disconnected" or timeout errors

Solution: Use absolute paths and proper environment:

# Find your paths first
which node
which python3
which uv

{
  "mcpServers": {
    "filesystem": {
      "command": "/opt/homebrew/bin/node",
      "args": ["/full/path/to/server/index.js"],
      "env": {
        "NODE_ENV": "production"
      }
    }
  }
}

Issue: Context Pollution

If MCP prompts are being ignored or behaving unexpectedly:

# Clear context and conversation history
/clear

Issue: Cannot find MCP server logs

Claude Code logs are located at:

macOS: ~/Library/Logs/Claude/mcp*.log
Windows: %APPDATA%\Claude\logs\mcp.log
Linux: ~/.config/claude/logs/mcp.log

# Monitor logs in real-time
tail -f ~/Library/Logs/Claude/mcp.log

Claude Code MCP Commands

# Add an MCP server
claude mcp add myserver --scope user

# List configured servers
claude mcp list

# Remove a server
claude mcp remove myserver

# Test server configuration
claude mcp get myserver

Debugging Claude Code MCP Issues

Enable verbose logging:

{
  "mcpServers": {
    "myserver": {
      "command": "node",
      "args": ["--inspect", "server.js"],
      "env": {
        "DEBUG": "*",
        "MCP_VERBOSE": "true"
      }
    }
  }
}

Test manually first:

# Send a test JSON-RPC message
echo '{"jsonrpc":"2.0","method":"ping","id":1}' | node your-server/index.js

Server Transport and Connection Issues

"Server transport closed unexpectedly" Error

This indicates your server is crashing during startup or failing to maintain connection.

1. Incorrect Command Line Arguments

# ❌ Wrong - Missing required parameters
mcp-server start

# ✅ Correct - Include all required arguments
mcp-server start --port 8080 --host localhost

Debug Steps:

Run the server command manually in terminal
Check server documentation for required parameters
Verify all environment variables are set
Test with minimal configuration first

2. Port Conflicts

# Check if port is already in use
netstat -an | grep :8080
lsof -i :8080

# Solution: Use different port or kill conflicting process
mcp-server start --port 8081
# Or kill the conflicting process
kill $(lsof -t -i:8080)

3. Permission Issues

# Fix permission denied errors
chmod +x mcp-server-executable
sudo chown $USER:$USER /path/to/mcp-server

# For Windows PowerShell execution policy
Set-ExecutionPolicy RemoteSigned -Scope CurrentUser

"SSE connection not established" Error

Server-Sent Events (SSE) connection failures prevent MCP clients from communicating with servers.

1. Firewall Configuration

# Allow MCP server port through firewall (Linux/Mac)
sudo ufw allow 8080

# For Windows
netsh advfirewall firewall add rule name="MCP Server" protocol=TCP dir=in localport=8080 action=allow

2. Host Binding Issues

// ❌ Wrong - Only binds to localhost
{
  "host": "127.0.0.1",
  "port": 8080
}

// ✅ Correct - Allows external connections
{
  "host": "0.0.0.0",
  "port": 8080
}

3. SSE to Streamable HTTP Migration

SSE transport is deprecated as of MCP specification 2025-03-26. Migrate to HTTP Stream:

// Old SSE configuration
{
  "type": "sse",
  "url": "http://localhost:8080/sse"
}

// New HTTP Stream configuration
{
  "type": "http-stream",
  "url": "http://localhost:8080/mcp"
}

Backwards compatibility check:

# Test if server supports new transport
curl -X POST http://localhost:8080/mcp \
  -H "Content-Type: application/json" \
  -d '{"jsonrpc":"2.0","method":"initialize","params":{},"id":1}'

# If 405/404, server uses old SSE - use GET instead
curl http://localhost:8080/sse

Configuration File Problems

Claude Desktop Configuration Issues

File Locations:

Windows: %APPDATA%\Claude\claude_desktop_config.json
macOS: ~/Library/Application Support/Claude/claude_desktop_config.json
Linux: ~/.config/claude/claude_desktop_config.json

Common Configuration Errors

1. Invalid JSON Syntax

// ❌ Wrong - Trailing comma (VERY common mistake)
{
  "mcpServers": {
    "my-server": {
      "command": "node",
      "args": ["server.js"],
    }
  }
}

// ✅ Correct - Valid JSON
{
  "mcpServers": {
    "my-server": {
      "command": "node",
      "args": ["server.js"]
    }
  }
}

Validation Steps:

# Validate JSON syntax
python3 -m json.tool claude_desktop_config.json

# Node.js validation
node -e "console.log(JSON.parse(require('fs').readFileSync('claude_desktop_config.json', 'utf8')))"

2. Incorrect Path Specifications

// ❌ Wrong - Relative paths can fail
{
  "command": "./server.js"
}

// ✅ Correct - Absolute paths are reliable
{
  "command": "/full/path/to/server.js"
}

// ✅ Also correct - Using npx for npm packages (with cmd on Windows)
{
  "command": "npx",
  "args": ["-y", "@modelcontextprotocol/server-filesystem"]
}

3. Missing Environment Variables

{
  "mcpServers": {
    "database-server": {
      "command": "python",
      "args": ["-m", "database_mcp"],
      "env": {
        "DATABASE_URL": "postgresql://localhost/mydb",
        "API_KEY": "your-api-key-here",
        "PYTHONUNBUFFERED": "1"
      }
    }
  }
}

VS Code and Cursor Configuration

VS Code Configuration Path: ~/Library/Application Support/Code/User/mcp.json

Cursor Configuration Path: ~/.cursor/mcp.json

Example Configuration:

{
  "mcpServers": {
    "filesystem": {
      "command": "mcp-filesystem",
      "args": ["--root", "/workspace"]
    }
  }
}

Platform-Specific Issues

Windows-Specific Problems

1. spawn npx ENOENT Error

This is the most common Windows error. npx.cmd is a batch script that requires shell execution.

Solution 1 - cmd /c wrapper:

{
  "command": "cmd",
  "args": ["/c", "npx", "-y", "@modelcontextprotocol/server-sequential-thinking"]
}

Solution 2 - PowerShell:

{
  "command": "powershell",
  "args": ["-Command", "npx @modelcontextprotocol/server-github"]
}

Solution 3 - Direct node.exe with absolute paths:

{
  "command": "C:\\Program Files\\nodejs\\node.exe",
  "args": [
    "C:\\Users\\Username\\AppData\\Roaming\\npm\\node_modules\\@modelcontextprotocol\\server-github\\dist\\index.js"
  ]
}

2. Path Issues with Spaces

// ❌ Wrong - Spaces cause issues
{
  "command": "C:\\Program Files\\Node\\node.exe"
}

// ✅ Correct - Use forward slashes (works on Windows)
{
  "command": "C:/Program Files/nodejs/node.exe"
}

3. PowerShell Execution Policy

# Check current execution policy
Get-ExecutionPolicy

# Allow script execution (as Administrator)
Set-ExecutionPolicy RemoteSigned -Scope CurrentUser

macOS-Specific Problems

1. Gatekeeper Security

# Remove quarantine attribute from downloaded executables
xattr -d com.apple.quarantine /path/to/mcp-server

2. Homebrew Path Changes

Homebrew paths changed in 2023. Update old configs:

// Old path (Intel Macs)
{
  "command": "/usr/local/bin/node"
}

// New path (Apple Silicon)
{
  "command": "/opt/homebrew/bin/node"
}

3. GUI App PATH Isolation

Create a wrapper script that exports proper PATH:

#!/bin/bash
# Save as ~/bin/mcp-node-wrapper.sh
export PATH="/opt/homebrew/bin:/usr/local/bin:$PATH"
exec /opt/homebrew/bin/node "$@"

Linux-Specific Problems

1. Missing Dependencies

# Install common MCP server dependencies
sudo apt update
sudo apt install python3-pip nodejs npm

# For Python-based servers
pip3 install mcp fastmcp

# For Node.js-based servers
npm install -g @modelcontextprotocol/sdk

2. Systemd Service Configuration

# Create systemd service for MCP server
sudo tee /etc/systemd/system/mcp-server.service > /dev/null <<EOF
[Unit]
Description=MCP Server
After=network.target

[Service]
Type=simple
User=mcp
Environment=NODE_ENV=production
ExecStart=/usr/local/bin/node /opt/mcp-server/index.js
Restart=always
RestartSec=10

[Install]
WantedBy=multi-user.target
EOF

# Enable and start service
sudo systemctl daemon-reload
sudo systemctl enable mcp-server
sudo systemctl start mcp-server
sudo systemctl status mcp-server

Python MCP Server Debugging

Common Python MCP Issues

1. PYTHONUNBUFFERED for Real-time Output

{
  "mcpServers": {
    "python-server": {
      "command": "python",
      "args": ["-u", "-m", "myserver"],
      "env": {
        "PYTHONUNBUFFERED": "1"
      }
    }
  }
}

2. Virtual Environment Issues

{
  "mcpServers": {
    "python-server": {
      "command": "/path/to/venv/bin/python",
      "args": ["-m", "myserver"],
      "env": {
        "VIRTUAL_ENV": "/path/to/venv",
        "PATH": "/path/to/venv/bin:$PATH"
      }
    }
  }
}

3. uv Tool Path Issues

# Find uv path
which uv
where uv  # Windows

# Use full path in configuration
{
  "command": "/Users/yourname/.local/bin/uv",
  "args": ["run", "server.py"]
}

4. FastMCP + Uvicorn Issues

# For FastMCP with SSE/HTTP transport
from fastmcp import FastMCP

mcp = FastMCP(
    "myserver",
    stateless_http=True  # Add this for HTTP transport
)

# Don't use workers with MCP
# ❌ uvicorn main:app --workers 4  # Causes 404 errors
# ✅ uvicorn main:app              # Single worker

5. BrokenPipeError

If you see BrokenPipeError, the connection closes before server initialization:

import signal
import sys

def handle_sigpipe(signum, frame):
    sys.exit(0)

signal.signal(signal.SIGPIPE, handle_sigpipe)

Authentication and OAuth Errors

OAuth 2.1 Authentication Issues

Common Error Messages:

"401 Unauthorized"
"Invalid token"
"OAuth flow failed"

1. Token Validation Problems

# Decode JWT token to check expiration
echo "YOUR_TOKEN" | cut -d. -f2 | base64 -d | jq .exp

# Compare with current timestamp
date +%s

Implement Token Refresh:

async function refreshTokenIfNeeded(token) {
  const decoded = jwt.decode(token);
  const now = Date.now() / 1000;

  if (decoded.exp < now + 300) { // Refresh 5 minutes before expiry
    return await refreshAccessToken();
  }
  return token;
}

2. GitHub MCP Server Authentication

# Install GitHub CLI and authenticate
gh auth login

# Generate personal access token with required scopes
gh auth token

Required Scopes:

repo - Repository access
read:org - Organization information
workflow - GitHub Actions (if needed)

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

3. Home Assistant MCP Server Authentication

Error: "Client error '401 Unauthorized'"

Generate Long-Lived Access Token in Home Assistant Profile → Security
Configure MCP Server:

{
  "mcpServers": {
    "homeassistant": {
      "command": "mcp-homeassistant",
      "args": [
        "--token", "YOUR_LONG_LIVED_TOKEN",
        "--url", "http://localhost:8123"
      ]
    }
  }
}

Advanced Debugging Techniques

Enable Debug Logging

# Set debug environment variables
export MCP_DEBUG=1
export MCP_LOG_LEVEL=debug
export DEBUG=mcp:*

# Run server with verbose output
mcp-server start --verbose --log-level debug

Network Traffic Analysis

# Monitor network traffic on MCP port
sudo tcpdump -i lo0 port 8080

# Use Wireshark with filter: tcp.port == 8080

Process Monitoring

# Monitor server process
ps aux | grep mcp-server
top -p $(pgrep mcp-server)

# Check file descriptors
lsof -p $(pgrep mcp-server)

# Windows Process Explorer for crashed processes
# Shows processes even after they exit

Manual Server Testing

# Test server with raw JSON-RPC messages
echo '{"jsonrpc":"2.0","method":"initialize","params":{"protocolVersion":"2024-11-05","capabilities":{},"clientInfo":{"name":"test","version":"1.0"}},"id":1}' | node server.js

# Test HTTP endpoint
curl -X POST http://localhost:8080/mcp \
  -H "Content-Type: application/json" \
  -d '{"jsonrpc":"2.0","method":"tools/list","id":1}'

Configuration Validation Script

#!/usr/bin/env python3
"""Validate MCP server configuration."""
import json
import os
import sys
import subprocess

def validate_config(config_path):
    # Load and validate JSON
    with open(config_path) as f:
        config = json.load(f)

    assert 'mcpServers' in config, "Missing mcpServers key"

    for name, server_config in config['mcpServers'].items():
        assert 'command' in server_config, f"Missing command for {name}"

        # Check if command exists
        cmd = server_config['command']
        result = subprocess.run(['which', cmd], capture_output=True)
        if result.returncode != 0:
            print(f"WARNING: Command '{cmd}' not found in PATH")

        print(f"✓ Server '{name}' configuration valid")

if __name__ == "__main__":
    config_path = sys.argv[1] if len(sys.argv) > 1 else "claude_desktop_config.json"
    validate_config(config_path)

Quick Reference Troubleshooting Table

| Error | Most Likely Cause | Quick Fix | |-------|-------------------|-----------| | MCP error -32000: Connection closed | stdout pollution | Use console.error() instead of console.log() | | spawn npx ENOENT (Windows) | npx is batch script | Use cmd /c npx wrapper | | MCP error -32001: Request timed out | Operation exceeds 60s | Increase timeout, send progress updates | | Error connecting to MCP Inspector | Missing auth token | Use full URL with MCP_PROXY_AUTH_TOKEN | | Server transport closed unexpectedly | Config syntax error | Validate JSON, check for trailing commas | | 401 Unauthorized | Invalid/expired token | Regenerate API token | | Cannot find module | Missing dependencies | Run npm install or pip install | | Permission denied | File not executable | Run chmod +x server.js | | Connection refused | Server not running | Start server, check port | | EACCES | Permission error | Check file permissions, run as correct user |

Complete Troubleshooting Checklist

Before Starting:

[ ] Check MCP server logs for specific error messages
[ ] Validate configuration file syntax (JSON validation)
[ ] Confirm all required dependencies are installed
[ ] Test network connectivity to server endpoint
[ ] Check for port conflicts and permission issues

For Error -32000 (Connection Closed):

[ ] Verify all logging uses stderr, not stdout
[ ] Use absolute paths for commands
[ ] On Windows, use cmd /c wrapper for npx
[ ] Test server directly in terminal first
[ ] Check for missing environment variables

For Error -32001 (Timeout):

[ ] Increase timeout in configuration
[ ] Implement progress notifications for long operations
[ ] Break large operations into smaller chunks
[ ] Check network latency

For Inspector Proxy Errors:

[ ] Use URL with auth token from terminal output
[ ] Try npx @modelcontextprotocol/inspector directly
[ ] Check for port conflicts (6274, 6277)
[ ] Use external terminal instead of VS Code integrated terminal

Common First Steps:

Restart the MCP server - Solves many temporary issues
Check configuration file location - Ensure you're editing the right file
Verify command paths - Use absolute paths when possible
Test with minimal configuration - Start simple and add complexity
Check server logs - Look for specific error messages

Nuclear Reset Option:

If standard fixes fail:

Quit application completely: killall Claude
Backup and remove config file
Clear caches (macOS): rm -rf ~/Library/Caches/com.anthropic.claude*
Reinstall Node: brew install node@20 && brew link node@20
Create minimal test config
Restart and verify
Gradually add servers back

Try These Integrations

Once you've resolved your issues, explore popular MCP integrations:

Use GitHub MCP with Claude Code - Repository management
Use Notion MCP with Cursor - Knowledge base integration
Use PostgreSQL MCP with Claude Desktop - Database access
Use Slack MCP with Windsurf - Team communication

Resources and Support

Official Documentation

Community Resources

Additional Tools

MCP Inspector - Debug and test servers
MCP Python SDK - Python development
MCP TypeScript SDK - TypeScript development

Related Guides

Complete MCP Server Setup Guide - Initial setup and configuration
MCP Authentication Guide - Detailed auth solutions
MCP Implementation Checklist - Best practices

This troubleshooting guide is updated regularly based on community feedback, new MCP developments, and emerging error patterns. Last updated: December 2025.