Add MCP servers to Cursor

Cursor reads MCP servers from an mcp.json file, either for your whole machine or for one project. This guide shows both remote and local entries using real registry examples, explains how Cursor handles OAuth and secrets, and covers tool approval.

Where the configuration lives

  • ~/.cursor/mcp.json in your home folder holds servers available in every project.
  • .cursor/mcp.json inside a project holds servers for that project only, and can be committed so a team shares them.

Both files use a top-level mcpServers object. Each key is a server name and each value describes how to reach it. When you add a server, merge it into the existing object rather than replacing the file, or you will lose the servers already configured. Cursor also offers one-click installs from its marketplace in the Customize view; the file-based setup below works for any server.

Add a remote server

A remote server needs only a url. Cursor supports Streamable HTTP and SSE endpoints and supports OAuth for servers that require it, so a vendor-hosted server usually looks like this:

Supabase for Cursor. Merge into ~/.cursor/mcp.json
{
  "mcpServers": {
    "supabase": {
      "url": "https://mcp.supabase.com/mcp"
    }
  }
}

After saving the file, open Cursor's MCP settings, find the server and connect. For an OAuth server Cursor opens the provider's sign-in page; you approve access there and Cursor stores the token. Supabase's own documentation also recommends adding project_ref and read_only=true to the URL to limit what the agent can reach; see the Supabase listing for details.

Some providers do not support OAuth dynamic client registration. For those, Cursor accepts static OAuth client credentials in an auth object with CLIENT_ID, an optional CLIENT_SECRET and optional scopes; the provider's documentation tells you whether you need this.

Add a local server

A local server uses command and args, plus an env object for anything the server reads from its environment. The registry marks values you must supply with REPLACE_WITH_...:

Brave Search MCP Server for Cursor. Merge into ~/.cursor/mcp.json
{
  "mcpServers": {
    "brave-search-official": {
      "command": "npx",
      "args": [
        "-y",
        "@brave/brave-search-mcp-server"
      ],
      "env": {
        "BRAVE_API_KEY": "REPLACE_WITH_BRAVE_API_KEY"
      }
    }
  }
}

Cursor starts the process itself, so the command must be on your path; install Node.js for npx servers or uv for uvx servers. For servers that need several settings, the envFile option loads them from a file such as .env. It works for local servers only.

Keep secrets out of the file

Pasting an API key into mcp.json works, but it puts the key in a plain-text file that is easy to commit or share by accident. Cursor resolves variables in the command, args, env, url and headers fields, so you can refer to environment variables instead:

{
  "mcpServers": {
    "brave-search-official": {
      "command": "npx",
      "args": ["-y", "@brave/brave-search-mcp-server"],
      "env": {
        "BRAVE_API_KEY": "${env:BRAVE_API_KEY}"
      }
    }
  }
}

Other supported variables include ${userHome}, ${workspaceFolder} (the folder that contains .cursor/mcp.json) and ${workspaceFolderBasename}. A project file that only contains ${env:...} references is safe to commit, because each person supplies their own values.

Tool approval and run modes

By default Cursor asks before it runs an MCP tool, and you can expand the prompt to see the exact arguments the agent wants to send. Read them, especially for tools that write: creating issues, running SQL or sending messages. MCP tools follow the same run modes as terminal commands, so if you switch to a mode that runs tools automatically, an allow list decides which tools skip the prompt.

On team and enterprise plans, admins can distribute shared servers and define an MCP allowlist that approves local servers by command pattern, remote servers by URL pattern, and individual tools. If a server you configured does not appear, ask whether such a policy applies.

If a server does not connect

  1. Check the file is valid JSON. A trailing comma or a missing brace stops every server in the file from loading.
  2. For a local server, run the command from the snippet in a terminal. Missing runtimes and wrong package names show up immediately.
  3. For a remote server, confirm the URL ends in the path the provider documents, often /mcp, and that you completed the sign-in.
  4. Open the server in Cursor's MCP settings to see its status and the tools it reported. If no tools are listed, the server started but returned nothing usable.

Servers to try

These current remote servers sign you in with OAuth, so you can add them without handling any key:

Every registry listing has a Cursor example. Before granting an agent write access, read authentication and security basics.

Sources

This guide was written from the official documentation below and last reviewed on 12 October 2026. Client interfaces change often; when a menu or file name here differs from what you see, the upstream documentation wins. Report a correction through the contact page.