Cursor MCP Server Failed to Connect: Causes and Fixes

Quick Answer

When Cursor reports MCP server failed to connect, it means the client could not complete a working session with the configured server. If the failure affects Cursor itself rather than one MCP server, start with the Cursor connection error guide. The failure can happen at any of eight distinct layers: process launch, configuration parsing, environment/PATH, transport, MCP initialization, authentication, session management, or remote server availability.

Fastest diagnostic path:

1. Open Cursor Settings → MCP and identify which server shows a red or failed status.
2. Click the log/output button next to that server and read the first error line.
3. Match the error to the 60-second checklist below.
4. Apply the targeted fix — do not guess.

Cursor MCP Server Failed to Connect: 60-Second Fix Checklist

Work through this list top-to-bottom. Stop at the first item that fails.

• Config file is valid JSON — paste your ~/.cursor/mcp.json (or workspace .cursor/mcp.json) into a JSON validator
• command field contains a real executable — run which npx / which uvx / which node in your terminal to confirm it exists
• Package is installed — npx -y some-server --version or uvx some-server --version succeeds in a fresh terminal
• args array is correct — every element is a separate string, flags and values are not merged
• Required env keys are set — any API key, token, or URL the server needs is present in the env block
• Transport type matches the server — stdio for local process servers, http (Streamable HTTP) or sse for remote servers
• Server URL is correct — for remote servers, the exact endpoint path matches the server docs (e.g. /mcp, /sse); for Atlassian, verify the official MCP server URL
• Full executable path is used — if the server works in terminal but not Cursor, replace the command with its full absolute path
• Cursor was restarted after the last config change
• Server is running — for remote servers, confirm the endpoint is reachable with curl

Why Cursor MCP Servers Fail to Connect

Every connection failure belongs to one of these layers. Identifying the layer saves significant time.

Check Your Cursor MCP Configuration

Cursor reads MCP configuration from two locations:

• Global: ~/.cursor/mcp.json
• Workspace: .cursor/mcp.json in the project root

Workspace config takes precedence for servers defined in both files.

Correct configuration structure

{
  "mcpServers": {
    "my-server": {
      "command": "npx",
      "args": ["-y", "@my-org/my-mcp-server"],
      "env": {
        "API_KEY": "sk-..."
      }
    },
    "remote-server": {
      "url": "https://api.example.com/mcp",
      "transport": "http"
    }
  }
}

Common configuration mistakes

Wrong: merging flags and values into one string

"args": ["-y @my-org/my-mcp-server"]

Correct: each token is a separate array element

"args": ["-y", "@my-org/my-mcp-server"]

Wrong: using a shell alias or short name

"command": "my-server"

Correct: full package name with npx, or absolute path

"command": "npx",
"args": ["-y", "@my-org/my-mcp-server"]

Wrong: missing transport field for HTTP servers

{
  "url": "https://api.example.com/mcp"
}

Correct:

{
  "url": "https://api.example.com/mcp",
  "transport": "http"
}

For SSE-based servers (older pattern), use "transport": "sse" and provide the SSE endpoint URL.

Always validate your JSON before restarting Cursor. A single trailing comma or missing brace silently prevents all servers from loading.

Cursor MCP Server Failed to Start

If the MCP log shows a spawn error, ENOENT, command not found, or the process exits immediately with a non-zero code, the server never started.

spawn ENOENT — executable not found

This is the single most common Cursor MCP error. It means the OS cannot locate the binary specified in command. For a detailed walkthrough of this specific error, see the Cursor MCP spawn npx ENOENT guide.

Quick fix:

# Find the absolute path
which npx        # e.g. /usr/local/bin/npx
which uvx        # e.g. /home/user/.local/bin/uvx
which node       # e.g. /usr/local/bin/node

Then use the absolute path in your config:

{
  "command": "/usr/local/bin/npx",
  "args": ["-y", "@modelcontextprotocol/server-filesystem", "/home/user"]
}

Package not installed or unavailable

npx -y will attempt to download the package if it is not cached. If the download fails (network issue, private registry, wrong package name), the process exits immediately. Test independently:

npx -y @my-org/my-mcp-server --version

For Python-based servers using uvx:

uvx my-mcp-server --version

Process exits immediately

The server starts but crashes before the MCP handshake. Causes:

• Missing required environment variable (server throws on startup)
• Dependency not installed
• Wrong args causing the CLI to print help and exit

Check the env block in your config. If the server requires DATABASE_URL or OPENAI_API_KEY, it must be present:

"env": {
  "OPENAI_API_KEY": "sk-...",
  "DATABASE_URL": "postgresql://localhost/mydb"
}

Read stderr in the Cursor MCP log — the crash reason is almost always printed there.

MCP Server Works in Terminal but Fails in Cursor

This is the second most reported Cursor MCP connection problem. The server runs fine when you execute it manually, but Cursor cannot start it.

Why it happens: Cursor is a GUI application. On macOS and Linux, GUI apps do not source .bashrc, .zshrc, or .profile. They start with a minimal system PATH that typically does not include:

