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, giving the AI assistant the ability to interact with databases, file systems, APIs, and more. However, Cursor's MCP implementation has specific quirks and configuration requirements that differ from Claude Desktop, VS Code, and other MCP clients. This guide covers every known Cursor MCP error and provides step-by-step fixes.

Before troubleshooting, make sure you are running Cursor version 0.40 or later. MCP support was added in this version and has been improved in subsequent releases. Check your version under Help, About Cursor.

Cursor MCP Configuration Format

Cursor uses a .cursor/mcp.json file for MCP configuration. There are two locations, and understanding the difference between them is critical for avoiding configuration confusion.

Project-Level Config (Recommended for project-specific servers)

your-project/.cursor/mcp.json

This config applies only to the current project. Create the .cursor directory in your project root if it does not exist. This is ideal for servers that are specific to a project, like database connections or project-specific tools. The config file travels with the project if you commit the .cursor directory to version control (but remember to keep secrets out of version-controlled files).

Global Config

# macOS / Linux
~/.cursor/mcp.json

# Windows
C:\Users\YOUR_USERNAME\.cursor\mcp.json

This config applies to all projects you open in Cursor. Use it for universally useful servers like filesystem, memory, or web search that you want available everywhere.

.cursor/mcp.json vs claude_desktop_config.json

One of the most common mistakes is copying a Claude Desktop config and expecting it to work in Cursor. While the JSON structure inside mcpServers is nearly identical, the file name and location are completely different:

Aspect	Claude Desktop	Cursor
File name	claude_desktop_config.json	mcp.json
Global location	~/Library/Application Support/Claude/	~/.cursor/
Project-level	Not supported (global only)	.cursor/mcp.json in project root
Server restart	Full app restart required	Per-server restart in Settings
Tool availability	All conversations	Composer mode only (Agent mode)

Config Format Example

