How to Add an MCP Server to Cursor

Cursor reads MCP servers from a file called mcp.json. Put a server there, globally or per project, and Cursor's agent can use its tools. The format is short: a URL for a hosted server, or a command for a local one. This guide covers both, how sign-in and secrets work, and how to switch servers on and off.

Every server in our MCP server directory with verified connection details has a ready-made Cursor snippet on its page.

Where the config lives

If the same server is defined in both, the project file wins. Use the global file for personal tools (search, docs, your issue tracker) and the project file for servers a codebase depends on.

The quickest route of all is the Cursor Marketplace or cursor.directory: click Add to Cursor on a listing and Cursor writes the config and starts the sign-in for you. Everything below is what that button does, so you can do it for any server.

Add a hosted server

A hosted server runs on the vendor's side, so all Cursor needs is the URL:

{
  "mcpServers": {
    "linear": {
      "url": "https://mcp.linear.app/mcp"
    }
  }
}

If the server uses OAuth, Cursor opens the vendor's sign-in page the first time it connects. You approve access in the browser and you're done.

If the server takes an API key instead, send it as a header:

{
  "mcpServers": {
    "context7": {
      "url": "https://mcp.context7.com/mcp",
      "headers": {
        "Authorization": "Bearer ${env:CONTEXT7_API_KEY}"
      }
    }
  }
}

${env:NAME} reads the value from an environment variable, so the key never sits in the file. That matters most in a project's .cursor/mcp.json, which usually ends up in version control.

Add a local server

A local server is a program Cursor starts on your machine. Give it the command, the arguments and any environment variables:

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

You need the runtime the server uses (Node.js for npx, uv for uvx, Docker for docker) installed on your machine. The server's page in the directory tells you which.

Local servers can also load their variables from a file with "envFile": ".env". That option only works for local servers, not hosted ones.

Useful variables

Cursor fills these in when it reads mcp.json, which keeps one config working across machines:

A filesystem server scoped to the current project, for example, can use ${workspaceFolder} as its allowed folder.

Turn servers on and off

Open Customize in the sidebar to see every configured server, its tools and its status. Use the toggle to switch a server off without deleting its config. It's worth doing: every enabled server adds its tools to what the agent has to choose from, and a long tool list makes it slower to pick the right one.

How the agent uses them

MCP tools are available to Cursor's agent, which picks a tool when your request needs it. By default Cursor asks for approval before running an MCP tool. If you use auto-run, keep it to tools you trust, and be careful with anything that can write, send or delete.

Common problems

The server shows as errored. For a local server, run the same command in a terminal and read the error. It's usually a missing runtime or environment variable. For a hosted server, check the URL against the server's page. Many endpoints end in /mcp, and a missing path gives a 404.

OAuth doesn't complete. Some servers don't support dynamic client registration. For those, add an auth object with the CLIENT_ID (and CLIENT_SECRET if needed) from an OAuth app you create with the vendor. Cursor's redirect URL for the desktop app is http://localhost:8787/callback.

Tools don't appear. Check the server is toggled on in Customize, then reload the window.

Next steps

Browse the MCP server directory for servers by category. Each page says who maintains it, whether it's hosted or local, and how it authenticates. If you're new to MCP, our guide to how MCP clients and servers fit together is a good primer. Using more than one AI tool? We have the same walkthrough for Claude Code, Claude Desktop and VS Code.