Cursor MCP Not Working: Fix mcp.json and Connection Errors

When Cursor MCP is not working, the failure is usually in one of four places: Cursor did not load the expected mcp.json, the local command cannot start, authentication is missing, or the server connects without advertising usable tools. Debug those layers in order and the vague red status becomes a specific fix.

Do not start by reinstalling Cursor. Prove which layer is broken first.

Start with a known-good mcp.json

Cursor's official MCP documentation supports project and global configuration:

• Project: .cursor/mcp.json
• Global: ~/.cursor/mcp.json

A local Node server uses this shape:

{
  "mcpServers": {
    "example": {
      "command": "npx",
      "args": ["-y", "example-mcp-server"],
      "env": {
        "EXAMPLE_API_KEY": "replace-me"
      }
    }
  }
}

A remote Streamable HTTP server uses a URL:

{
  "mcpServers": {
    "example-remote": {
      "type": "http",
      "url": "https://example.com/mcp"
    }
  }
}

Use one server while debugging. A five-server config makes it harder to tell whether the parser, one package, or one credential failed.

Validate the file before opening Cursor:

jq empty .cursor/mcp.json

No output means the JSON parses. If jq reports a line number, fix the trailing comma, missing quote, or bracket first.

Fix “server not detected”

Confirm that the file is in the workspace root Cursor actually opened:

pwd
ls -la .cursor/mcp.json

The common mistake is opening apps/web as the Cursor workspace while placing .cursor/mcp.json two directories higher. Project configuration is scoped to the opened workspace.

If the server should be global, inspect:

ls -la "$HOME/.cursor/mcp.json"

Then check whether Cursor can see it. Current Cursor Agent CLI builds expose:

cursor-agent mcp list

The official Cursor CLI parameter reference also provides mcp list-tools <identifier> for checking whether a connected server exposes tools.

Restart Cursor after changing the config. A syntactically valid file can still require a reload before the MCP process is recreated.

Fix “command not found”

For a stdio server, Cursor launches the command exactly as configured. Test the same executable outside Cursor:

command -v node
command -v npx
npx -y example-mcp-server --help

If command -v returns nothing, Cursor will not find it either.

GUI applications sometimes inherit a smaller PATH than an interactive shell. Replace the command with its absolute path:

command -v npx

Then use that result:

{
  "mcpServers": {
    "example": {
      "command": "/opt/homebrew/bin/npx",
      "args": ["-y", "example-mcp-server"]
    }
  }
}

On Windows, confirm whether the executable belongs to Windows, PowerShell, Git Bash, or WSL. A Windows Cursor process cannot execute a Linux-only path without a WSL wrapper.

Also verify the package name. Several early MCP packages were renamed or archived. The fact that an old blog post shows an npm command does not mean that package still exists.

Fix environment variable failures

There are two separate questions:

1. Is the variable defined?
2. Did the Cursor process inherit it?

Check the shell:

test -n "$EXAMPLE_API_KEY" && echo "present" || echo "missing"

Do not print the secret itself.

Cursor supports environment values in the server configuration and OAuth for compatible remote servers. Recent builds also document ${env:NAME} interpolation in supported fields. A desktop-launched Cursor process may not receive variables defined only in .zshrc or .bashrc.

Test that distinction:

cursor .

Launch Cursor from a terminal where the variable is present. If MCP works there but not from the Dock or desktop launcher, the server is fine. The GUI process environment is the problem.

For a project committed to Git, never hardcode a token into .cursor/mcp.json. Prefer OAuth for remote servers. For local stdio servers, use a supported environment or envFile mechanism and keep the secret file out of version control.

Fix “connection failed” for remote servers

Test the endpoint without assuming the UI is correct:

curl -i https://example.com/mcp

An MCP endpoint may reject a plain GET, but the response still tells you whether DNS, TLS, routing, and the host are reachable.

Check these in order:

• The URL uses the current MCP endpoint, often /mcp
• Production uses HTTPS
• The server supports Streamable HTTP
• Authentication scopes are valid
• A proxy is not stripping required headers
• The service is reachable from the machine running Cursor

Cursor supports stdio, SSE, and Streamable HTTP, but SSE is the older remote transport. Prefer Streamable HTTP for a new setup.

For OAuth servers in Cursor Agent CLI:

cursor-agent mcp login example-remote

If login succeeds but connection still fails, clear the stale authorization in Cursor and authenticate again. A cached token can be validly formatted and still have the wrong audience or scopes.

Fix “connected, but no tools”

A green connection proves transport, not capability.

Ask the CLI for the advertised tools:

cursor-agent mcp list-tools example

If the list is empty, inspect the server:

• Does it implement the MCP tools/list capability?
• Did tool registration run before the transport connected?
• Does the authenticated user have access to those tools?
• Is Cursor showing the server but leaving individual tools disabled?

Cursor lets users enable or disable MCP tools from the Available Tools panel. Confirm that the tools are enabled before debugging the protocol.

Read the logs that name the failure

Cursor's troubleshooting guide documents Developer: Open Logs Folder and the developer console. Open the MCP output channel and look for the first error, not the last retry.

Typical messages map directly to a layer:

Redact tokens before sharing logs.

A ten-minute recovery sequence

1. Reduce the config to one server.
2. Validate mcp.json with jq.
3. Confirm the project or global file location.
4. Run the exact stdio command manually.
5. Use an absolute executable path if Cursor cannot resolve PATH.
6. Confirm required variables without printing them.
7. Test the remote host and authentication.
8. Restart Cursor.
9. List the server and its tools.
10. Read the first relevant MCP log entry.

If you need the initial setup rather than a repair, use the broader Cursor MCP server guide.

Cursor MCP troubleshooting FAQs

Should mcp.json be committed to Git?

Commit project-scoped server definitions when they help every contributor and contain no secrets. Keep tokens, user-specific paths, and private endpoints out of the committed file.

Why does MCP work in a terminal-launched Cursor only?

Your terminal exports environment variables or adjusts PATH, while the desktop launcher starts Cursor with a different environment. Move the required configuration to a process environment the GUI receives, or use explicit executable paths and supported secret handling.

Does Cursor support remote MCP servers?

Yes. Cursor supports Streamable HTTP and the older SSE transport in addition to local stdio servers. Prefer Streamable HTTP for new remote integrations.

Why did reinstalling Cursor not fix MCP?

MCP configuration and application data can survive an application reinstall. More importantly, a bad command, URL, or credential remains bad after reinstalling. Diagnose the server layer before clearing application data.

Build This Now treats tool configuration like any other integration: a declared boundary, a health check, and evidence that the capability is actually available. That mindset is more reliable than toggling settings until the red dot disappears.

The useful question is not “why is MCP broken?” It is “which of config, process, transport, auth, or capabilities failed?” Once you can answer that, the repair is usually small.

Posted by @speedy_devv