Catalog My learning Blog
MCP Setup Guides: Cursor, Codex, Gemini CLI and Top Servers · Phase 1 · Lesson 1 · 4 min read

How to Add MCP Servers to Cursor (mcp.json)

On this page
  1. What you'll have at the end
  2. Step 1: pick the right config file
  3. Step 2: add a local (stdio) server
  4. Step 3: add a remote (HTTP) server
  5. Step 4: keep secrets out of the file
  6. Step 5: check it connected
  7. When it doesn't work
  8. Check yourself

What you'll have at the end

Cursor's agent can call tools from any MCP server you connect: open a pull request on GitHub, query your database, drive a browser. You'll have one local server and one remote server set up, a config file you can commit without leaking a token, and a way to read the logs when something breaks.

If you use Claude Code, VS Code or Claude Desktop, the matching guide is Using MCP servers in Claude Code, VS Code and Claude Desktop. The ideas are the same; only the file changes.

Step 1: pick the right config file

Cursor looks in two places:

FileApplies toCommit it?
.cursor/mcp.json in your projectThat project onlyYes, if it holds no secrets
~/.cursor/mcp.json in your home folderEvery project on your machineNo, it's personal

Use the project file for servers the whole team needs, such as the project's database or Sentry project. Use the global file for personal tools you want everywhere, such as Context7 or a browser server.

Step 2: add a local (stdio) server

A local server is a program Cursor starts on your machine and talks to over standard input and output. You give it a command and args. Create .cursor/mcp.json with Playwright's browser server:

JSON
{
  "mcpServers": {
    "playwright": {
      "command": "npx",
      "args": ["-y", "@playwright/mcp@0.0.84"]
    }
  }
}

The key under mcpServers ("playwright") is the name you'll see in Cursor. The -y flag stops npx from asking for confirmation, which it can't do when Cursor starts it in the background. The version is pinned on purpose: a server runs with your permissions, so you want to choose when it updates. 0.0.84 was current in November 2026.

Step 3: add a remote (HTTP) server

A remote server runs somewhere else and you reach it by URL. Add a url instead of a command:

JSON
{
  "mcpServers": {
    "playwright": {
      "command": "npx",
      "args": ["-y", "@playwright/mcp@0.0.84"]
    },
    "sentry": {
      "url": "https://mcp.sentry.dev/mcp"
    }
  }
}

Many hosted servers, including Sentry, Supabase and Figma, sign you in with OAuth. Cursor handles that for you: the first time the server is used, it opens a browser window to log in. There's no token to paste.

Step 4: keep secrets out of the file

Some servers want an API key in a header or environment variable. Don't paste the key into a file you commit. Cursor replaces ${env:NAME} with the value of an environment variable when it starts the server:

JSON
{
  "mcpServers": {
    "github": {
      "url": "https://api.githubcopilot.com/mcp/",
      "headers": { "Authorization": "Bearer ${env:GITHUB_PAT}" }
    }
  }
}

Each developer sets GITHUB_PAT in their own shell profile, and the file stays safe to share. Cursor resolves these variables in command, args, env, url and headers. It also understands ${workspaceFolder} (the folder that holds .cursor/mcp.json) and ${userHome}, which help when a server needs a path. Local servers can load a whole file of variables with "envFile": "${workspaceFolder}/.env".

TipCursor only sees environment variables that existed when it launched. If you add GITHUB_PAT to your shell profile, quit and reopen Cursor before testing.

Step 5: check it connected

Open Customize in Cursor's sidebar. Each server has a toggle and a status. A server that started shows its tools; one that failed shows an error. Turn off servers a project doesn't need: every connected server adds its tool descriptions to every request, which costs tokens and gives the agent more ways to pick the wrong tool.

Then ask the agent something only the server can answer, such as "Open example.com and tell me the page title." The agent should ask permission to call browser_navigate.

When it doesn't work

Open the Output panel (Cmd+Shift+U on macOS, Ctrl+Shift+U on Windows and Linux) and choose MCP Logs from the dropdown. Most failures are one of these:

  • spawn npx ENOENT: Cursor can't find npx. This is common when Node is installed with nvm, because apps opened from the Dock don't load your shell's PATH. Use the full path from which npx as the command.
  • The server starts, then drops: run the exact command from your config in a terminal. A missing environment variable or an old Node version usually shows up right away.
  • OAuth window never appears: toggle the server off and on in Customize, then use a tool again.

The troubleshooting guide at the end of this course covers these in more depth.

Check yourself

Put the server in the project's .cursor/mcp.json and reference the connection string with ${env:NAME}. Each developer sets that variable locally, so the committed file holds no secret.

Cursor didn't inherit your shell's PATH, so it can't find npx. Give the full path to npx in command, or start Cursor from a terminal.

Every enabled server sends its tool definitions with each request. That costs tokens and gives the agent more similar tools to choose between.