Claude MCP failed to connect

TL;DR:

• Most Claude MCP connection failures trace to one of four root causes: malformed JSON in claude_desktop_config.json, environment path conflicts (Node.js or Python not found), network timeouts, or server runtime errors.

• Start by categorizing your error using the diagnostic flowchart below, then apply the specific fix for that category.

• To skip local config debugging entirely, use a managed remote MCP endpoint. You get server-side execution, automatic auth handling, and 100,000 tool calls/month free, no credit card required.

You added an MCP server to Claude Desktop, restarted the app, and got "Claude MCP failed to connect." Now you're staring at a JSON config file wondering what went wrong. Local MCP debugging consumes hours that should go to building agent logic, and the error messages rarely tell you what's actually broken.

This guide categorizes the most common MCP connection failures into four buckets, gives you the specific fix for each. If you're debugging a connection right now, start with the diagnostic flowchart below.

Quick diagnostic flowchart

Use this decision tree to categorize your error quickly. Errors can overlap, but start with the most likely category. Start with the category that matches your symptoms, then jump to the relevant section below.

1. Config syntax errors: Claude Desktop silently fails if the JSON is malformed. No error dialog appears, no warning notification. MCP servers simply don't load.

2. Environment path conflicts: GUI apps don't inherit your shell PATH. If Claude can't find node or python3, the server won't start.

3. Network timeouts: Connection timeouts and transport mismatches are common when the server is slow to start or the port is blocked.

4. Server runtime errors: Stdio pollution from console.log() corrupts the JSON-RPC stream, causing Claude to terminate the connection instantly.

Common causes for MCP handshake failures

Troubleshooting malformed JSON configs

The most common cause of MCP failures is invalid JSON in the config file, and Claude Desktop silently fails when the syntax is wrong.

A valid claude_desktop_config.json follows this structure:

{
  "mcpServers": {
    "filesystem": {
      "command": "npx",
      "args": [
        "-y",
        "@modelcontextprotocol/server-filesystem",
        "/Users/you/projects"
      ]
    },
    "github": {
      "command": "npx",
      "args": [
        "-y",
        "@modelcontextprotocol/server-github"
      ],
      "env": {
        "GITHUB_PERSONAL_ACCESS_TOKEN": "ghp_xxxx"
      }
    }
  }
}

Common mistakes that break the config include args formatted as strings instead of arrays, env values as numbers instead of strings, and trailing commas.

Here's an invalid config with common errors annotated:

{
  "mcpServers": [  // ERROR: should be an object, not an array
    "filesystem": {
      "command": "npx",
      "args": "-y @modelcontextprotocol/server-filesystem /tmp",  // ERROR: args must be an array
      "env": {
        "PORT": 3000  // ERROR: env values must be strings
      },
    }  // ERROR: trailing comma
  ]
}

Most JSON parse errors trace to a trailing comma, an unquoted key, or a copy-pasted comment rather than a missing dependency.

Fixing environment variable path conflicts

PATH problems cause many Desktop MCP failures because GUI apps don't inherit your shell PATH. When you run node or python3 in your terminal, your shell resolves the command using the PATH environment variable, but Claude Desktop launches from a different context and can't find the executable.

To fix this, use an absolute path instead of relying on PATH lookup:

1. Run which node in your terminal to find the absolute path.

2. Run which python3 to find the Python path.

3. Use the full path in your config.

Example config with absolute paths:

{
  "mcpServers": {
    "filesystem": {
      "command": "/usr/local/bin/node",
      "args": [
        "/Users/you/mcp-servers/filesystem/index.js"
      ]
    },
    "python-server": {
      "command": "/usr/bin/python3",
      "args": [
        "/Users/you/mcp-servers/python-server/main.py"
      ]
    }
  }
}

If Claude cannot find npx or python, the PATH is usually the culprit.

Debugging internal MCP server runtime errors

Runtime errors happen when the server starts but crashes during the handshake. Common causes include missing dependencies, incompatible Node.js or Python versions, and unhandled exceptions.

Stdio pollution is a frequent culprit because in stdio transport, stdout is reserved strictly for JSON-RPC messages. If your code calls console.log("Starting server..."), the text corrupts the JSON-RPC stream and Claude terminates the connection instantly.

To debug runtime errors, run the server manually in a terminal before adding it to Claude Desktop.

Identifying root causes for MCP link drops

Inspect logs for MCP connection errors

Claude Desktop logs MCP connection errors to a file. On macOS, logs are at ~/Library/Logs/Claude/mcp.log. On Windows, logs are at %APPDATA%\Claude\logs\.

