Adding an MCP server to Cursor

Where Cursor stores MCP config

Cursor reads MCP servers from a JSON file using the `mcpServers` key (not `servers`). There are two scopes:

Project scope: `.cursor/mcp.json` in your repository root. The server is available only when that project is open, and you can commit it to share the setup with your team.

Global scope: `~/.cursor/mcp.json` in your home directory (`%USERPROFILE%\.cursor\mcp.json` on Windows). The server is available in every project.

If the same server name appears in both files, the project-level definition wins. You can open the right file straight from the editor: Settings - Tools & Integrations - MCP Tools - New MCP Server.

Add a local (stdio) server

Local servers run as a child process on your machine over the stdio transport. Cursor launches the `command` with the given `args`, and passes secrets via `env`. Create `.cursor/mcp.json` with:

{ "mcpServers": { "my-server": { "command": "<command>", "args": ["<arg>"], "env": { "API_KEY": "<your-key>" } } } }

Replace `<command>` with the executable (for example a launcher like `uvx` or `npx`, or an absolute path to a binary), and `<arg>` with the package or script it runs. Keep real secrets in `env`; never hardcode them in `args`. Use an absolute path for `command` if the binary is not on your PATH.

Add a remote (HTTP) server

Remote servers are reached over the network using Streamable HTTP, so you supply a `url` instead of a `command`. Auth headers (such as a bearer token) go in `headers`:

{ "mcpServers": { "my-remote": { "url": "<url>", "headers": { "Authorization": "Bearer <token>" } } } }

Many hosted servers use OAuth instead of a static token; in that case you can install from a marketplace entry or cursor.directory with an Add to Cursor button and authenticate in the browser. After editing the file, fully quit and reopen Cursor so it reloads MCP servers, then confirm the server and its tools appear under Settings - Tools & Integrations.

Vet the server before you add it

Adding an MCP server grants it real power: Cursor will call the server's tools, and a local server runs on your machine with your environment and credentials. A malicious or compromised server can attempt tool poisoning (hidden instructions in a tool description), exfiltrate secrets, or run command injection. Treat adding a server like installing a dependency you do not fully control.

Before adding one: prefer official or first-party servers, pin to a specific version rather than a floating `latest`, read the tool descriptions and schemas, scope credentials to least privilege (a read-only or short-lived token), and watch out for the lethal trifecta - a server that combines access to private data, exposure to untrusted content, and the ability to communicate externally.

Re-vet on updates, too. A server that was safe yesterday can change behavior in a new version (an MCP rug pull), so review changes before bumping the pinned version.

Verify and manage from the CLI

The Cursor CLI (the `cursor-agent` binary) shares the same `mcp.json` configuration as the editor and follows the same project-then-global precedence. There is no `cursor mcp add` command - you add servers by editing the JSON - but you can manage them once configured:

`cursor-agent mcp list` - show configured servers and their status.

`cursor-agent mcp list-tools <identifier>` - list the tools a server exposes (a quick way to inspect what it can do).

`cursor-agent mcp login <identifier>` - authenticate with a server that uses OAuth.

`cursor-agent mcp enable <identifier>` / `disable <identifier>` - turn a server on or off. In interactive mode the same actions are available as `/mcp list` and `/mcp list-tools`.

Adding an MCP server to Cursor — FAQ

Related