Set Up MCP Servers in Cursor: Config Scopes, Errors, JSON (2026)

Cursor connects to external tools and data sources through the Model Context Protocol (MCP). MCP is the open standard governed by the Linux Foundation’s Agentic AI Foundation (Linux Foundation, “Agentic AI Foundation Launch,” December 9, 2025). Adding MCP servers to Cursor takes three paths: the GUI panel in Settings, manual JSON configuration in a project-scoped file, or manual JSON configuration in a global-scoped file.

This guide covers all three methods, the precedence rules when project and global scopes conflict, and the three colored status indicators. It also provides fixes for the two highest-volume error messages: “specific node not found” and “spawn npx enoent.”

Independent setup notes from real installs across macOS, Windows, and Linux.

What Do You Need Before Setting Up MCP in Cursor?

Cursor supports MCP on Free, Pro, and Business plans. No paid subscription is required for MCP server connections. Install Node.js 18+ for npm-based servers and Python 3.10+ for uvx-based servers before adding any server entry.

MCP server support is available on every Cursor tier, including the free plan. The free plan limits which AI models are available for conversation, but it does not restrict MCP server connections or tool invocations.

Does MCP Work on the Cursor Free Plan?

Yes. Cursor Free supports MCP server connections without restriction. The free plan limits model access (fewer premium model calls per month), but MCP servers connect and expose tools on all plans:

Cursor Free at $0/month (limited model calls, full MCP support)
Cursor Pro at $20/month (500 premium model calls, full MCP support)
Cursor Business at $40/seat/month (unlimited premium calls, full MCP support, admin controls)

Which Runtimes Does Cursor Require for MCP Servers?

MCP servers are standalone programs that Cursor launches as child processes. The runtime depends on the server’s language:

Node.js 18+ for servers distributed through npm (Filesystem, GitHub, Sequential Thinking, and most community servers)
Python 3.10+ with the uvx package runner for servers distributed through PyPI
Docker Desktop for containerized servers (must be running before Cursor launches the server)

Verify installation by running node --version or python3 --version in Cursor’s integrated terminal. A missing runtime is the cause of the “spawn npx enoent” error covered in the troubleshooting section below.

How Do You Add MCP Servers Through the Cursor GUI?

Open Cursor Settings, navigate to Features, then Tools & Integrations. Click “Add New MCP Server” or “Add Custom MCP.” Enter the server name, command, arguments, and environment variables in the form fields. Cursor validates the connection automatically after saving.

The GUI method is the fastest path for a first MCP server. Cursor writes the JSON config file in the background, so you do not need to create or edit any files manually.

Where Is the MCP Settings Panel in Cursor?

Open Cursor Settings through one of 3 methods:

Keyboard shortcut: Cmd+, (macOS) or Ctrl+, (Windows/Linux)
Menu: Cursor > Settings (macOS) or File > Preferences > Settings (Windows/Linux)
Command palette: Cmd+Shift+P > type “Cursor Settings” > select it

Navigate to Features in the left sidebar, then scroll to Tools & Integrations. The MCP section lists all configured servers with their status indicators.

What Does the “Add Custom MCP” Form Look Like?

Click “Add New MCP Server” to open the configuration form. The form has 5 fields:

Name: A descriptive label for the server (e.g., “filesystem” or “github”)
Type: stdio (Standard Input/Output, for local servers that Cursor launches as a child process) or sse/http (for remote servers)
Command: The executable to launch (e.g., “npx” or “uvx”)
Arguments: Space-separated arguments passed to the command
Environment variables: Key-value pairs for API keys and tokens

Click Save. Cursor launches the server process and displays a status indicator within 5 seconds.

The GUI method writes to the project-scoped mcp.json file in the background. For more control over scope, file location, and version-controlled configurations, use the manual JSON method described next.

How Do You Add MCP Servers Through the JSON Config File?

