How to Debug an MCP Server That Will Not Connect in Cursor

Diagnose a red or failing MCP server in Cursor and get its tools showing up to the agent again.

8 minIntermediate

Visit Cursor

You added an MCP server, but Cursor shows a red dot and the agent cannot see its tools. MCP failures almost always come down to a handful of causes: a bad command path, a missing runtime, a wrong argument, or a crash on startup. This guide walks through diagnosing each so you can get the server connected.

An MCP server configured but showing as failed in Cursor
A terminal to test the command by hand
The server's documentation for its required arguments

Read the server's error in Cursor

Open the MCP settings page and look at the failing server. Cursor surfaces a short error and often a log toggle. The message usually points straight at the problem, such as a command not found or a missing argument.

Cursor Settings - MCP

MCP Servers

------------------------------

x my-server [failed]

error: spawn npx ENOENT

[ view logs ] [ retry ]

A failed server shows a red dot and an inline error.

Run the exact command yourself

Copy the command and args from your config and run them in a normal terminal. If it fails there too, the problem is the command, not Cursor. This isolates the issue in seconds.

zsh - reproduce the failure

$which npx

npx not found

the runtime is missing or not on PATH

$node -v && npm -v

command not found: node

Fix the common causes

Most failures map to one of these fixes. Work through them against the error you saw.

Symptom	Likely fix
`spawn npx ENOENT`	Install Node, or use an absolute path to the command in your config.
Connects then immediately drops	A required argument is missing; check the server docs and add it.
Authentication or 401 errors	An env var or token is missing; add it to the server's env block.
Works in terminal, fails in Cursor	PATH differs in the app; use a full path to node and the package.

Pass environment variables correctly

If the server needs a token, add an env block to its config entry rather than relying on your shell environment, which Cursor may not inherit.

.cursor/mcp.json

{
  "mcpServers": {
    "my-server": {
      "command": "/usr/local/bin/node",
      "args": ["/abs/path/to/server.js"],
      "env": {
        "API_TOKEN": "your-token-here"
      }
    }
  }
}

Use absolute paths when in doubt

The most common reason a server works in your terminal but fails in Cursor is a different PATH. Pointing command at the full path to node sidesteps it entirely.

Result: a clear path from a red, failing server to a green one. Reproduce the command, read the error, apply the matching fix, and the agent sees the server's tools again.