cursor-mcp-json

To connect an MCP (Model Context Protocol) server in Cursor, you configure it in an mcp.json file. Based on the official Cursor documentation, this article covers where mcp.json lives, how to write server entries, and what to check when a connection fails; exact behavior can change as the docs are updated. (As of September 2026.)

Where does mcp.json belong?

Short answer: Place it in .cursor/mcp.json inside your project folder or ~/.cursor/mcp.json in your home directory; if both exist, they are merged and the project-level config wins on name conflicts.

Cursor documents two valid locations. The project-level file, .cursor/mcp.json inside your project folder, is meant to be committed to git so teammates share the same tools. The global file, ~/.cursor/mcp.json in your home directory, holds servers you want available everywhere.

If both files exist, Cursor merges them, and when the same server name appears in both, the project-level entry takes priority. After creating or editing the file, save it and restart Cursor for the change to take effect.

How do you write a server entry?

Short answer: Add a server name as a key under the mcpServers object, then use command/args/env (plus envFile) for local execution or url/headers for a remote connection.

Every entry lives as a key inside the top-level mcpServers object. For a local stdio server, the official docs give this shape:

{
  "mcpServers": {
    "server-name": {
      "command": "npx",
      "args": ["-y", "mcp-server"],
      "env": {
        "API_KEY": "value"
      }
    }
  }
}

The official reference table lists command (required, must be on your system PATH or given as a full path), args, env, and envFile as the fields for stdio servers. envFile only applies to stdio servers; remote servers do not support it.

A remote (HTTP/SSE) server that gives you a URL instead of a command connects through the url field, with headers added when authentication is required.

{
  "mcpServers": {
    "my-service": {
      "url": "https://mcp.example.com/sse",
      "headers": {
        "Authorization": "Bearer your-token-here"
      }
    }
  }
}

Values support config interpolation: ${env:NAME}, ${userHome}, ${workspaceFolder}, ${workspaceFolderBasename}, and ${pathSeparator} can be used inside command, args, env, url, and headers instead of hardcoding values. Save the file and restart Cursor so the new server is picked up.

What do you check when a connection fails?

Short answer: Start with JSON syntax and whether command is on your PATH, then check MCP Logs in the Output panel before toggling or re-adding the server.

First confirm the JSON in mcp.json is syntactically valid (missing commas or braces are common culprits). For stdio servers, check whether the executable named in command is actually on your system PATH, or supply a full path instead. If the server depends on environment variables set in your shell profile, make sure those variables are visible to Cursor; the docs note that you must restart Cursor after changing your shell profile.

Open the Output panel (Cmd+Shift+U on Mac, Ctrl+Shift+U on Windows/Linux) and select MCP Logs from the dropdown to see initialization errors, authentication issues, or server crashes. Also check the MCPs tab in Customize to confirm the server isn’t toggled off.

If that doesn’t resolve it, the official docs recommend removing the server from the MCPs tab in Customize and re-adding it. A single failing server does not affect the others; Cursor isolates server failures so the rest keep working.

FAQ

Q1. Can I register multiple servers at once?

A1. Yes, add multiple key-value pairs with unique names inside the mcpServers object.

Q2. Can I reference the current project path as a variable?

A2. Yes, the ${workspaceFolder} interpolation variable points to the project root that contains .cursor/mcp.json.

Q3. Can environment variables be loaded from a single file?

A3. Yes, stdio servers support an envFile field pointing to something like a .env file. Remote servers do not support envFile.

Q4. Can I disable a server temporarily without deleting it?

A4. Yes, use the toggle next to the server in the MCPs tab of Customize.

Sources