Create a file named mcp.json inside the .cursor directory at your project root for project-scoped configuration, or at ~/.cursor/mcp.json for global configuration. Add server entries inside the “mcpServers” object. Save the file and Cursor detects the change without requiring a restart.

Manual JSON configuration provides more control than the GUI and enables version-controlled MCP setups through project-scoped config files that live in your repository.

Where Does the mcp.json File Go? (Project vs Global Scope)

Cursor reads MCP configuration from 2 locations:

Project scope: <project-root>/.cursor/mcp.json applies to that workspace only. Commit this file to your repository to share MCP configuration with your team.
Global scope: ~/.cursor/mcp.json applies to every project. Use this for personal servers you want available everywhere (filesystem access, memory, personal GitHub token).

The project-scope file lives inside the .cursor directory at the root of your project. Create the directory and file manually. The global-scope file lives in your home directory’s .cursor folder.

What Happens When Project and Global Scopes Conflict?

Project-level entries override global entries with the same server name. Cursor merges both scopes at launch. A server named “github” in the project mcp.json replaces a server named “github” in the global mcp.json.

Servers with different names from both scopes run simultaneously. A project-scoped “project-github” and a global-scoped “personal-github” both connect and both consume tool slots.

What Does a Correct mcp.json Entry Look Like?

The mcp.json format matches the Claude Desktop config structure. The root key is “mcpServers.” Each server entry contains command, args, and optionally env.

Example: Filesystem server (Node.js, stdio)

{
  "mcpServers": {
    "filesystem": {
      "command": "npx",
      "args": ["-y", "@modelcontextprotocol/server-filesystem", "/Users/you/project"],
      "env": {}
    }
  }
}

Example: GitHub server (Python, with API token)

{
  "mcpServers": {
    "github": {
      "command": "uvx",
      "args": ["mcp-server-github"],
      "env": {
        "GITHUB_PERSONAL_ACCESS_TOKEN": "ghp_your_token_here"
      }
    }
  }
}

The file name must be mcp.json. Cursor does not read files named mcp-config.json, config.json, or mcp.jsonc.

How Do You Add a Remote Server with Streamable HTTP or SSE?

Remote MCP servers use a URL instead of a command. Cursor supports both streamable HTTP (current standard) and SSE (Server-Sent Events, legacy transport).

{
  "mcpServers": {
    "remote-server": {
      "url": "https://mcp.example.com/sse",
      "headers": {
        "Authorization": "Bearer your_token_here"
      }
    }
  }
}

The url field replaces command and args. The headers field passes authentication. SSE URLs work through the same config format.

How Do You Add Multiple Servers?

Add each server as a separate named entry inside the “mcpServers” object.

{
  "mcpServers": {
    "filesystem": {
      "command": "npx",
      "args": ["-y", "@modelcontextprotocol/server-filesystem", "/Users/you/project"]
    },
    "github": {
      "command": "uvx",
      "args": ["mcp-server-github"],
      "env": { "GITHUB_PERSONAL_ACCESS_TOKEN": "ghp_your_token" }
    },
    "sequential-thinking": {
      "command": "npx",
      "args": ["-y", "@modelcontextprotocol/server-sequential-thinking"]
    }
  }
}

Cursor enforces a 40-tool ceiling across all connected servers. Tools beyond 40 are silently dropped without any error message or warning. 3 to 5 servers is the practical limit for most workflows. Disconnect servers you are not actively using for the current project.

After saving the config file, Cursor attempts to connect each server automatically. The status indicators described next confirm whether each connection succeeded.

How Does Cursor Indicate Whether MCP Servers Are Connected?

Cursor displays a colored status dot next to each server name in the Settings panel. A green dot means the server connected and registered tools. A yellow dot means Cursor is attempting to connect or restart. A red dot means the connection failed.

The status indicators provide instant visual feedback. No terminal output or log file inspection is needed for basic connection checks.

What Do the Green, Yellow, and Red Dots Mean?

Each color represents a specific connection state:

Green dot: The server process launched, completed the MCP handshake, and registered at least one tool. The server is ready for use.
Yellow dot: Cursor is in the process of launching the server, waiting for the handshake response, or restarting after a configuration change. Wait 10 to 15 seconds. A yellow dot that persists beyond 30 seconds indicates a slow server startup or a hanging process.
Red dot: The server failed to connect. Causes include a missing runtime, invalid credentials, a malformed config entry, or a server crash during initialization. The troubleshooting section below covers each cause.

How Do You Restart a Failed Server Without Restarting Cursor?

Click the refresh icon (circular arrow) next to the server name in Settings > Features > Tools & Integrations. Cursor terminates the existing server process and launches a new one from the current config.

The refresh icon restarts a single server without affecting other connected servers. A full Cursor restart (Cmd+Q then reopen) restarts all servers simultaneously.

The sections above cover the complete setup and verification workflow. The sections below address error diagnostics, platform comparisons, and server recommendations.

What Are the Common MCP Errors in Cursor and How Do You Fix Them?

The 5 most common Cursor MCP errors are “specific node not found” (npm package missing or misspelled), “spawn npx enoent” (Node.js not in PATH), connection timeout (handshake failure), silent tool loss (the 40-tool ceiling), and red-dot-no-message (server crash with no visible output).

These two error messages are the most frequently encountered MCP problems in Cursor. Fixing them takes under 2 minutes once you know the cause.

“Specific Node Not Found”: npm Package Missing or Misspelled

This error appears when the npm package name in the args array does not exist in the npm registry. Cursor attempted to run npx -y package-name and npm reported that the specified package was not found.

3 common causes:

Typo in the package name: “@modelcontextprotocol/server-filesytem” instead of “@modelcontextprotocol/server-filesystem” (missing ‘s’)
Deprecated or renamed package: Some early MCP server packages were renamed. The old name returns “not found.” Check the server’s GitHub repository for the current package name.
Scoped package without the scope: “server-filesystem” instead of “@modelcontextprotocol/server-filesystem”

Fix: copy the exact package name from the server’s official README or npm page. Paste it directly into the args array. Do not type it from memory.

“spawn npx enoent”: Node.js Not Installed or Not in PATH

Cursor attempted to run the command “npx” and the operating system reported that the executable does not exist at any location in the system PATH.

2 common causes:

Node.js is not installed: Run node --version in Cursor’s integrated terminal. No output or “command not found” confirms the missing installation. Install Node.js 18+ from nodejs.org.
Node.js is installed but not in Cursor’s PATH: Cursor uses its own environment, which does not always inherit the shell’s PATH. Fix: use the absolute path to npx in the command field. Run which npx (macOS/Linux) or where npx (Windows) in a terminal to find the full path, then use that path as the command value.

{
  "mcpServers": {
    "example": {
      "command": "/usr/local/bin/npx",
      "args": ["-y", "@modelcontextprotocol/server-filesystem", "/Users/you/project"]
    }
  }
}

Connection Timeout: Server Started but Did Not Respond

Cursor launched the server process but did not receive an MCP handshake response within the expected window.

3 common causes:

Network dependency unavailable: The server requires an internet connection that is down or blocked by a firewall
Missing or incorrect arguments: The server is waiting for input that was not provided in the args array
Server crashed silently during initialization: The process started and terminated before completing the handshake

Click the red dot, then click “Show Logs” to view the server’s output. The log output reveals which step failed.

Server Connected but Tools Are Missing (the 40-Tool Ceiling)

Cursor enforces a maximum of 40 tools across all connected MCP servers. Tools beyond 40 are silently dropped. No error message, no warning, no log entry.

The 40-tool ceiling produces a specific symptom: a server shows a green dot (connected) but some or all of its tools do not appear in the model’s tool list. The server itself is healthy. Cursor chose not to load its tools because the 40-tool budget was already consumed by other servers.

Fix: disconnect servers you are not actively using. Each server’s tool count is visible in Settings next to its name. Prioritize servers with fewer, more targeted tools over servers that expose large tool sets.

