How to Fix Common MCP Server Connection Errors

MCP servers fail in predictable ways. The error messages are often unhelpful, but the underlying causes are almost always one of a handful of common problems. Find your error below and follow the fix.

TL;DR: 90% of MCP connection errors are: wrong npx path (use which npx and paste the absolute path), missing env vars (add them to the config env block, not your shell), invalid JSON (no trailing commas, no comments, double quotes only), or wrong config file location. Use the diagnostic flowchart and checklist at the bottom to systematically rule out each cause.

Diagnostic Flowchart

graph TD
    A[Connection error] --> B{Error message?}
    B -->|"ENOENT" or<br/>"command not found"| C[Use absolute path<br/>to npx in config]
    B -->|"connection refused"<br/>or "failed to start"| D{Run server<br/>manually in terminal}
    D -->|Shows missing<br/>env var error| E[Add env vars<br/>to config env block]
    D -->|Shows auth error| F[Regenerate API key<br/>and update config]
    D -->|Server starts OK| G[PATH issue — use<br/>absolute npx path]
    B -->|"JSON parse error"| H[Validate JSON:<br/>no trailing commas,<br/>double quotes only,<br/>no comments]
    B -->|Tools not<br/>showing up| I{Total tool count?}
    I -->|Over client limit| J[Remove servers<br/>to get under limit]
    I -->|Under limit| K[Check if server<br/>crashed after startup]
    B -->|No error,<br/>just not working| L[Verify config file<br/>is in correct location<br/>for your client]

Before You Debug Anything

Run these three commands first:

node --version                                           # Node.js installed?
which npx                                                # npx accessible?
npx -y @modelcontextprotocol/server-filesystem --help    # Package name correct?

If node --version fails, install Node.js 18+. If which npx returns nothing, your PATH is misconfigured. Most MCP server problems are Node.js, PATH, or credential problems wearing an MCP hat.

"Server Failed to Start"

The most common error across all clients. You add a server, restart, and it reports failure with no detail.

Cause 1: npx Not Found (PATH Issue)

GUI applications on macOS do not inherit your terminal's PATH. If you installed Node.js through nvm, fnm, or Homebrew, the npx binary is invisible to Claude Desktop, Cursor, and VS Code.

The fix: Use the full absolute path:

which npx
# Example: /Users/you/.nvm/versions/node/v20.11.0/bin/npx

{
  "mcpServers": {
    "github": {
      "command": "/Users/you/.nvm/versions/node/v20.11.0/bin/npx",
      "args": ["-y", "@modelcontextprotocol/server-github"],
      "env": {
        "GITHUB_PERSONAL_ACCESS_TOKEN": "ghp_your_token"
      }
    }
  }
}

This is the single most common fix on macOS. Claude Code running in a terminal usually does not have this problem. For full setup instructions per client, see our guides for Claude Code, Cursor, and Windsurf.

Cause 2: Wrong Package Name

A typo causes npx to fail silently. Common mistakes:

• @modelcontextprotocol/github instead of @modelcontextprotocol/server-github
• server-postgres instead of @modelcontextprotocol/server-postgres
• supabase-mcp instead of @supabase/mcp-server-supabase

The fix: Test manually: npx -y @modelcontextprotocol/server-github. Check the exact name on npmjs.com or the server's GitHub repo (GitHub MCP, Supabase MCP).

Cause 3: Network Issues During Install

First-run npx -y downloads from npm. If your network is down or behind a corporate proxy, the download fails.

The fix: Pre-install globally:

npm install -g @modelcontextprotocol/server-github

For corporate proxies:

npm config set proxy http://proxy.company.com:8080
npm config set https-proxy http://proxy.company.com:8080

Cause 4: Node.js Version Too Old

Some MCP servers require Node.js 18+. Older versions cause syntax errors swallowed by the client.

node --version    # If below v18, upgrade
nvm install 20 && nvm use 20

"Connection Refused" or "Connection Timeout"

Cause 1: Missing Environment Variables

The server starts, checks for a required API key, finds nothing, and exits.

The fix: Run the server manually to see the actual error:

GITHUB_PERSONAL_ACCESS_TOKEN="" npx -y @modelcontextprotocol/server-github

Double-check every required env var is set in your config's env block. For server-specific env var names, check the READMEs: Supabase MCP, GitHub MCP, Playwright MCP, Stripe MCP.

Cause 2: API Key Expired or Revoked

Valid-looking credentials that have been rotated cause the server to crash on authentication.

The fix: Regenerate your API key:

• GitHub: Settings > Developer settings > Personal access tokens
• Supabase: Dashboard > Account > Access Tokens
• Brave Search: brave.com/search/api

Update your config and restart. For security best practices on key management, see our MCP security guide.

"Tools Not Showing Up"

Cause 1: Tool Count Exceeds Client Limit

Cursor limits to 40 tools. GitHub MCP alone exposes 34. Add Supabase MCP (25 tools) and you are at 59 -- well over the limit.

The fix: Remove servers you are not actively using, or switch to lighter alternatives. A lean stack of 3-5 servers avoids this problem entirely. See how to build a lean stack.

Cause 2: Server Started But Env Vars Are Wrong

Some servers start without errors even with incorrect credentials. They register tools but those tools fail when called.

The fix: Test a tool call. Ask your assistant to use one of the server's tools. If the call fails with an auth error, the credentials are wrong.

"Environment Variable Not Recognized"

Cause 1: Trailing Spaces or Invisible Characters

Copy-pasting API keys sometimes includes hidden characters.

The fix: Delete the entire value and retype it manually.

Cause 2: Wrong Variable Name

Case-sensitive and must match exactly:

• GITHUB_TOKEN should be GITHUB_PERSONAL_ACCESS_TOKEN
• BRAVE_KEY should be BRAVE_API_KEY
• SUPABASE_TOKEN should be SUPABASE_ACCESS_TOKEN

Check the server's README for the exact variable name.

Cause 3: Env Vars Set in Shell But Not in Config

Variables in .bashrc or .zshrc are not available to GUI clients like Claude Desktop and Cursor. The env block in the MCP config is the only reliable way to pass env vars.

"JSON Parse Error in Config"

Trailing Commas

JSON does not allow trailing commas (JavaScript does):

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

Validate with: python3 -c "import json; json.load(open('path/to/config.json'))"

Single Quotes or Comments

JSON requires double quotes and does not support comments. Remove any // comment lines and replace 'single quotes' with "double quotes".

Unescaped Characters

Windows paths need escaped backslashes: "C:\\Users\\me\\project" not "C:\Users\me\project".

"Too Many Tokens" or Context Window Exhaustion

Your assistant seems to forget things or behave erratically. The cause is often too many MCP servers consuming too much context window.

The fix: Remove servers not actively in use, use project-level configs, and cap your stack at 3-5 servers. For detailed strategies, read how to cut your MCP token costs.

Diagnostic Checklist

Run through this before diving into specific errors:

1. Is Node.js 18+ installed? (node --version)
2. Is npx accessible? (which npx)
3. Is the package name correct? (check npmjs.com)
4. Are all required env vars set in the config?
5. Are the API keys valid and not expired?
6. Is the config file valid JSON?
7. Is the config file in the right location for your client?
8. Is the total tool count within your client's limit?
9. Can the server run manually in a terminal?
10. Are there duplicate server entries across project and global configs?

If you pass all ten and the server still fails, file an issue on the server's GitHub repository. For the 10 most common errors with detailed fixes, see our companion guide: MCP Server Troubleshooting.

The fastest way to avoid configuration problems entirely is to start with a known-good config from stackmcp.dev.