MCP Server Connection Issues

Encountering connection issues with MCP servers? This comprehensive guide covers common problems, platform-specific solutions, and best practices for establishing reliable MCP connections.

Understanding MCP Connection Architecture

Before diving into troubleshooting, it’s essential to understand how MCP connections work:

Connection Flow

1. Client Discovery: Cursor/Claude Code discovers MCP servers from configuration
2. Process Launch: Client spawns server process using specified command
3. Transport Negotiation: Client and server establish communication channel
4. Tool Registration: Server advertises available tools to client
5. Keep-Alive: Connection maintained with periodic health checks

Common Connection Issues

1. “No Tools Found” or Server Not Visible

This is the most common issue when setting up MCP servers.

Cursor IDE

Symptoms:

• Red indicator next to MCP server
• “No tools found” message
• Server not appearing in tool list

Solutions:

# 1. Verify MCP server is enabled
cursor --version  # Ensure v0.45+ for MCP support

# 2. Check configuration syntax
cat ~/.cursor/mcp.json  # or project-specific .cursor/mcp.json

# 3. Restart Cursor completely
# Close all windows including background processes

Configuration Check:

{
  "mcpServers": {
    "your-server": {
      "command": "npx",
      "args": ["-y", "@your-scope/server-name"]
    }
  }
}

Claude Code

Symptoms:

• Server doesn’t appear in tool list
• No MCP tools available in chat
• Connection timeout messages

Solutions:

# 1. List configured servers
claude mcp list

# 2. Test server manually
claude mcp test your-server-name

# 3. Enable debug mode
claude --mcp-debug

Configuration Example:

# Add server with SSE transport (e.g., Figma)
claude mcp add --transport sse figma-dev-mode http://127.0.0.1:3845/sse

2. “Client Closed” or “spawn ENOENT” Errors

These errors indicate the server process failed to start.

1. Clear NPX Cache

   npx clear-npx-cache
   npm cache clean --force

2. Verify Dependencies

   # Check Node.js version (requires 18+)
   node --version
   
   # Ensure npx is available
   npx --version

3. Test Manual Execution

   # Try running the server command directly
   npx -y @modelcontextprotocol/server-example

4. Check PATH Configuration

   Windows

   # Add Node.js to PATH
   $env:Path += ";C:\Program Files\nodejs"
   
   # For permanent fix, add via System Properties

   macOS/Linux

   # Add to shell profile
   export PATH="/usr/local/bin:$PATH"

3. Authentication and Permission Issues

Common Auth Problems

• API keys not configured
• OAuth flow failures
• File system permissions
• Firewall blocking localhost

Solutions by Type:

API Keys

{
  "mcpServers": {
    "api-server": {
      "command": "npx",
      "args": ["-y", "@example/server"],
      "env": {
        "API_KEY": "your-key-here",
        "API_SECRET": "your-secret"
      }
    }
  }
}

Tip

Store sensitive keys in environment variables:

export MY_API_KEY="secret-key"

Then reference in config:

"env": {
  "API_KEY": "${MY_API_KEY}"
}

OAuth Issues

For OAuth-based servers (e.g., remote MCP):

# Claude Code OAuth flow
claude mcp add --transport sse remote-server https://api.example.com/mcp

# Follow OAuth prompts in browser
# Check for popup blockers

Troubleshooting:

• Ensure redirect URLs are whitelisted
• Check browser console for errors
• Verify OAuth app configuration

File Permissions

# Fix permission issues on Unix systems
chmod +x ~/.npm/_npx/*/node_modules/*/dist/index.js

# For global installs
sudo npm install -g @modelcontextprotocol/server-name

Platform-Specific Issues

Windows-Specific Problems

PowerShell Execution Issues

Windows users often encounter PowerShell-specific problems with MCP servers.

Problem: Empty PowerShell windows or execution policy errors

Solutions:

# 1. Set execution policy
Set-ExecutionPolicy -ExecutionPolicy RemoteSigned -Scope CurrentUser

# 2. Use full paths instead of npx
{
  "mcpServers": {
    "server-name": {
      "command": "node",
      "args": ["C:\\Users\\YourName\\AppData\\Roaming\\npm\\node_modules\\@scope\\server\\dist\\index.js"]
    }
  }
}

# 3. Disable PowerShell window (Cursor specific)
# Add to server config:
"windowsHide": true

macOS-Specific Issues

1. Gatekeeper Blocks

   # If macOS blocks execution
   xattr -d com.apple.quarantine /path/to/mcp/server

2. Port Access

   # Check if port is in use
   lsof -i :3845  # For Figma MCP example

3. Homebrew Node Issues

   # Ensure correct Node version
   brew update
   brew upgrade node

Linux Permission Errors

# Common fixes for Linux
# 1. Avoid global npm installs with sudo
mkdir ~/.npm-global
npm config set prefix '~/.npm-global'
echo 'export PATH=~/.npm-global/bin:$PATH' >> ~/.bashrc
source ~/.bashrc

# 2. Fix npm permissions
sudo chown -R $(whoami) ~/.npm

