Guide · Cursor IDE

MCP server with Cursor IDE

Cursor has native MCP support, letting you connect custom tools that appear directly in Agent mode alongside Cursor's built-in capabilities. The config file lives in two places depending on whether you want the server available globally or only in a specific project. Cursor supports both stdio (local subprocess) and HTTP transport (remote servers). Once connected, Cursor's MCP panel lets you inspect which tools are loaded and test them — but it won't tell you if a remote server degrades between sessions. This guide covers setup, transport selection, and monitoring.

TL;DR

For a global server (all projects): edit ~/.cursor/mcp.json. For a project-scoped server: create .cursor/mcp.json in the project root and add it to .gitignore if it contains secrets. Use command + args for local stdio servers; use url for remote HTTP servers. Reload MCP servers from Cursor's Settings → Features → MCP or the command palette (MCP: Reload Servers). Verify in the MCP panel that your server shows a green dot and lists its tools. For remote servers, add the public URL to AliveMCP for continuous protocol-level monitoring between Cursor sessions.

Config file locations

Cursor reads MCP server configuration from two places, processed in priority order:

Project-scoped: .cursor/mcp.json in the project root. Applies only when that project is open. Useful for project-specific tools (database access, repo-aware code generators).
Global: ~/.cursor/mcp.json in your home directory. Applies to all projects. Useful for personal productivity tools you use everywhere.

If both files exist, project-scoped config takes precedence for servers with the same name. Servers with unique names from both files are merged into a single list.

The format follows the same structure used by Claude Desktop's claude_desktop_config.json:

{
  "mcpServers": {
    "server-name": {
      "command": "node",
      "args": ["/absolute/path/to/dist/index.js"]
    }
  }
}

Store project-scoped configs with secrets in .cursor/mcp.json and add that path to .gitignore. Commit a .cursor/mcp.json.example with placeholder values so teammates know what variables to fill in.

stdio transport: local server setup

For servers running on the same machine as Cursor, stdio is the simplest transport. Cursor spawns your server as a subprocess when a session starts, communicates via stdin/stdout, and terminates it when the session ends.

// ~/.cursor/mcp.json
{
  "mcpServers": {
    "my-tools": {
      "command": "node",
      "args": ["/Users/you/projects/my-mcp-server/dist/index.js"],
      "env": {
        "DATABASE_URL": "postgresql://localhost/mydb",
        "LOG_LEVEL": "error"
      }
    }
  }
}

Use absolute paths for both the command and args. Cursor's subprocess environment may not include your shell's PATH or custom environment setup from .zshrc / .bash_profile. If node isn't found, use the full path: /usr/local/bin/node (find it with which node).

For TypeScript projects using tsx or ts-node:

{
  "mcpServers": {
    "my-ts-server": {
      "command": "/usr/local/bin/npx",
      "args": ["tsx", "/Users/you/projects/my-server/src/index.ts"]
    }
  }
}

Keep server startup fast — Cursor's Agent mode calls tools synchronously and users notice lag during initialization. Avoid connecting to remote databases or external APIs during the initialize handshake; defer those connections to the first tool call or use connection pooling with pre-warmed connections. See MCP server cold start optimization for techniques.

HTTP transport: remote server setup

Cursor supports HTTP transport for MCP servers, enabling connections to servers deployed on Railway, Render, Fly.io, or any public HTTPS endpoint. The SSE endpoint URL goes in the url field:

{
  "mcpServers": {
    "remote-tools": {
      "url": "https://my-mcp-server.fly.dev/sse"
    }
  }
}

If your server requires authentication, add a headers field:

{
  "mcpServers": {
    "remote-tools": {
      "url": "https://my-mcp-server.fly.dev/sse",
      "headers": {
        "Authorization": "Bearer your-api-key"
      }
    }
  }
}

For the StreamableHTTP transport variant (used by newer MCP SDK versions), the URL points to the main endpoint rather than a dedicated SSE path. Cursor's HTTP client handles both SSE streaming and standard HTTP request-response patterns, so the same url field works for both transport variants — the server negotiates which mode to use during the initialize exchange.

See MCP server SSE transport and MCP server HTTP transport for server-side implementation details.

Reloading servers without restarting Cursor

Unlike Claude Desktop, Cursor doesn't require a full restart to reload MCP config changes. You can reload servers from:

Command palette: Cmd+Shift+P → type "MCP" → select MCP: Reload Servers
Cursor Settings → Features → MCP → click the reload button

After reloading, Cursor re-reads the config files and restarts all server connections. For stdio servers, this means killing and respawning the subprocess. For HTTP servers, this means closing and reopening the SSE connection.

During development, save the config file and run "MCP: Reload Servers" to pick up changes without losing your Cursor window state. If a server fails to connect after reload, the error appears in the MCP panel immediately rather than silently.

Inspecting servers in Cursor's MCP panel

Cursor shows connected MCP servers in its settings panel. Navigate to Settings → Features → MCP to see:

Each server's connection status (green = connected, red = failed)
The list of tools each server exposes
Error messages for servers that failed to connect

When Cursor's Agent mode is active, tools from all connected MCP servers appear in the tool use area. Cursor automatically selects which tools to call based on the conversation — you don't need to explicitly reference tool names unless you want to force a specific tool call.

If a tool is not appearing, verify in the MCP panel that the server is connected and that the tool name matches what the server advertises via tools/list. Tool names are case-sensitive.

Troubleshooting connection failures

Common failure patterns and how to diagnose them:

Server shows red in MCP panel:

For stdio servers: check that the command path is absolute and the executable exists. Run the command manually in a terminal to confirm it starts without errors.
For HTTP servers: verify the URL is reachable (curl -N https://your-server/sse should open an event stream). Check that the server isn't behind a firewall blocking your network.

Server connects but tools don't appear:

The server's tools/list response may be returning an empty array. Test with the MCP inspector tool: npx @modelcontextprotocol/inspector your-server-url.
Tool names with spaces or special characters may not display correctly. Use snake_case or kebab-case for tool names.

Tools call but return errors:

Check server logs for the actual error. Cursor shows a generic "tool call failed" message; the detailed error is on the server side.
Verify the tool's input schema matches what Cursor is sending. Use Zod validation in tool handlers to get structured error messages back to the client.

stdio server crashes on startup:

Any output to stdout before the MCP handshake (console.log, startup banners) breaks the protocol. Use stderr for all application logs.
Unhandled promise rejections during async initialization crash the process silently. Wrap startup code in try/catch and log errors to stderr.

See MCP server debugging for a comprehensive troubleshooting workflow.

Monitoring remote MCP servers used from Cursor

Cursor's MCP panel only checks server status when you open Settings or reload servers. Between sessions, there's no visibility into whether a remote server has gone down, had its SSL certificate expire, or is returning errors for tool calls.

For remote MCP servers connected to Cursor, add the server URL to AliveMCP. AliveMCP runs the full initialize → tools/list handshake from an external network on a regular schedule and alerts you when the protocol layer fails. This means you learn about outages before a Cursor session tries to use a tool and gets a cryptic failure rather than after.

See MCP server observability for how to combine external monitoring with Cursor's MCP panel for full visibility.