Red Dot but No Error Message: How to Read Cursor’s MCP Logs

A red status dot with no visible error message indicates the server process crashed before producing output. The crash details are in Cursor’s MCP log files.

Access the logs through 2 methods:

GUI method: Click the red dot next to the failed server in Settings, then click “Show Logs” or “View Output”
File method: Open Cursor’s log directory. On macOS: ~/Library/Application Support/Cursor/logs/. On Windows: %APPDATA%\Cursor\logs\. On Linux: ~/.config/Cursor/logs/

Search the log files for the server name. The log entry contains the process exit code and any stderr output the server produced before crashing.

How Does Cursor MCP Setup Differ from Claude Desktop MCP Setup?

Cursor and Claude Desktop both speak the Model Context Protocol, but they configure servers through different mechanisms. Understanding the differences prevents wasted time when following tutorials written for the wrong client.

Claude Desktop MCP setup guide covers the full process for that client.

Config File Location and Scope Differences

Claude Desktop uses a single config file at a fixed OS-specific path (e.g., ~/Library/Application Support/Claude/claude_desktop_config.json on macOS). Cursor uses 2 scopes: a project-level .cursor/mcp.json and a global ~/.cursor/mcp.json. The project-level file enables per-repository MCP configurations that travel with the codebase.

Claude Desktop requires a full application quit (Cmd+Q) to reload MCP configuration. Cursor detects config file changes automatically and offers a refresh button for individual servers.

GUI vs JSON-Only Setup

Cursor provides a GUI panel (Settings > Features > Tools & Integrations) for adding and managing MCP servers without editing JSON. Claude Desktop requires either the Extensions Directory or manual JSON editing. Cursor’s GUI is faster for quick additions. JSON is better for version-controlled, team-shared configurations.

Which MCP Servers Should You Install First in Cursor?

Start with 3 servers that cover file access, code context, and structured reasoning. A minimal first setup validates the entire pipeline (config, status dot, tool registration, invocation) before you connect additional servers.

Browse the full server index for the complete directory.

Three Servers for a First Setup

Filesystem exposes local file reading and writing within a specified directory. It requires no API key. Add it with the path to your current project. Test by asking Cursor to list the files in that directory.

GitHub exposes issues, pull requests, and repository contents. It requires a personal access token scoped to public_repo (or repo for private repositories). Test by asking Cursor to list your open issues. GitHub MCP server setup and scoping guide covers the token scope decisions.

Sequential Thinking provides structured chain-of-thought reasoning. It requires no API key and no external service. Test by asking Cursor to break down a complex coding problem step by step.

These 3 servers together register approximately 15 to 25 tools, well within the 40-tool ceiling.

Frequently Asked Questions

Does Cursor support remote MCP servers?

Yes. Cursor supports both streamable HTTP and SSE transports for remote servers. Configure them using the url and headers fields instead of command and args in the mcp.json file.

Can you use the Cursor MCP Marketplace to install servers?

Yes. The Cursor MCP Marketplace (introduced in 2026) provides verified servers that install with one click through Settings > Features > Tools & Integrations. The marketplace handles configuration and credential prompting automatically. Cursor’s MCP feature limits and pricing covers marketplace availability by plan.

How many MCP servers can Cursor run at once?

No hard limit on the number of servers. The practical constraint is the 40-tool ceiling. Each server registers a set of tools. When the total tool count across all servers exceeds 40, Cursor silently drops the overflow. 3 to 5 servers is practical for most projects.

Is Cursor MCP setup the same on macOS, Windows, and Linux?

The mcp.json format and GUI method are identical across all 3 operating systems. The only difference is the global config file path: ~/.cursor/mcp.json on macOS and Linux, %USERPROFILE%\.cursor\mcp.json on Windows. Project-scoped .cursor/mcp.json files work identically on every platform.

How Do You Set Up MCP Servers in Cursor?