# 3. Use node version manager
curl -o- https://raw.githubusercontent.com/nvm-sh/nvm/v0.39.0/install.sh | bash
nvm install 20
nvm use 20

Network and Firewall Issues

Local Server Connection Problems

Localhost Issues

# Test localhost connectivity
curl http://127.0.0.1:3845/sse  # Example for Figma

# Alternative: use 0.0.0.0
{
  "url": "http://0.0.0.0:3845/sse"
}

Firewall Rules

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

# macOS
sudo pfctl -f /etc/pf.conf

# Linux (ufw)
sudo ufw allow 3845/tcp

Corporate Proxies

For corporate networks with proxies:

{
  "mcpServers": {
    "server": {
      "command": "npx",
      "args": ["-y", "@scope/server"],
      "env": {
        "HTTP_PROXY": "http://proxy.company.com:8080",
        "HTTPS_PROXY": "http://proxy.company.com:8080",
        "NO_PROXY": "localhost,127.0.0.1"
      }
    }
  }
}

HTTP/2 Compatibility Issues

Caution

Some corporate networks don’t support HTTP/2, causing MCP failures.

Fix for Cursor:

1. Open Settings (Cmd/Ctrl + ,)
2. Search for “HTTP/2”
3. Enable “Disable HTTP/2”
4. Restart Cursor

Performance and Timeout Issues

Handling Large Operations

{
  "mcpServers": {
    "heavy-server": {
      "command": "node",
      "args": ["server.js"],
      "env": {
        "MCP_TIMEOUT": "30000",  // 30 seconds
        "NODE_OPTIONS": "--max-old-space-size=4096"
      }
    }
  }
}

Connection Pool Management

For multiple MCP servers:

// Example configuration for high-load scenarios
{
  "mcpServers": {
    "db-server": {
      "command": "npx",
      "args": ["@db/mcp-server"],
      "maxRestarts": 3,
      "restartDelay": 1000,
      "connectionPool": {
        "max": 10,
        "idleTimeout": 60000
      }
    }
  }
}

Advanced Troubleshooting

Debug Mode Investigation

Cursor

# Enable MCP debug logs
1. Ctrl+Shift+U (Cmd+Shift+U on Mac)
2. Select "MCP Logs" from dropdown
3. Look for:
   - Connection attempts
   - Authentication failures
   - Tool registration errors

Claude Code

# Run with debug flag
claude --mcp-debug

# Check specific server
claude mcp get server-name -v

# Monitor real-time logs
claude --debug 2>&1 | grep MCP

Process Management

# Find stuck MCP processes
# Windows
tasklist | findstr "node"
taskkill /F /PID <pid>

# macOS/Linux
ps aux | grep mcp
kill -9 <pid>

# Clean up orphaned processes
pkill -f "mcp-server"

Connection State Recovery

// Example recovery configuration
{
  "mcpServers": {
    "resilient-server": {
      "command": "npx",
      "args": ["@scope/server"],
      "reconnect": {
        "enabled": true,
        "maxAttempts": 5,
        "backoffMultiplier": 2,
        "initialDelay": 1000,
        "maxDelay": 30000
      },
      "healthCheck": {
        "enabled": true,
        "interval": 60000,
        "timeout": 5000
      }
    }
  }
}

Best Practices for Stable Connections

Configuration Management

• Use version control for MCP configs
• Separate dev/prod configurations
• Document required environment variables
• Test configs before deployment

Security Considerations

• Never hardcode sensitive credentials
• Use read-only database users
• Implement rate limiting
• Validate input parameters

Monitoring Setup

• Enable debug logs in development
• Set up health checks
• Monitor resource usage
• Track connection metrics

Error Handling

• Implement graceful degradation
• Add retry logic with backoff
• Log errors comprehensively
• Provide user-friendly messages

Quick Reference Checklist

When troubleshooting MCP connections, work through this checklist:

1. Version Check

   • Cursor v0.45+ or Claude Code latest
   • Node.js 18+ installed
   • NPM/NPX working correctly

2. Configuration Validation

   • Valid JSON syntax
   • Correct command and args
   • Required environment variables set

3. Network Verification

   • Server reachable on specified port
   • No firewall blocking
   • Proxy settings if applicable

4. Process Health

   • No orphaned processes
   • Sufficient system resources
   • Correct file permissions

5. Debug Information

   • Enable debug logs
   • Check error messages
   • Test manual execution

Getting Help

If you’re still experiencing issues:

1. Gather Debug Information

   # System info
   node --version
   npm --version
   cursor --version  # or claude --version
   
   # MCP config
   cat ~/.cursor/mcp.json  # or equivalent
   
   # Error logs
   # Copy from MCP Logs output

2. Check Community Resources

   • Cursor Community Forum
   • Anthropic Discord
   • MCP GitHub Discussions

3. Report Issues

   • Include full error messages
   • Specify platform and versions
   • Provide minimal reproduction steps
   • Mention what you’ve already tried

Tip

Most MCP connection issues are resolved by:

1. Clearing NPX cache
2. Restarting the application
3. Fixing configuration syntax
4. Setting required environment variables

Remember that MCP is evolving rapidly, so keep your tools updated and check release notes for breaking changes!