Cursor MCP server not working? Fixes that actually work

Quick checklist

1. 1. Is the config file in the right place?
2. 2. Check the JSON
3. 3. Check the server is listed and enabled
4. 4. Read the MCP logs
5. 5. Run the command yourself
6. 6. Environment variables and tokens
7. 7. Restart Cursor
8. Problems we actually hit in testing

1. Is the config file in the right place?

Project servers go in .cursor/mcp.json in the project; global ones in ~/.cursor/mcp.json in your home folder. The top-level key is "mcpServers".

Our tests: the Cursor CLI looked for .cursor/ at the git repository root, not the folder we started it in. A .cursor/mcp.json in a sub-folder of a repo was ignored until that folder was its own git repo or the file moved to the repo root.

2. Check the JSON

One stray comma breaks the whole file, and then no server loads. JSON doesn't allow trailing commas or comments, and every key and string needs double quotes. Check the file with:

python3 -m json.tool .cursor/mcp.json

It prints the file back if it's valid, or the line and column of the first error.

3. Check the server is listed and enabled

In the app, open Settings and look at the MCP section: each server shows its status and can be toggled on or off. In the CLI, run agent mcp list; our working servers showed as e.g. playwright: ready. agent mcp list-tools <name> shows the tools the server offers (we compare that count with what the server reports directly).

Our tests: in the CLI we had to run agent mcp enable <name> before a newly added project server would load. Older installs name the command cursor-agent instead of agent.

4. Read the MCP logs

Open the Output panel (Ctrl+Shift+U, or Cmd+Shift+U on Mac) and choose MCP Logs from the dropdown. It shows server start-up, tool calls and errors.

5. Run the command yourself

Copy the exact command and args into a terminal and run them. A stdio server that starts correctly just waits silently for input (press Ctrl+C to stop). An error, a “command not found” or a crash here is the real problem, and the app's log will show the same thing.

Use ${workspaceFolder} for paths inside the project instead of relative paths.

6. Environment variables and tokens

Use "env": {"API_KEY": "${env:API_KEY}"} to read a value from your environment, or "envFile": ".env" to load a file (stdio servers only; remote servers don't support envFile). For remote servers, pass tokens in "headers", e.g. "Authorization": "Bearer ${env:MY_SERVICE_TOKEN}".

7. Restart Cursor

After changing a local server's files or config, restart Cursor (or toggle the server off and on in Settings).

Problems we actually hit in testing

From our test runs on 2026-10-13 and 2026-10-14. These apply to every client, because the cause is in the server or the machine, not the app.

• Wrong Node version. context-mode needs Node 22.5 or newer and failed to start under Node 20.19 in our protocol check. Draw.io MCP also needs Node 22+. Check with node --version. If your default Node is older, install Node 22 and point command at its absolute path (for example /path/to/node22/bin/npx). That is how we made both pass.
• npx / uvx not found. Most servers we test start with npx -y … (needs Node.js) or uvx … (needs uv). Apps started from a dock or menu may not see the PATH your terminal uses. Run which npx / which uvx in a terminal and use that absolute path as command.
• The server needs something else running. Jupyter MCP only works with a running Jupyter server. Draw.io MCP acts on a live draw.io editor that has to be open. We failed Jupyter until a local JupyterLab was started.
• No Docker. Terraform MCP's documented quick start runs it in Docker. Where Docker isn't available we used HashiCorp's official release binary as the command instead.
• “Private IP” or SSRF refusals behind a proxy or VPN. On our test machine, DNS resolved public sites to 198.18.x addresses (a proxy's fake-IP range). Fetch (reference), DuckDuckGo search and Open-WebSearch have private-address guards that then refused every URL. If fetch tools fail only on one network, this is a likely cause. Each server documents its own override flag; only relax it on a network you trust.
• It's the website, not your setup. DuckDuckGo search sometimes got “No results” from DuckDuckGo's bot detection. That failed a search task in one of our Cursor runs (2026-10-13) even though the server was connected and working.
• One mode of a server fails while another works. Fetch (reference)'s default (readability) mode exited with an error on our machine; its raw=true option worked.

Sources

• Cursor docs: Model Context Protocol
• Cursor docs: MCP in the CLI
• MCP docs: Debugging
• MCP docs: Inspector

Links checked 2026-10-14. Items marked “Our tests” come from our own harness runs, shown on each server page with the date.