Fix: MCP Server Connection Failed — Complete Troubleshooting Guide

The Problem

You configured an MCP server in Claude Code (or another MCP-compatible agent), but when you try to use it:

Error: MCP Server Connection Failed
Error: Failed to connect to MCP server "my-server"
Error: MCP server disconnected unexpectedly
MCP Error: ENOENT — spawn npx ENOENT

MCP (Model Context Protocol) servers extend your AI agent with custom tools, databases, and APIs. When they fail to connect, your AI agent loses those capabilities.

This guide covers every common MCP connection failure and how to fix it.

---

Step 1: Verify Your MCP Server Configuration

The most common cause of connection failures is a misconfigured settings.json or claude_desktop_config.json.

Check Your Config File

Claude Code reads MCP server configuration from .claude/settings.json:

{
  "mcpServers": {
    "filesystem": {
      "command": "npx",
      "args": [
        "-y",
        "@modelcontextprotocol/server-filesystem",
        "/path/to/allowed/directory"
      ]
    },
    "sqlite": {
      "command": "uvx",
      "args": [
        "mcp-server-sqlite",
        "--db-path",
        "/tmp/test.db"
      ]
    }
  }
}

Common Config Mistakes

Mistake 1: Wrong command path

// ❌ Wrong — assumes global install
{
  "command": "mcp-server-filesystem"
}
// ✅ Correct — uses npx to run from npm
{
  "command": "npx",
  "args": ["-y", "@modelcontextprotocol/server-filesystem", "/path"]
}

Mistake 2: Missing required arguments

Each MCP server has specific required args. Check the server's documentation.

Mistake 3: Invalid JSON

A trailing comma or missing quote will silently fail. Use a JSON validator:

cat .claude/settings.json | python3 -m json.tool

External Links: - MCP Server Configuration Documentation - JSON Validator — validate your config before using it - MCP Servers Beginner's Guide — understand how MCP servers work

---

Step 2: Check If the MCP Server Can Run Independently

Before debugging the integration, verify the MCP server starts on its own:

# Try running it manually — same command as in your config
npx -y @modelcontextprotocol/server-filesystem /tmp/test
# If you see output like "MCP server running on stdio", it works
# If you get an error, the server itself has a problem

Common Server-Level Errors

"Command not found" or "ENOENT"

The tool you're trying to run isn't installed:

# For npx-based servers:
npx --version  # Should show a version number
# For uvx-based servers (Python MCP servers):
uvx --version  # Should show a version number

Fix: Install the required tools

# Install Node.js/npx (if missing)
# Download from https://nodejs.org/
# Install uv/uvx (for Python MCP servers)
pip install uv
# Or: curl -LsSf https://astral.sh/uv/install.sh | sh

"Module not found" or "Cannot find package"

# Fix: Try installing with explicit cache bypass
npx -y @modelcontextprotocol/server-filesystem --help
# Or install globally first
npm install -g @modelcontextprotocol/server-filesystem

External Links: - Node.js Download — install Node.js and npx - uv: Python Package Manager — for Python-based MCP servers

---

Step 3: Verify Network Access

Some MCP servers need network access (e.g., database servers, API servers):

# Test basic network connectivity
curl -v https://api.example.com
# Check if a port is listening
nc -zv localhost 5432  # Check PostgreSQL
nc -zv localhost 3306  # Check MySQL

Port Conflicts

If your MCP server needs a specific port, make sure it's available:

# Check if port is in use
sudo lsof -i :5432
# Or
netstat -tulpn | grep :5432
# Kill the process using the port
kill -9 

---

Step 4: Check File System Permissions

MCP servers that access the file system need permission to read/write:

# Check if the allowed directory exists
ls -la /path/to/allowed/directory
# Check permissions
stat /path/to/allowed/directory
# Fix permissions
chmod 755 /path/to/allowed/directory
chown -R $(whoami) /path/to/allowed/directory

For the Filesystem MCP Server

The @modelcontextprotocol/server-filesystem server restricts access to specified directories:

