How to Add MCP Servers to Cursor (mcp.json)
On this page
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:
| File | Applies to | Commit it? |
|---|---|---|
.cursor/mcp.json in your project | That project only | Yes, if it holds no secrets |
~/.cursor/mcp.json in your home folder | Every project on your machine | No, 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:
{
"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:
{
"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:
{
"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".
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 findnpx. 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 fromwhich npxas thecommand.- 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.