Agents Index

Cursor MCP Setup: mcp.json, Remote URLs, Headers and Env

Updated 2026-11-18

To set up an MCP server in Cursor, add it to .cursor/mcp.json in your project or ~/.cursor/mcp.json in your home directory. A local server uses command and args. A remote server uses url, plus optional headers. Cursor reloads the entry and lists the server's tools in chat.

Pick a config file

Cursor reads MCP servers from two places:

FileScopeUse it for
.cursor/mcp.jsonCurrent projectServers the whole team uses with this repo
~/.cursor/mcp.jsonAll projectsPersonal servers you want everywhere

Create the file if it does not exist. Do not put secrets in the project file if you commit it. Use environment variables instead, as shown below.

Add a remote server with url

A remote server is reached over HTTP. The two fields to know are:

{
  "mcpServers": {
    "example-remote": {
      "url": "https://mcp.example.com/mcp",
      "headers": {
        "Authorization": "Bearer ${env:EXAMPLE_API_TOKEN}"
      }
    }
  }
}

Set EXAMPLE_API_TOKEN in your shell environment before starting Cursor. The token is then never written to the file.

If the server uses OAuth, you do not need headers. Cursor supports the OAuth authorization code flow with PKCE and reads protected resource metadata. With dynamic client registration, Cursor registers itself as a public client with no secret. Expired access tokens are renewed with a refresh token when the server issues one. Otherwise you sign in again.

Some providers need fixed credentials. For those, add an auth object with CLIENT_ID (required), CLIENT_SECRET (optional) and scopes (optional). These values can also use interpolation, for example ${env:MCP_CLIENT_ID}.

Add a local server with command

A local (stdio) server is a program Cursor starts on your machine. The fields are:

{
  "mcpServers": {
    "example-local": {
      "type": "stdio",
      "command": "npx",
      "args": ["-y", "example-mcp-server@1.2.3"],
      "env": {
        "EXAMPLE_API_KEY": "${env:EXAMPLE_API_KEY}"
      }
    }
  }
}

The example pins the package to a version, so a later release cannot change what runs on your machine without you noticing. See the MCP server security checklist for why that matters.

Variables you can use

Cursor resolves these in command, args, env, url and headers:

{
  "mcpServers": {
    "project-files": {
      "type": "stdio",
      "command": "node",
      "args": ["${workspaceFolder}/tools/mcp-server.js"]
    }
  }
}

Install from the marketplace instead

You do not have to edit JSON. The Cursor Marketplace has an "Add to Cursor" button on each entry. It installs the server and starts OAuth where the server needs it. Community servers are also listed on cursor.directory. Manual setup in mcp.json works for everything else, including servers you find in the list of MCP servers that work with Cursor.

Enable, disable and check a server

Open Customize in the sidebar, find the server and use its toggle. According to the Cursor docs, disabled servers do not load and do not appear in chat. Turn off servers you are not using. Fewer servers means fewer tools in the model's context and less to review.

When a server is connected, ask the agent to use one of its tools by name to confirm it works.

Troubleshooting

If you are new to the protocol, read what an MCP server is first. Using another editor? See the guides for VS Code and Claude Code.

Sources

FAQ

Where is the Cursor MCP config file?

Use .cursor/mcp.json in your project for project-specific servers, or ~/.cursor/mcp.json in your home directory for servers available in every project.

How do I add a remote MCP server to Cursor?

Add an entry to mcp.json with a url field, and an optional headers object for API keys. If the server uses OAuth, Cursor starts the sign-in flow when you connect.

Can I use environment variables in Cursor mcp.json?

Yes. Cursor resolves ${env:NAME} in command, args, env, url and headers. It also supports ${userHome} and ${workspaceFolder}.

How do I turn an MCP server off in Cursor?

Open Customize in the sidebar, find the server and use its toggle. Cursor's docs say disabled servers do not load or appear in chat.

More guides