How to Debug an MCP Server That Will Not Connect in 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.

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.

Fix the common causes

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

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.

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

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.