{
  "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 section.

Diagnosis Steps

1. Open Cursor Settings (Cmd/Ctrl + ,)
2. Navigate to the MCP section
3. Look for servers with red indicators or "Error" status
4. Click the server name or hover over it to see error details
5. Check the Output panel (View, Output) and select the MCP-related channel for detailed logs

Common Causes and Fixes

• npx not found (ENOENT) - Use the full absolute path to npx. On macOS, run which npx to find it. On Windows, use npx.cmd or where npx for the full path. See our spawn ENOENT guide for platform-specific paths.
• Package not installed or misspelled - Run npx -y <package-name> manually in the integrated terminal to verify it works and downloads successfully.
• Wrong Node version - Cursor uses its own Node.js runtime for editor operations, but MCP servers use your system Node.js. Ensure Node.js 18+ is installed system-wide. Run node --version in the integrated terminal to check.
• Invalid JSON syntax - Check for trailing commas, missing quotes, unescaped backslashes, or comments (JSON does not support comments). Validate with node -e "require('./.cursor/mcp.json')"

Error 2: Config File Not Detected

Cursor might not pick up your mcp.json file even though it exists. This is one of the most confusing issues because the file is right there but Cursor ignores it.

• Wrong directory name - It must be .cursor/mcp.json, not .cursor/mcp.config.json, .cursor/config.json, or cursor/mcp.json (note the leading dot on the directory name).
• File not saved - Ensure the file is saved after editing. Look for the dot indicator on the file tab.
• Project not opened from root - If you opened a subfolder, Cursor looks for .cursor/mcp.json in that subfolder, not the actual project root. Open the project at the correct root level.
• Case sensitivity on Linux - Linux file systems are case-sensitive. .Cursor/mcp.json is not the same as .cursor/mcp.json.
• Hidden directory not created - Some file managers do not show directories starting with a dot by default. Use the terminal to create it: mkdir -p .cursor && touch .cursor/mcp.json

After creating or editing the config, reload Cursor: Cmd/Ctrl + Shift + P, then type "Developer: Reload Window" and press Enter.

Error 3: Tools Not Appearing in Composer

This is the second most common issue. MCP tools in Cursor are only available in Composer mode, not in the regular chat sidebar. This is a fundamental architectural decision by Cursor - regular chat does not have tool-calling capabilities.

Composer Mode Requirements

• Open Composer mode - Press Cmd/Ctrl + I to open the Composer panel
• Enable Agent mode - In the Composer panel, make sure the mode selector shows "Agent" or "Composer Agent", not just "Chat." The basic chat mode does not support MCP tools.
• Check server connection - Go to Settings, MCP and verify the server shows as connected (green indicator) with a non-zero tool count
• Verify tool count - If the tool count shows 0, the server is connected but not exposing tools. See our tools not showing guide for fixes.

If tools appear in the Settings UI but the AI does not use them, try explicitly mentioning the tool or server in your prompt. For example, "Use the filesystem tool to read the README.md file" is more likely to trigger tool use than a vague request.

Error 4: Extension Conflicts

Certain VS Code extensions (Cursor is built on VS Code) can interfere with MCP server operation. Known conflicts include:

• Other AI extensions - Extensions like GitHub Copilot, Cody, or Continue may conflict with Cursor's MCP implementation if they also try to manage MCP servers. Disable them temporarily to test.
• Terminal-modifying extensions - Extensions that modify the shell environment or terminal behavior can affect how Cursor spawns MCP server processes.
• Port-using extensions - Extensions that bind to network ports may conflict with HTTP-based MCP servers. Check for port conflicts using lsof -i :PORT.

To test for extension conflicts, open Cursor with extensions disabled: cursor --disable-extensions from the terminal. If MCP works with extensions disabled, re-enable them one by one to find the conflicting extension.

Error 5: Server Keeps Disconnecting

If your MCP server connects but then drops after a few seconds or minutes, the server process is likely crashing or being killed.

# Common indicators
MCP server "my-server" disconnected
Reconnecting in 5 seconds...
Server status changed to: error

Causes and Fixes

• Server crash on first request - The server starts fine but crashes when Cursor sends a tools/list or tools/call request. Run the server manually and use the MCP Inspector (npx @modelcontextprotocol/inspector) to test requests.
• Stderr output pollution - Servers that write warnings, deprecation notices, or debug output to stderr can confuse Cursor's MCP transport layer. Suppress or redirect stderr output in your server. In Node.js: console.warn = () => {}. In Python: redirect stderr in the entry point.
• Timeout on slow operations - Cursor disconnects servers that take too long to respond. See our timeout troubleshooting guide for optimization strategies.
• Memory exhaustion - Servers that consume too much memory may be killed by the OS. Monitor memory usage and optimize your server's resource consumption.

Error 6: Environment Variables Not Working

Cursor supports the "env" field in mcp.json, but behavior differs from Claude Desktop in important ways:

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

• Env vars in the "env" field are passed directly to the server process
• Cursor inherits more of the system environment than Claude Desktop does, so some env vars set in your terminal may already be available without explicit configuration
• If you need PATH modifications, include the full PATH in the env field - setting PATH in env replaces the inherited PATH entirely
• Cursor does not read .env files automatically - use the "env" field or set variables globally in your OS
• All env values must be strings, even for numbers: use "PORT": "3000" not "PORT": 3000

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

Error 7: Project vs Global Config Conflicts

If you have both project-level (.cursor/mcp.json) and global (~/.cursor/mcp.json) MCP configs, Cursor merges them. This can cause unexpected behavior:

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

# Project: .cursor/mcp.json
{
  "mcpServers": {
    "filesystem": { "command": "npx", "args": ["...server-filesystem", "/project/path"] }
  }
}
# Result: project config takes precedence for "filesystem"
# Global servers with different names are also loaded

Best practices for managing config conflicts:

• Use unique server names across global and project configs to avoid collisions
• Use project-level configs for project-specific servers (database, project filesystem)
• Use global config only for universally useful servers (web search, memory)
• When debugging, temporarily remove one config to isolate which config is causing issues

Cursor Settings UI for MCP

Cursor also allows configuring MCP servers through the Settings UI, which is useful for quick additions but has limitations:

1. Open Settings (Cmd/Ctrl + ,)
2. Search for "MCP" in the settings search bar
3. Click "Add Server" to add a new server
4. Enter the server details (name, command, arguments, environment variables)

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

Restarting MCP Servers in Cursor

Unlike Claude Desktop which requires a full application restart, Cursor supports restarting individual MCP servers without restarting the whole editor:

1. Open Settings, navigate to MCP
2. Click the restart button (circular arrow icon) next to the server you want to restart
3. Wait for the status indicator to turn green

Alternatively, reload the entire window to restart all servers: Cmd/Ctrl + Shift + P, then "Developer: Reload Window". This is faster than closing and reopening Cursor and reinitializes all MCP connections.

Common Pitfalls

• Using Claude Desktop config file name - Cursor uses .cursor/mcp.json, not claude_desktop_config.json. Do not rename one to the other.
• Not using Composer mode - MCP tools are only available in Composer/Agent mode, not regular chat. This catches many users off guard.
• Forgetting to reload - After config changes, reload the window or restart the server. Config changes are not picked up automatically.
• Too many servers - Cursor handles about 8-10 servers well. Beyond that, you may notice slower Composer responses because each tool description consumes context window tokens. See our how many servers guide for optimization tips.
• Windows path issues - On Windows, use npx.cmd instead of npx and double-escape backslashes in paths. See our Windows MCP setup guide.
• Stale npx cache - If a server was working and suddenly breaks after an update, clear the npx cache: npx clear-npx-cache and try again.

For a complete first-time setup tutorial, see our first MCP server tutorial. For a comparison of all MCP clients and their capabilities, see our MCP clients comparison. For running multiple servers efficiently, see the multiple server configuration guide.