Cursor MCP Server Errors

Overview: MCP in Cursor

Cursor has built-in MCP support that lets you connect AI-powered tools directly to the editor. However, Cursor's MCP implementation has specific quirks and configuration requirements that differ from other clients. This guide covers every known Cursor MCP error and how to fix it.

Cursor MCP Configuration Format

Cursor uses a .cursor/mcp.json file for MCP configuration. There are two locations:

Project-Level Config (Recommended)

your-project/.cursor/mcp.json

This config applies only to the current project. Create the .cursor directory in your project root if it doesn't exist.

Global Config

~/.cursor/mcp.json

This config applies to all projects. Create it in your home directory.

Config Format

Cursor's format is similar to Claude Desktop but has differences:

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

Error 1: Server Not Starting

The most common error is the server failing to start. Cursor shows a red status indicator next to the server name in Settings > MCP.

Diagnosis

1. Open Cursor Settings (Cmd/Ctrl + ,)
2. Navigate to the MCP section
3. Look for servers with red indicators
4. Click the server name to see error details

Common Causes

• npx not found - Use the full path to npx. See our spawn ENOENT guide for platform-specific paths.
• Package not installed - Run npx -y <package-name> manually in the terminal to verify it works.
• Wrong Node version - Cursor uses its own Node.js runtime for some operations, but MCP servers use your system Node. Ensure Node 18+ is installed.

Error 2: Config File Not Detected

Cursor might not pick up your mcp.json file. Common causes:

• Wrong directory name - It must be .cursor/mcp.json, not .cursor/mcp.config.json or cursor/mcp.json (note the dot).
• File not saved - Ensure the file is saved after editing.
• Project not opened from root - If you opened a subfolder, the project root may not have the .cursor directory.

After creating or editing the config, reload Cursor (Cmd/Ctrl + Shift + P > "Developer: Reload Window").

Error 3: Tools Not Appearing in Composer

MCP tools in Cursor are primarily available in Composer mode (Cmd/Ctrl + I), not the regular chat. If you can't see your tools:

• Open Composer mode (Cmd/Ctrl + I)
• Make sure the agent mode is enabled (not just "chat" mode)
• Check that the server shows as connected in Settings > MCP
• Verify the tool count is not 0 - if it is, see our tools not showing guide

Error 4: Server Keeps Disconnecting

If your MCP server connects but then drops after a few seconds or minutes:

# Common log output
MCP server "my-server" disconnected
Reconnecting in 5 seconds...

Causes

• Server crash - The server process is crashing. Run it manually to see the error output.
• Stderr output - Servers that write warnings to stderr can confuse some MCP clients. Suppress stderr output or redirect it.
• Timeout - Some servers take too long to respond and Cursor disconnects them. Optimize your server's response time.

Error 5: Environment Variables Not Working

Cursor supports the "env" field in mcp.json, but there are caveats:

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

• Env vars are passed to the server process, not inherited from your shell
• If you need PATH modifications, include the full PATH in the env field
• Cursor doesn't read .env files automatically - use the env field or set them globally

For more on environment variable configuration, see our environment variables guide.

Error 6: Project vs Global Config Conflicts

If you have both project-level and global MCP configs, Cursor merges them. This can cause issues if the same server name appears in both files with different configurations.

# Global: ~/.cursor/mcp.json
{
  "mcpServers": {
    "filesystem": { "command": "npx", "args": ["...server-filesystem", "/global"] }
  }
}

# Project: ./cursor/mcp.json
{
  "mcpServers": {
    "filesystem": { "command": "npx", "args": ["...server-filesystem", "/project"] }
  }
}
# Result: project config takes precedence

Best practice: Use unique server names, or use only project-level configs for project-specific servers.

Cursor Settings UI

Cursor also allows configuring MCP servers through the Settings UI:

1. Open Settings (Cmd/Ctrl + ,)
2. Search for "MCP"
3. Click "Add Server"
4. Enter the server details

Changes made in the UI are saved to the global config. For project-specific servers, edit the .cursor/mcp.json file directly.

Restarting MCP Servers in Cursor

Unlike Claude Desktop, Cursor supports restarting individual servers without restarting the whole editor:

1. Open Settings > MCP
2. Click the restart button next to the server
3. Or reload the window: Cmd/Ctrl + Shift + P > "Developer: Reload Window"

Common Pitfalls

• Using Claude Desktop config format - While similar, the file name and location differ. Cursor uses .cursor/mcp.json, not claude_desktop_config.json.
• Not using Composer mode - MCP tools are only available in Composer/Agent mode, not regular chat.
• Forgetting to reload - After config changes, reload the window or restart the server.
• Too many servers - Cursor handles about 8-10 servers well. More than that can slow down Composer response times.

For a complete setup tutorial, see our first MCP server tutorial. For a comparison of all MCP clients, see our MCP clients comparison.