• /usr/local/bin (Homebrew, nvm, Node.js)
• ~/.local/bin (pip, uv, uvx)
• ~/.nvm/versions/node/.../bin (nvm-managed Node)
• ~/.cargo/bin (Rust tools)
• Conda/pyenv shims

Diagnostic flow

Terminal: `which npx` → /usr/local/bin/npx  ✓
Cursor MCP log: spawn ENOENT for 'npx'       ✗
Conclusion: PATH problem
Fix: use /usr/local/bin/npx in command field

Solutions ranked by reliability

1. Use full absolute path (most reliable):

{ "command": "/usr/local/bin/npx" }

1. Set PATH explicitly in the env block:

"env": {
  "PATH": "/usr/local/bin:/usr/bin:/bin"
}

1. Use a wrapper shell script that sources your profile before launching the server (useful for version managers like nvm or pyenv).

For nvm users, the Node.js binary path changes with each version. Find yours with:

node -e "console.log(process.execPath)"
# e.g. /Users/you/.nvm/versions/node/v20.11.0/bin/node

Cursor Cannot Connect to a Remote MCP Server

For remote MCP servers accessed over HTTP, failures fall into distinct categories.

Wrong endpoint URL

Different servers expose different paths. Common patterns:

• /mcp — Streamable HTTP (current standard)
• /sse — legacy SSE transport
• /message — legacy HTTP+SSE transport

Always verify the exact path in the server's documentation. A 404 almost always means the URL path is wrong, not that the server is down.

Transport mismatch

Streamable HTTP (the current MCP transport standard) and SSE are not interchangeable. If you connect with "transport": "http" to an SSE-only server, the connection will fail. Check the server docs and set the transport to match:

// Streamable HTTP server
{ "url": "https://api.example.com/mcp", "transport": "http" }

// SSE server (legacy)
{ "url": "https://api.example.com/sse", "transport": "sse" }

HTTP error codes

Authentication and OAuth

For servers requiring bearer tokens, pass the token in the headers field if your Cursor version supports it, or in the env block if the server reads it from the environment. For OAuth-based servers, Cursor initiates the OAuth flow automatically when the server advertises it during initialization — ensure your callback URL and client credentials are correctly configured on the server side.

TLS and certificate failures

If the server uses a self-signed certificate or an internal CA, Cursor's embedded Chromium may reject the TLS handshake. Use a publicly trusted certificate in production. For development, test with a tool like curl -k to confirm the server is otherwise reachable, but avoid disabling TLS verification in production configs.

Reverse proxies

Streamable HTTP requires that the proxy correctly forwards chunked transfer encoding and does not buffer responses. Nginx requires proxy_buffering off. Verify your proxy config is passing through streaming responses.

Cursor MCP Server Connects and Immediately Disconnects

The server process starts (no ENOENT), the transport connects, but the session drops within seconds.

stdout contamination (stdio servers)

For stdio-based MCP servers, the MCP protocol uses stdout exclusively for JSON-RPC messages. If anything — a console.log, a debug print, a startup banner — writes non-JSON text to stdout before or between protocol messages, Cursor will fail to parse the stream and close the connection.

// WRONG — breaks the stdio MCP protocol
console.log('Server starting...');

// CORRECT — use stderr for all diagnostic output
console.error('Server starting...');

Check the MCP log for JSON parse errors. If you see Unexpected token or Invalid JSON, stdout contamination is the cause.

Protocol version mismatch

During initialization, the client and server exchange initialize / initialized messages that include the protocol version. If the server requires a version Cursor does not support (or vice versa), initialization fails. Update the server package to the latest version.

Initialization failure

The server may crash during the initialization handler — for example, trying to connect to a database that is not available. The error will be in stderr. Read it in the Cursor MCP log.

For detailed help with connection-closed errors, see how to fix MCP error -32000 connection closed.

Cursor MCP Server Connected but No Tools Appear

A green status in Cursor Settings → MCP means the transport connected and initialization completed. But tools still may not appear.

This is a tool discovery failure, not a connection failure. The causes are distinct:

1. Server returns empty tools/list — the server connected successfully but has no tools registered. Check the server implementation.

2. Server did not declare tools capability — during initialization, the server must include "tools" in its capabilities response. If missing, Cursor will not request the tool list.

3. Cursor cache — after fixing a config issue, Cursor sometimes shows a stale state. Fully restart Cursor (not just reload window) to force a fresh initialization.

4. Wrong server connected — if you have multiple servers with similar names, confirm you are looking at the right one.

Verify with MCP Inspector:

npx @modelcontextprotocol/inspector npx -y @my-org/my-mcp-server

Navigate to the Tools tab. If tools appear in Inspector but not in Cursor, the issue is Cursor's cache or config. If no tools appear in Inspector either, fix the server implementation.

For more on diagnosing connection problems versus tool discovery failures, see the MCP server failed to connect causes and fixes guide.