To tail logs in real time on macOS or Linux:

tail -n 20 -f ~/Library/Logs/Claude/mcp*.log

On Windows, open the log file in a text editor or use PowerShell:

Get-Content "$env:APPDATA\Claude\logs\mcp.log" -Tail 20 -Wait

Log paths may vary by installation. If you can't find the logs, check the Claude Desktop settings or search for mcp.log in your user directory.

Validate MCP JSON configuration syntax

Validate your JSON syntax using jq or a JSON linter. To validate with Python:

cat ~/Library/Application\ Support/Claude/claude_desktop_config.json | python3 -m json.tool

If there is a syntax error, Python will tell you exactly which line.

To validate with jq:

jq . ~/Library/Application\ Support/Claude/claude_desktop_config.json

If the JSON is valid, jq will pretty-print it. If it's invalid, jq will show the error and line number.

Perform manual MCP handshake tests

Test the server manually in your terminal by copying the exact command and arguments from your config:

npx -y @modelcontextprotocol/server-filesystem /tmp

The server should start without errors and wait for input on stdin (this is normal for stdio servers). Press Ctrl+C to stop. This isolates whether the failure is in the config or the server itself.

If the server runs cleanly in your terminal but fails in Claude Desktop, the problem is the config. If it fails in your terminal, the problem is the server.

Debug missing environment configuration

MCP servers often need environment variables like API keys, tokens, or paths. If these are missing, the server will fail to start or crash during the handshake.

To check if environment variables are set:

env | grep API_KEY

If the variable is not set, add it to your config file:

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

Environment variables in the config file are passed to the server process when Claude Desktop launches it.

Fixing Claude MCP connectivity issues fast

Resolve invalid MCP path definitions

Relative paths fail when Claude Desktop launches from a different working directory. Always use absolute paths in your config.

Incorrect (relative path):

{
  "command": "node",
  "args": ["./server.js"]
}

Correct (absolute path):

{
  "command": "/usr/local/bin/node",
  "args": ["/Users/you/mcp-servers/server.js"]
}

Path resolution failures happen because GUI applications don't resolve relative paths the same way terminals do.

Set up Python virtual environments

Python MCP servers fail when dependencies are installed globally and the server expects a virtual environment. To fix this, create a virtual environment and point the config file to the venv's Python binary:

python3 -m venv mcp-env
source mcp-env/bin/activate
pip install mcp-server

Then update your config:

{
  "mcpServers": {
    "python-server": {
      "command": "/Users/you/mcp-servers/mcp-env/bin/python",
      "args": ["/Users/you/mcp-servers/main.py"]
    }
  }
}

On Windows, the venv Python binary is at mcp-env\Scripts\python.exe. On macOS and Linux, it's at mcp-env/bin/python.

Resolve Node.js module load failures

MODULE_NOT_FOUND errors happen when the npm package failed to download or the server can't find its dependencies.

To fix this:

1. Run npm install in the server directory to download dependencies.

2. Use absolute paths in your config.

3. Set NODE_PATH if the server needs to resolve modules from a custom location.

Example config with NODE_PATH:

{
  "mcpServers": {
    "node-server": {
      "command": "/usr/local/bin/node",
      "args": ["/Users/you/mcp-servers/index.js"],
      "env": {
        "NODE_PATH": "/Users/you/mcp-servers/node_modules"
      }
    }
  }
}

Fix port availability for MCP servers

Port conflicts happen when multiple MCP servers try to use the same port. To check port usage on macOS or Linux:

lsof -i :3000

On Windows:

netstat -ano | findstr :3000

If the port is in use, either stop the conflicting process or change the port in your MCP server config. Most MCP servers accept a --port flag or an environment variable like PORT.

Example config with a custom port:

{
  "mcpServers": {
    "custom-server": {
      "command": "/usr/local/bin/node",
      "args": ["/Users/you/mcp-servers/index.js", "--port", "3001"]
    }
  }
}

Anatomy of an MCP connection

How MCP extends Claude Desktop

Think of MCP as a universal connector for AI. It lets Claude Desktop talk to external tools like filesystems, databases, and SaaS apps through a standardized protocol. When you add an MCP server to Claude Desktop, you're telling Claude how to launch and communicate with that server through a JSON config file.

The config lives in claude_desktop_config.json, and Claude reads it on startup. If anything in that config is wrong, the server won't connect.

Local vs. remote MCP setups

Local MCP servers run on the same machine as Claude Desktop. The config file specifies a command (like npx or python3) and arguments. Claude launches the server as a subprocess and communicates over stdio. Failure modes include malformed JSON, wrong paths, port conflicts, and runtime errors.

