How to fix common MCP server errors

Most MCP server problems fall into a few categories: the config file has a syntax error, the app cannot find the server command, credentials are wrong, or the server crashes on startup. Here is how to diagnose and fix each one.

For basic setup instructions, see How to install an MCP server. This guide covers what to do when that setup does not work.

How do you diagnose an MCP server that will not connect?

Start by figuring out which layer is failing:

1. Config file problem. The AI app cannot parse your config at all.
2. Command not found. The app parses the config but cannot launch the server.
3. Server crashes on startup. The command runs but the server exits immediately.
4. Auth failure. The server starts but cannot connect to the external service.

Work through these in order. Most issues are in step 1 or 2.

How do you fix JSON config syntax errors?

The most common cause of "server not appearing" is a broken config file. JSON is strict about syntax: one missing comma or extra bracket breaks everything, and most AI apps fail silently.

How to check:

1. Open your config file
2. Copy the entire contents
3. Paste it into a JSON validator (search "JSON validator" in your browser)
4. Fix any errors it highlights

Common mistakes:

• Trailing comma after the last item in an object or array
• Missing comma between server entries
• Mismatched braces or brackets
• Using single quotes instead of double quotes

{
  "mcpServers": {
    "github": {
      "command": "npx",
      "args": ["-y", "@modelcontextprotocol/server-github"],
      "env": {
        "GITHUB_PERSONAL_ACCESS_TOKEN": "ghp_your_token"
      }
    },
    "postgres": {
      "command": "npx",
      "args": ["-y", "@modelcontextprotocol/server-postgres", "postgresql://localhost/mydb"]
    }
  }
}

Make sure each server block is separated by a comma and the overall structure has matching braces.

What does "command not found" mean and how do you fix it?

This means your AI app cannot find npx, uvx, python, or whatever command the server uses. It happens because GUI applications (Claude Desktop, Cursor) often have a different PATH environment than your terminal.

Fix for npx/node:

1. Open your terminal
2. Run which npx (macOS/Linux) or where npx (Windows)
3. Copy the full path (e.g., /usr/local/bin/npx)
4. Replace "command": "npx" with "command": "/usr/local/bin/npx" in your config

Fix for uvx/python:

1. Run which uvx in your terminal
2. Copy the full path (e.g., /Users/you/.local/bin/uvx)
3. Use that full path in your config

This is especially common on macOS where Node.js is installed via nvm or Homebrew, and the GUI app does not inherit your shell's PATH.

Why are MCP tools not showing up after restart?

If the config is valid and the command exists, but tools still do not appear:

Check that the server actually starts. Run the command directly in your terminal:

npx -y @modelcontextprotocol/server-github

If it prints an error and exits, the server itself has a problem (usually missing credentials or a dependency issue).

Check your AI app version. Older versions of Claude Desktop, Cursor, or VS Code may not support all MCP features. Remote server support, for example, was added in later releases. Update to the latest version.

Check for conflicting server names. If two servers have the same key in your config (e.g., both named "github"), the second one overwrites the first. Each server needs a unique name.

How do you fix authentication and credential errors?

If the server starts but returns authentication errors:

Verify the credential is correct. Copy it fresh from the service (GitHub, Slack, Notion, etc.) and paste it directly into the config. Watch for extra whitespace or newline characters.

Check permissions. Some API tokens need specific scopes. A GitHub token needs repo scope to manage repositories. A read-only token will fail on write operations.

Check expiration. Some tokens expire. If a server worked last week but fails now, regenerate the token.

Environment variable format. Credentials go in the "env" block of your config:

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

Do not put credentials in the "args" array unless the server documentation specifically says to.

What causes "connection refused" on remote servers?

Remote MCP servers connect over a URL instead of running locally. "Connection refused" usually means:

• Wrong URL. Double-check the URL from the server listing on MCP Marketplace. A typo or missing path segment will cause this.
• Server is down. The remote server may be temporarily unavailable. Try again in a few minutes.
• Authentication required. Some remote servers need an API key in the headers config:

{
  "mcpServers": {
    "remote-plugin": {
      "url": "https://api.example.com/mcp",
      "headers": {
        "Authorization": "Bearer your-key-here"
      }
    }
  }
}

• App does not support remote servers. Make sure your AI app supports remote MCP connections. Recent versions of Claude Desktop and Cursor support this, but older versions may not.

Where do you find MCP server logs?

When a server crashes or behaves unexpectedly, logs tell you what happened.

Running directly in terminal. The simplest approach: run the server command in your terminal and watch the output. Most servers print errors to stderr.

Claude Desktop logs. On macOS, check ~/Library/Logs/Claude/. On Windows, check %APPDATA%\Claude\logs\.

Cursor. Open the Output panel (View > Output) and select the MCP server from the dropdown.

VS Code. Similar to Cursor: check the Output panel for MCP-related channels.

Quick reference: common errors and fixes

For installation instructions, see How to install an MCP server. To evaluate server safety, read Are MCP servers safe?.

Browse servers with install instructions on MCP Marketplace.