{
  "mcpServers": {
    "filesystem": {
      "command": "npx",
      "args": [
        "-y", 
        "@modelcontextprotocol/server-filesystem",
        "/home/user/projects",  // Only allow access to these
        "/tmp/shared"           // directories
      ]
    }
  }
}

If you get "Access denied" or "Path not allowed" errors, add the directory to the allowed paths.

---

Step 5: Check MCP Server Logs

Claude Code logs MCP server activity. Check these for detailed error messages:

# Claude Code logs location (macOS/Linux)
cat ~/.claude/logs/mcp-server-*.log
# Windows
type %USERPROFILE%\.claude\logs\mcp-server-*.log
# Check the most recent log
ls -t ~/.claude/logs/ | head -5
cat ~/.claude/logs/$(ls -t ~/.claude/logs/ | head -1)

Look for: - [error] — explicit errors - [stderr] — stderr output from the server process - SIGTERM / SIGKILL — server was killed (possibly OOM or timeout) - ECONNREFUSED — the server isn't listening on expected port

---

Step 6: Debugging by Server Type

SQLite MCP Server

{
  "mcpServers": {
    "sqlite": {
      "command": "uvx",
      "args": ["mcp-server-sqlite", "--db-path", "/tmp/test.db"]
    }
  }
}

Common issues: - uvx not installed → pip install uv - Database path doesn't exist → create it: touch /tmp/test.db - Permission denied on db file → check directory ownership

External Links: - MCP SQLite Server on GitHub

GitHub MCP Server

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

Common issues: - Missing or expired GITHUB_TOKEN → generate a new token - Token permissions too restrictive → needs repo and read:org scopes - Rate limiting → GitHub API has a limit of 5000 requests/hour

External Links: - GitHub Personal Access Tokens - GitHub API Rate Limiting

PostgreSQL MCP Server

{
  "mcpServers": {
    "postgres": {
      "command": "npx",
      "args": ["-y", "@anthropic/mcp-postgres", "postgresql://user:pass@localhost:5432/mydb"]
    }
  }
}

Common issues: - Connection string format wrong → postgresql://user:password@host:port/database - Database is running? → pg_isready - Firewall blocking → check pg_hba.conf

---

Step 7: Restart Claude Code

After making any config changes, restart Claude Code:

# Exit current session
/exit
# Start a new session — it will re-read the config
claude

If you're using Claude Desktop instead of Claude Code, restart the desktop app after config changes.

---

Advanced Debugging: Run MCP Server in Stdio Mode

For deep debugging, run the MCP server directly and pipe it to a test client:

# Run the server and capture output
npx -y @modelcontextprotocol/server-filesystem /tmp/test 2>&1 | tee mcp-debug.log
# In another terminal, send a test request:
echo '{"jsonrpc": "2.0", "id": 1, "method": "tools/list"}' | nc -U /tmp/mcp.sock

---

Quick Reference Table

| Error Message | Likely Cause | Fix | |---------------|-------------|-----| | "Connection Failed" | Server didn't start | Test server independently (Step 2) | | "ENOENT" | Tool not installed | Install npx, uvx, or the server package | | "ENOTFOUND" | DNS resolution | Check network and proxy settings | | "ECONNREFUSED" | Server not listening | Check port, check if server is running | | "Access Denied" | File permissions | Fix directory ownership or add to allowed paths | | "Module not found" | Missing npm package | Try with -y flag or install globally | | "Timeout" | Server too slow | Increase timeout in settings.json | | "Invalid JSON" | Config file error | Validate JSON with python3 -m json.tool |

---

Prevention: MCP Server Setup Checklist

# 1. Validate config JSON
python3 -m json.tool .claude/settings.json
# 2. Test server independently
npx -y YOUR-SERVER-PACKAGE --help
# 3. Check permissions
ls -la /path/to/server/directory
# 4. Check network if applicable
curl -v https://your-api-server.com
# 5. Restart Claude Code
claude

Related Articles: - MCP Servers Beginner's Guide — understand what MCP servers are - Claude Code Memory Systems Explained — how MCP expands agent capabilities - Setting Up Claude Code + OpenClaw — advanced configuration patterns - Claude Code Hooks vs MCP Servers — when to use each