Cursor MCP Not Working? Complete Troubleshooting Guide

If your MCP servers are not working in Cursor, the fix is almost always one of five things: an invalid mcp.json configuration file, a missing runtime dependency (Node.js or Python), a server that crashes on startup, Cursor needing a restart, or incorrect environment variables. This guide walks through every common Cursor MCP issue with step-by-step solutions.

For the full MCP setup guide for Cursor and other IDEs, see MCP in Cursor, VS Code and Other IDEs.

---

Quick Diagnostic Checklist

Before diving into specific issues, run through this checklist. Most problems are resolved by one of these steps:

---

Issue 1: MCP Server Not Connecting

Symptoms

• The server shows a red status or "disconnected" in Cursor's MCP panel
• No tools from the server appear in Composer or Chat
• The server name appears in settings but with an error indicator

Fixes

Fix 1A: Validate your mcp.json syntax

The most common cause is a JSON syntax error. Open .cursor/mcp.json and check for:

• Missing commas between server entries
• Trailing comma after the last server entry
• Mismatched brackets or quotes
• Smart quotes (curly quotes) instead of straight quotes

Test your JSON from the terminal:

python3 -c "import json; json.load(open('.cursor/mcp.json'))"

No output means valid JSON. An error message will point to the problematic line.

Fix 1B: Check the server command exists

If your config uses npx, verify Node.js is installed:

node --version
npx --version

If your config uses uvx, verify uv is installed:

uvx --version

If these commands are not found, install the required runtime:

# Install Node.js (via nvm)
curl -o- https://raw.githubusercontent.com/nvm-sh/nvm/v0.39.0/install.sh | bash
nvm install 20

# Install uv (for Python MCP servers)
curl -LsSf https://astral.sh/uv/install.sh | sh

Fix 1C: Run the server command manually

Copy the exact command from your mcp.json and run it in a terminal:

npx -y @modelcontextprotocol/server-filesystem /Users/you/projects

If the server crashes immediately, the error output will tell you what is wrong. Common causes include:

• Package not found (typo in the package name)
• Missing system dependencies
• Permission denied errors
• Port already in use (for remote servers)

Fix 1D: Restart Cursor completely

Cursor caches MCP connections. A full restart is required after any config change:

1. Save all your work
2. Quit Cursor completely (Cmd+Q on macOS, Alt+F4 on Windows)
3. Wait 5 seconds
4. Reopen Cursor and your project

Simply closing and reopening a tab or window is not sufficient.

---

Issue 2: Tools Not Appearing in Composer

Symptoms

• The server shows as connected in MCP settings
• But when using Composer, Claude does not use or mention the server's tools
• The tools list in Composer does not include the expected tools

Fixes

Fix 2A: Verify tools are listed in MCP settings

Go to Cursor Settings > MCP and click on the connected server. You should see a list of available tools. If the list is empty, the server connected but is not exposing tools correctly.

Fix 2B: Use Composer mode, not Chat

MCP tools work most reliably in Cursor's Composer mode (Cmd+I / Ctrl+I). Some MCP features may have limited support in the standard Chat panel depending on your Cursor version.

Fix 2C: Be explicit in your prompts

Sometimes Claude does not invoke tools because it does not realize they are relevant. Be specific:

Instead of: "What is in my database?" Try: "Use the postgres MCP server to list all tables in my database."

Fix 2D: Check for tool count limits

Cursor may limit the number of tools shown to the model to avoid context overflow. If you have many servers with many tools, some may be deprioritized. Reduce the number of active servers to test if this is the issue.

---

Issue 3: Timeout Errors

Symptoms

• Server initially connects but then shows "timed out"
• Tools work for the first call but fail on subsequent calls
• Error messages mentioning "timeout" or "connection reset"

Fixes

Fix 3A: Increase timeout settings

Some MCP servers take longer to respond, especially database servers running complex queries or browser automation servers loading pages. Check if the server supports a timeout configuration option.

Fix 3B: Check network connectivity

For remote MCP servers (those using a URL instead of a local command), verify the endpoint is reachable:

curl -I https://your-mcp-server.example.com/sse

If this times out, the issue is network connectivity, not Cursor.

Fix 3C: Check for server crashes

A server may connect initially and then crash when processing a request. Run the server manually and send it a test request to see if it handles the workload:

# Start the server in one terminal
npx -y @modelcontextprotocol/server-postgres

# Check if the process stays running
ps aux | grep "server-postgres"

If the process disappears after a request, the server is crashing. Check the server's GitHub issues for known bugs.

---

Issue 4: Node.js and Python Runtime Issues

Symptoms