Remote MCP servers run on a managed gateway. Claude Desktop connects via URL. The gateway handles auth, token refresh, and sandboxing. Failure modes include network issues, auth errors, and token expiry.

Production failure modes for local MCP hosts

Syncing runtime configs for stable MCP

Config drift happens when local configs diverge across team members, causing "works on my machine" failures. If you don't version control claude_desktop_config.json, every developer ends up with a slightly different setup.

This is a maintenance treadmill, not a one-time fix. Every new MCP server requires config file edits, path checks, and dependency installs. Every team member has to replicate the same setup. When someone updates a dependency or changes a path, everyone else has to sync manually.

Addressing version drift and token expiry

Version drift happens when MCP server dependencies update and break the local install. A previously working integration breaks silently after a provider API update. "Works in the notebook" does not mean "works in production."

OAuth tokens from providers like Google and Slack expire periodically. Without automatic token refresh handling, local MCP servers fail silently when tokens expire during long-running agent sessions.

How Composio solves connection problems

Remove manual config for reliable sync

To connect Claude Desktop to Composio's managed MCP server, open Claude Desktop and go to Settings → Connectors → Add custom connector. Paste the endpoint URL:

https://connect.composio.dev/mcp

Claude will prompt you to complete OAuth on first connect. Once authenticated, the connection persists for future sessions. No edits to claude_desktop_config.json required.

If you prefer the config-file approach, use the mcp-remote bridge to proxy the remote connection.

{
  "mcpServers": {
    "composio": {
      "command": "npx",
      "args": ["-y", "mcp-remote", "https://connect.composio.dev/mcp"]
    }
  }
}

Composio's remote server handles execution routing and credential management. You don't manage any local config. If you prefer to manage things from the terminal, the Composio CLI is optional. Run composio login to authenticate the same connection.

How Composio routes tool calls

Composio's managed MCP server acts as a tool execution layer for your agents. When Claude needs to act (query a database, update a CRM record, send a Slack message), the gateway routes the request to the right tool, handles execution, and returns a structured result.

Authentication is one part of the execution pipeline, not a separate concern you manage manually. OAuth 2.0, API keys, and JWT tokens are handled automatically. When credentials are required mid-conversation, users authenticate once through a Connect Link URL and credentials persist for future sessions.

Token refresh happens mid-conversation without breaking the agent workflow.

Scaling with Composio

The free tier gives you access to 100,000 tool calls per month across 1,500+ integrations, including Gmail, Slack, GitHub, Google Drive, and hundreds more. No credit card required to start.

Get started with Composio. Free tier includes 100,000 tool calls/month. No credit card required.

FAQs

Why does Claude say MCP server failed to connect?

Usually one of four causes: malformed JSON in claude_desktop_config.json, environment path conflicts, network timeouts, or server runtime errors. Start with the diagnostic flowchart above.

How do I fix Claude MCP not connecting on Mac?

Check logs at ~/Library/Logs/Claude/, validate JSON syntax with jq, and verify Node.js or Python paths with which node or which python3. Fix the specific error category identified in the logs.

Can I use remote MCP servers with Claude Desktop?

Yes. Claude Desktop supports remote MCP servers via URL. Composio provides a managed remote MCP server that drops into Claude Desktop without local config.

What's the difference between local and hosted MCP servers?

Local MCP servers run on your machine and require config file management, path setup, and dependency installs. Hosted MCP servers run on a managed gateway with auth, token refresh, and sandboxing handled automatically.

How do I debug MCP connection failed errors?

Categorize the error using the diagnostic flowchart, inspect logs, validate JSON syntax, test the server manually, and check environment variables. If local debugging is consuming too much time, consider a remote gateway.

Key terms glossary

MCP (Model Context Protocol): A protocol that lets AI clients like Claude Desktop connect to external tools through a standardized interface. Think of it as a universal connector for AI.

stdio: A transport method where the MCP server runs as a subprocess and communicates over standard input/output. Common for local MCP servers.

JSON-RPC: The message format MCP uses for requests and responses between client and server. The -32000 to -32099 range is reserved for implementation-defined server errors; the TypeScript SDK uses -32001 for request timeouts, but that's an SDK convention, not a general JSON-RPC guarantee.

Handshake: The initial exchange between Claude Desktop and an MCP server to establish a connection. Failures here produce "failed to connect" errors.

Token refresh: The process of renewing expired OAuth tokens. Composio handles this automatically to prevent mid-conversation failures.