How to Find and Read Cursor MCP Logs

Cursor exposes server output directly in the settings UI:

1. Open Cursor Settings (Cmd/Ctrl + Shift + J, then navigate to MCP, or via the gear icon)
2. Find the MCP section — each configured server is listed with a status indicator
3. Click the log or output button next to the failing server
4. Read the output — it contains stdout, stderr, and connection lifecycle events

For deeper diagnostics, open Help → Toggle Developer Tools and check the Console tab. Filter by MCP to isolate relevant messages.

What to look for in the logs

Test the MCP Server Outside Cursor

Before debugging Cursor-specific behavior, confirm the server itself works.

For stdio servers

# Replicate exactly what Cursor runs
API_KEY="sk-..." npx -y @my-org/my-mcp-server

# Then manually send an initialize request via stdin

Or use MCP Inspector (easiest):

npx @modelcontextprotocol/inspector \
  npx -y @my-org/my-mcp-server

For remote HTTP servers

# Test the endpoint directly
curl -X POST https://api.example.com/mcp \
  -H "Content-Type: application/json" \
  -H "Authorization: Bearer sk-..." \
  -d '{"jsonrpc":"2.0","id":1,"method":"initialize","params":{"protocolVersion":"2024-11-05","capabilities":{},"clientInfo":{"name":"test","version":"1.0"}}}'

A valid MCP server returns a JSON-RPC response with serverInfo and capabilities.

Key principle: Use the exact same command, args, environment variables, URL, and transport that Cursor uses. If it works here and fails in Cursor, the problem is Cursor's config or environment — not the server.

Debug Cursor MCP Connection Failures with MCP Inspector

MCP Inspector is the official diagnostic tool for MCP servers. It provides an interactive UI that tests the full connection lifecycle independently of Cursor.

# Install and run in one step
npx @modelcontextprotocol/inspector <command> [args...]

# Examples
npx @modelcontextprotocol/inspector npx -y @modelcontextprotocol/server-filesystem /tmp
npx @modelcontextprotocol/inspector uvx my-python-server
npx @modelcontextprotocol/inspector node /absolute/path/to/server.js

Inspector opens at http://localhost:5173 and shows:

• Connection status — whether the transport connected
• Initialize result — server capabilities and protocol version
• Tools tab — full tools/list response
• Resources and Prompts tabs — additional capability inspection
• Request/Response log — raw JSON-RPC message trace

Using Inspector to isolate the failure layer

For a full Inspector walkthrough, see the MCP Inspector complete guide. You can also test any publicly accessible MCP server directly at MCPForge MCP Server Tester.

Cursor MCP Server Failed to Connect: Troubleshooting Table

For a broader reference on MCP error codes and their meanings, see the MCP error codes guide.

Official Sources

• Cursor MCP documentation - official Cursor reference for mcp.json configuration, supported transports, OAuth behavior, logs, and troubleshooting.
• MCP transports specification - official stdio and Streamable HTTP behavior, including stdout rules and HTTP headers.
• MCP Inspector documentation - official local testing tool for verifying MCP server connectivity outside Cursor.

How to Confirm the Fix

After applying a fix, verify each layer in sequence:

1. Config is valid — JSON validates without errors, required fields are present
2. Server starts — status indicator in Cursor Settings → MCP turns green
3. No immediate disconnect — server remains connected for more than a few seconds
4. Initialization completed — no initialization errors in the MCP log
5. Authentication passed — no 401/403 errors in the log (for remote servers)
6. Tools appear — the expected tools are listed in the Cursor AI panel or Settings → MCP tool list
7. Tool call succeeds — invoke a simple tool (e.g. list files, ping) and confirm it returns a result

If any step fails, return to the troubleshooting table and address that specific layer.

How to Prevent Cursor MCP Connection Failures

Most connection failures are preventable with good configuration hygiene:

Use absolute paths. Never rely on PATH resolution working the same in Cursor as in your terminal. Always find and use the full path to executables.

Validate JSON before saving. A single syntax error silently disables all your MCP servers. Keep a JSON validator in your workflow.

Keep environment variables in the env block. Never assume Cursor will inherit your shell environment. Explicitly declare every variable the server requires.

Pin package versions. Using npx -y package@latest can break unexpectedly when a new version ships a breaking change. Pin to a specific version in production configs.

Use stderr for all server-side logging. This applies to stdio servers you control. Anything written to stdout must be valid JSON-RPC. Move all debug output to stderr.

Test with MCP Inspector before adding to Cursor. If a server works in Inspector, it should work in Cursor. This catches server-side issues before they become Cursor debugging sessions.

Keep Cursor updated. MCP protocol support improves with each Cursor release. Protocol version compatibility issues are often resolved by updating.

Document your MCP configs. Keep a commented version of your mcp.json in a secure location (without secrets) so you can quickly restore a working configuration.

For general MCP connection failure patterns that apply across all MCP clients, the MCP failed to connect guide covers client-agnostic diagnostics that complement this Cursor-specific guide.