How to Fix Common MCP Server Connection Errors

MCP servers fail in predictable ways. The error messages are often unhelpful -- a vague "connection refused," a silent hang, or a JSON parse error that points to the wrong line. But the underlying causes are almost always one of a handful of common problems.

This guide covers the most frequent MCP server connection errors, organized by the error message you actually see. Find your error, follow the fix.

Before You Debug Anything

Run these three commands first. They catch the most common root causes before you start digging into specific errors.

# 1. Is Node.js installed and accessible?
node --version

# 2. Can your shell find npx?
which npx

# 3. Is the package name correct? (test with any server)
npx -y @modelcontextprotocol/server-filesystem --help

If node --version fails, install Node.js 18 or later. If which npx returns nothing, your PATH is misconfigured. If the npx command fails with a package error, you have a network or registry issue.

Most MCP server problems are not MCP problems. They are Node.js, PATH, or credential problems wearing an MCP hat.

"Server Failed to Start"

This is the most common error across all MCP clients. You add a server to your config, restart the client, and it reports that the server failed to start. No further 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 in a directory that Claude Desktop, Cursor, and VS Code cannot see.

The fix: Use the full absolute path to npx in your MCP config.

# Find the full path
which npx
# Example: /Users/you/.nvm/versions/node/v20.11.0/bin/npx

Then update your config:

{
  "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 for "server failed to start" on macOS. Claude Code running in a terminal usually does not have this problem because it inherits your shell's PATH directly.

Cause 2: Wrong Package Name

A typo in the npm package name causes npx to fail silently. The MCP client reports a generic startup failure.

The fix: Verify the package name by running it manually:

# Test the exact command from your config
npx -y @modelcontextprotocol/server-github

If it fails with "not found" or "404," the package name is wrong. Common mistakes:

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

Check the exact package name on npmjs.com or in the server's GitHub README.

Cause 3: Network Issues During Install

The first time npx -y runs a package, it downloads it from npm. If your network is down, behind a corporate proxy, or npm's registry is experiencing issues, the download fails and the server cannot start.

The fix: Pre-install the package globally so it does not need to download on each startup:

npm install -g @modelcontextprotocol/server-github

Then verify it runs:

npx @modelcontextprotocol/server-github

If you are behind a corporate proxy, configure npm to use it:

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 or later. If you are running an older version, the server may fail to start with a syntax error or an unexpected token error that gets swallowed by the client.

The fix:

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

"Connection Refused" or "Connection Timeout"

You see this when the MCP client tries to connect to a server and gets no response. The server process either did not start or crashed immediately after starting.

Cause 1: Missing Environment Variables

The server starts, checks for a required API key or token, finds nothing, and exits. The client only sees that the connection was refused.

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

# Run exactly what your config specifies
GITHUB_PERSONAL_ACCESS_TOKEN="" npx -y @modelcontextprotocol/server-github

You will likely see output like Error: GITHUB_PERSONAL_ACCESS_TOKEN is required. Double-check that every required env var is set in your MCP config:

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

Cause 2: HTTP Server Not Running (SSE Transport)

If you are connecting to a remote MCP server using SSE (Server-Sent Events) transport, the server must be running and accessible at the specified URL before the client tries to connect.

The fix: Verify the server is reachable:

curl -I http://localhost:3001/sse

If the server is remote, check that the URL is correct, the port is open, and any firewall or security group allows the connection. If the server runs in Docker, ensure the port is mapped correctly.

Cause 3: API Key Expired or Revoked

Valid-looking credentials that have been rotated, expired, or revoked cause the server to start and then immediately crash when it tries to authenticate with the external service.

The fix: Regenerate your API key from the service provider's dashboard:

• GitHub: Settings > Developer settings > Personal access tokens
• Brave Search: brave.com/search/api
• Supabase: Dashboard > Account > Access Tokens
• Exa: exa.ai/dashboard
• Tavily: tavily.com/dashboard

Update your MCP config with the new key and restart the client.

"Tools Not Showing Up"

The server appears to be running (no error messages), but your AI assistant does not list any tools from it. The server is connected but functionally invisible.

Cause 1: Server Crashed After Registration

Some servers start successfully and register with the client, then crash when they try to initialize their tool set. The client shows the server as "connected" but has no tools to offer.

The fix: Check the server logs. In Claude Code:

# List servers and their status
claude mcp list

In Claude Desktop, open the developer console (View > Developer > Developer Tools) and check the console tab for error messages from the MCP server process.

Cause 2: Tool Count Exceeds Client Limit

Each client has a maximum number of MCP tools it can register. Cursor limits you to 40 tools. If you exceed the limit, later servers get silently dropped.

The fix: Audit your total tool count:

If you are running GitHub MCP (34 tools) and Supabase MCP (25 tools) in Cursor, you are already at 59 tools -- well over the 40-tool limit. Remove servers you are not actively using, or switch to lighter alternatives.

Cause 3: Server Started But Env Vars Are Wrong

Some servers start without errors even when environment variables are incorrect. They register their tools but those tools fail when called because the credentials do not work.

The fix: Test a tool call. Ask your assistant to use one of the server's tools (e.g., "list my GitHub repos" for the GitHub MCP server). If the tool call fails with an authentication error, the credentials are wrong even though the server appeared to start correctly.

"Environment Variable Not Recognized"

The server reports that an environment variable is not set, but you can see it in your config file. This is a formatting issue almost every time.

Cause 1: Trailing Spaces or Invisible Characters

Copy-pasting API keys from a web dashboard sometimes includes trailing spaces, zero-width characters, or newlines that are invisible in your editor but break the value.

The fix: Delete the entire value and retype it manually. Or use a hex editor to verify there are no hidden characters. A quick test:

# Print the value with quotes to reveal trailing spaces
echo "[$GITHUB_PERSONAL_ACCESS_TOKEN]"

If you see [ghp_abc123 ] with a space before the bracket, there is your problem.

Cause 2: Wrong Variable Name

Environment variable names are case-sensitive and must match exactly what the server expects.

Common mistakes:

• GITHUB_TOKEN instead of GITHUB_PERSONAL_ACCESS_TOKEN
• BRAVE_KEY instead of BRAVE_API_KEY
• SUPABASE_TOKEN instead of SUPABASE_ACCESS_TOKEN
• EXA_KEY instead of EXA_API_KEY
• TAVILY_KEY instead of TAVILY_API_KEY

Check the server's README or npm page for the exact variable name. Do not guess.

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

If you set environment variables in your .bashrc or .zshrc, they are available in your terminal but not in your MCP config. GUI clients like Claude Desktop and Cursor do not read your shell profile. The env block in the MCP config is the only reliable way to pass environment variables to a server.

The fix: Always set env vars explicitly in your MCP config's env block, even if they are also set in your shell.

"JSON Parse Error in Config"

Your client refuses to load the MCP config file because the JSON is invalid. Sometimes you get a line number. Sometimes you just get "invalid JSON."

Cause 1: Trailing Commas

JSON does not allow trailing commas. JavaScript does. If you are used to writing JavaScript objects, this mistake is automatic.

{
  "mcpServers": {
    "github": {
      "command": "npx",
      "args": ["-y", "@modelcontextprotocol/server-github"],  <-- trailing comma OK here
    }  <-- trailing comma NOT OK here
  }
}

The fix: Remove the comma after the last property in every object and array. Use a JSON validator like jsonlint.com or run:

# Validate your config file
python3 -c "import json; json.load(open('path/to/config.json'))"

Cause 2: Single Quotes Instead of Double Quotes

JSON requires double quotes. Single quotes are invalid.

// WRONG
{ 'mcpServers': { 'github': { 'command': 'npx' } } }

// CORRECT
{ "mcpServers": { "github": { "command": "npx" } } }

Cause 3: Comments in JSON

JSON does not support comments. If you added // this is my github config above a server entry, the parser will reject the entire file.

The fix: Remove all comments. If you need to annotate your config, use a separate documentation file or switch to a client that supports JSONC (JSON with Comments), like VS Code's settings files.

Cause 4: Unescaped Characters in Values

Backslashes and quotes inside string values must be escaped.

// WRONG - Windows path with unescaped backslashes
"args": ["-y", "server", "C:\Users\me\project"]

// CORRECT
"args": ["-y", "server", "C:\\Users\\me\\project"]

"Server Keeps Crashing"

The server starts, works for a while, then crashes mid-session. Your assistant loses access to its tools and you have to restart.

Cause 1: Memory Issues

Some MCP servers accumulate memory usage over long sessions, especially those that maintain state like database connections or browser sessions. Eventually they hit a memory limit and crash.

The fix: Restart your AI client periodically during long sessions. If a specific server consistently crashes after extended use, file an issue on its GitHub repository. In the meantime, reduce session length or split your work into shorter sessions.

Cause 2: Conflicting Server Processes

Running two MCP servers that both try to bind to the same port, or two instances of the same server, causes crashes. This happens when you have the same server configured in both a project-level and global config file.

The fix: Check for duplicate configs:

# Project-level
cat .mcp.json

# Global (Claude Code)
cat ~/.claude.json

# Cursor project-level
cat .cursor/mcp.json

# Cursor global
cat ~/.cursor/mcp.json

If the same server appears in both project and global config, remove the duplicate.

Cause 3: Version Incompatibility

Running an outdated version of an MCP server against a newer version of the MCP protocol can cause unexpected crashes. The -y flag in npx caches packages, so you might be running a stale version.

The fix: Clear the npx cache and force a fresh install:

# Clear npx cache
npx clear-npx-cache

# Or reinstall the specific package
npm install -g @modelcontextprotocol/server-github@latest

"Permission Denied"

The server starts and connects, but tool calls fail with permission or authorization errors.

Cause 1: Token Scopes Too Narrow

GitHub personal access tokens, for example, require specific scopes for different operations. A token with only repo scope cannot manage GitHub Actions. A Supabase token without the right permissions cannot create projects.

The fix: Check what scopes your token has and what the MCP server requires. For GitHub MCP, you typically need:

• repo (full repository access)
• read:org (read organization data)
• gist (create and read gists)

Regenerate the token with the required scopes and update your config.

Cause 2: API Key Rate Limited

Some services return permission-denied errors when you hit rate limits instead of a proper 429 status code. If your tools worked earlier in the session but started failing, you may have exhausted your API quota.

The fix: Check your usage dashboard on the service provider's site. Wait for the rate limit to reset, or upgrade your plan if you consistently hit limits.

Cause 3: Filesystem Permissions

MCP servers that access your filesystem (Filesystem MCP, SQLite MCP) need read/write permissions on the directories they access. If you point them at a directory owned by another user or a read-only mount, they fail.

The fix: Verify permissions on the target directory:

ls -la /path/to/directory

Ensure the user running your AI client has read (and write, if needed) access to the files the MCP server will touch.

"Too Many Tokens" or Context Window Exhaustion

You are not getting errors per se, but your AI assistant seems to forget things, drop context, or behave erratically. The cause is often too many MCP servers consuming too much of your context window.

The Problem

Every active MCP server registers its tool definitions at session start. These tool definitions are tokens that count against your context window. Here is what common server combinations cost:

When tool definitions consume 25-30% of your context window, you have proportionally less space for your actual conversation, code, and results. This is why your assistant "forgets" things late in a session -- it is not a bug, it is a math problem.

The Fix

1. Remove servers you are not actively using. If you have not used the Playwright MCP server in the last hour, remove it from your config. You can add it back in 10 seconds.

2. Choose lighter alternatives. PostgreSQL MCP (4,120 tokens) instead of Supabase MCP (12,875 tokens) if you only need SQL queries. Brave Search MCP (1,030 tokens) instead of Exa MCP (1,545 tokens) if keyword search is sufficient.

3. Use project-level configs. Configure only the servers you need for each project, rather than loading everything globally.

4. Cap your stack at 3-5 servers. A focused set of servers that you actively use is more effective than 8 servers that crowd your context window.

Client-Specific Issues

Claude Code

Claude Code runs in the terminal and inherits your shell's PATH, so the npx-not-found problem is rare. The most common Claude Code-specific issue is the 60-second timeout for long-running tool calls. If an MCP tool call takes longer than 60 seconds, it is silently abandoned. Break long operations into smaller chunks.

# Check your configured servers
claude mcp list

# Add a server
claude mcp add github -e GITHUB_PERSONAL_ACCESS_TOKEN=ghp_abc123 -- npx -y @modelcontextprotocol/server-github

Cursor

Cursor has a 40-tool limit. If your combined MCP servers register more than 40 tools, the extras are silently dropped. Cursor also reads config from .cursor/mcp.json (project) or ~/.cursor/mcp.json (global). Make sure you are editing the right file.

VS Code (GitHub Copilot)

VS Code reads MCP config from .vscode/mcp.json in the workspace. The format is the same as other clients, but the file location is different. VS Code also supports an inputs array for prompting users for secrets at runtime instead of hardcoding them in the config.

Windsurf

Windsurf reads from .windsurf/mcp.json (project) or ~/.windsurf/mcp.json (global). Windsurf has been known to cache MCP server connections aggressively -- if you change your config, fully restart Windsurf rather than just reloading the window.

How to Test a Server Manually

When all else fails, test the MCP server outside of any client. This isolates whether the problem is with the server or the client.

# Step 1: Run the server command directly
npx -y @modelcontextprotocol/server-github

# Step 2: If it needs env vars, set them inline
GITHUB_PERSONAL_ACCESS_TOKEN=ghp_abc123 npx -y @modelcontextprotocol/server-github

# Step 3: If it starts successfully, you should see it waiting for input on stdin
# The server is working. The problem is in your client config.

# Step 4: If it crashes, read the error output
# Common outputs:
# - "Error: GITHUB_PERSONAL_ACCESS_TOKEN is required" -> missing env var
# - "Error: Cannot find module" -> broken package install, clear cache
# - "SyntaxError: Unexpected token" -> Node.js version too old

If the server runs successfully in your terminal but not in your client, the problem is almost always PATH resolution (fix with absolute paths) or missing env vars (fix by adding them to the env block in your config).

Diagnostic Checklist

When you hit an MCP server issue, run through this checklist before diving into specific error messages:

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? (no trailing commas, no comments, double quotes)
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 checks and the server still does not work, file an issue on the server's GitHub repository with the error output from step 9.

Stop Debugging, Start Building

Most MCP connection errors come from misconfiguration, not broken servers. Wrong paths, missing keys, invalid JSON, and tool count limits account for over 90% of the issues developers hit.

The fastest way to avoid these problems is to start with a known-good configuration. At stackmcp.dev, every server config is pre-validated with correct package names, environment variable placeholders, and accurate tool count data. Pick your stack, copy the config, fill in your API keys, and you are running.

If you are still hitting issues, check out our full MCP Server Troubleshooting Guide for additional error scenarios and advanced debugging techniques.