• Error messages about "node not found" or "python not found"
• Server fails with "ENOENT" or "spawn error"
• npx or uvx commands work in terminal but not in Cursor

Fixes

Fix 4A: Path issues between terminal and Cursor

Cursor may not have the same PATH as your terminal. This is especially common with Node.js installed via nvm or Python installed via pyenv.

Find the full path to your runtime:

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

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

Then use the full path in your mcp.json:

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

Fix 4B: Node.js version too old

MCP servers generally require Node.js 18 or later. Check your version:

node --version

If it is below v18, upgrade:

nvm install 20
nvm use 20

Fix 4C: Python server issues

For Python-based MCP servers using uvx:

# Verify uv is installed
uv --version

# Test the server directly
uvx mcp-server-name

If uv is not found, install it:

pip install uv
# or
curl -LsSf https://astral.sh/uv/install.sh | sh

---

Issue 5: Configuration File Errors

Symptoms

• Cursor does not recognize the mcp.json file
• Changes to the config have no effect
• Some servers load but others do not

Fixes

Fix 5A: Verify file location

The config file must be at .cursor/mcp.json in your project root -- not in the home directory, not in a subdirectory, and not named differently.

# Correct location
ls -la /path/to/your/project/.cursor/mcp.json

# Create the directory if it does not exist
mkdir -p /path/to/your/project/.cursor

Fix 5B: Check file encoding

The file must be UTF-8 encoded with no BOM (byte order mark). If you created the file on Windows, it may have a BOM. Open it in a code editor and save as UTF-8 without BOM.

Fix 5C: Verify the JSON structure

The correct structure uses mcpServers as the top-level key:

{
  "mcpServers": {
    "server-name": {
      "command": "npx",
      "args": ["-y", "package-name"]
    }
  }
}

Common structural mistakes:

Fix 5D: Global vs project config

Cursor supports both global and project-level MCP configs. If your project config is not working, check if a global config is overriding it. The global config is typically in your Cursor settings directory.

---

Issue 6: Environment Variable Problems

Symptoms

• Server connects but tool calls fail with "unauthorized" or "forbidden" errors
• Error messages about missing API keys or tokens
• Server works when run manually but fails in Cursor

Fixes

Fix 6A: Verify env values in config

Check that your environment variables are correctly set in the mcp.json:

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

Common mistakes:

• Placeholder values left in place ("your_token_here")
• Expired API keys or tokens
• Incorrect variable names (check the server's documentation for exact names)
• Extra whitespace in values

Fix 6B: Check token permissions

Many API tokens require specific scopes. For example, a GitHub token needs repo, read:org, and read:user scopes to use all GitHub MCP server tools.

---

Issue 7: Server Works in Claude Desktop but Not Cursor

Symptoms

• The same server and config work perfectly in Claude Desktop
• But the same server fails or behaves differently in Cursor

Fixes

Fix 7A: Config format differences

Claude Desktop and Cursor use the same general JSON structure but store configs in different locations. Double-check that you have copied the server entries into the Cursor-specific file (.cursor/mcp.json), not the Claude Desktop config.

Fix 7B: Cursor-specific MCP version

Cursor may support a slightly different version of the MCP protocol. Check Cursor's release notes for any known MCP compatibility issues with specific servers.

Fix 7C: Composer mode requirement

Some tool invocations only work in Cursor's Composer mode. If you are testing in Chat mode, switch to Composer (Cmd+I / Ctrl+I).

---

Reading Server Logs

When none of the above fixes work, server logs provide the definitive answer.

Finding Cursor Logs

Cursor writes MCP-related logs to its developer console:

1. Open Cursor
2. Go to Help > Toggle Developer Tools
3. Click the Console tab
4. Filter for "mcp" to see MCP-related messages

Running the MCP Inspector

The MCP Inspector is a standalone tool for testing servers outside of any client:

npx @modelcontextprotocol/inspector npx -y @modelcontextprotocol/server-filesystem /tmp

This opens a web UI where you can connect to the server, list tools, and test tool calls. If the server works in the Inspector but not in Cursor, the issue is Cursor-specific.

For more on debugging MCP servers, see Testing and Debugging MCP Servers.

---

Common Error Messages and Solutions

---

Preventive Best Practices

What to Read Next

• MCP in Cursor, VS Code and Other IDEs -- Complete setup guide (parent pillar)
• Best MCP Servers for Cursor -- Top 15 recommended servers
• Configure Multiple MCP Servers in Claude Desktop -- Multi-server management (applies to Cursor too)
• Testing and Debugging MCP Servers -- In-depth debugging techniques
• Browse All MCP Servers -- Find compatible servers for your workflow