How to set up MCP servers in Cursor

Cursor reads MCP servers from a JSON file called mcp.json, either in your home directory or in your project. This guide shows where those files live, how to add local and remote servers, how to keep secrets out of them, how one-click install links work, and what to check when a server doesn't show up.

Where Cursor keeps MCP config

Cursor looks in two places:

• Global: ~/.cursor/mcp.json (on Windows, %USERPROFILE%\.cursor\mcp.json). Servers here are available in every project.
• Project: .cursor/mcp.json in the project root. Servers here are available only in that project, and the file can be committed so your whole team gets the same setup.

Use the global file for personal tools you want everywhere, such as documentation lookup or web search. Use the project file for tools tied to the codebase, such as its database, issue tracker or error monitoring. Both files use the same format, with servers under a top-level mcpServers key.

Add a local server

A local server is a command that Cursor starts and talks to over stdio. Give it a name, a command, its args, and any environment variables in env:

{
  "mcpServers": {
    "playwright": {
      "type": "stdio",
      "command": "npx",
      "args": ["-y", "@playwright/mcp@latest"]
    },
    "my-api": {
      "type": "stdio",
      "command": "npx",
      "args": ["-y", "my-api-mcp-server@1.2.3"],
      "env": { "MY_API_KEY": "${env:MY_API_KEY}" }
    }
  }
}

Stdio servers can also load variables from a file with envFile, for example "envFile": "${workspaceFolder}/.env". Make sure that file is in .gitignore.

Pin versions for anything you haven't reviewed closely. @latest is convenient for a well-known vendor package, but it also means the code can change every time Cursor starts the server.

Add a remote server

A remote server is a URL. Add headers if the server expects a token:

{
  "mcpServers": {
    "linear": {
      "url": "https://mcp.linear.app/mcp"
    },
    "internal-api": {
      "url": "https://mcp.example.com/mcp",
      "headers": { "Authorization": "Bearer ${env:INTERNAL_API_TOKEN}" }
    }
  }
}

Cursor supports Streamable HTTP, and still accepts SSE for older servers. Many remote servers use OAuth. Cursor handles the sign-in in your browser, so there is no key to paste. For servers that need pre-registered OAuth credentials, Cursor accepts an auth object with a CLIENT_ID, an optional CLIENT_SECRET and optional scopes.

Not sure which kind a server is? The local vs remote guide explains the difference, and the remote servers list shows every listing you can add with just a URL.

Use variables, not secrets

Cursor resolves variables in command, args, env, url and headers:

• ${env:NAME} reads an environment variable.
• ${userHome} is your home directory.
• ${workspaceFolder} is the folder that contains .cursor/mcp.json, and ${workspaceFolderBasename} is its name.
• ${pathSeparator} (or ${/}) is the path separator for the current OS.

This is what makes a shared project file safe to commit. Write "${env:STRIPE_API_KEY}" instead of the key, and each developer keeps the real value in their own environment. Remember that Cursor reads the environment it was launched with. If you start it from the Dock or Start menu, variables set only in your shell profile may not reach it.

One-click install links

Cursor supports install deeplinks in this format:

cursor://anysphere.cursor-deeplink/mcp/install?name=NAME&config=BASE64_CONFIG

config is the server's JSON entry, the part you would put under its name in mcp.json, serialized with JSON.stringify and then base64-encoded. You can build one yourself:

node -e 'const c={command:"npx",args:["-y","some-mcp-server@1.2.3"]}; console.log("cursor://anysphere.cursor-deeplink/mcp/install?name=example&config="+encodeURIComponent(Buffer.from(JSON.stringify(c)).toString("base64")))'

Every MCPpedia server page with an installable config shows an Add to Cursor link in its Install section. The link contains only the public config shown on the page, never your secrets. Whatever the source, check the command Cursor shows before you confirm. A one-click link runs a program on your machine just like a manual entry does. The security best practices guide covers what to check.

Turn servers and tools on and off

You can switch each server on or off in Cursor's settings without deleting its entry. In current versions this is the toggle beside the server in the Customize panel. A disabled server doesn't load and doesn't appear in chat.

Keep only the servers you need switched on. Every enabled server adds tool definitions to the model's context, and a long list of similar tools makes it harder for the model to pick the right one.

Cursor asks for your approval before it runs an MCP tool, and you can expand a call to see its arguments first. MCP tools follow the same run modes as terminal commands. If you allowlist a tool, it runs without asking. Allowlist read-only tools if you like, and keep tools that write, send or delete on manual approval.

Troubleshooting

Start with the logs. 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 explain themselves there.

• The server doesn't appear. Check the file name and location (.cursor/mcp.json, not .cursor/mcp.jsonc or .vscode/mcp.json), the top-level key (mcpServers), and that the JSON is valid, with no trailing commas. Then check that the server is switched on.
• spawn npx ENOENT or "command not found". Cursor can't find the command on its PATH. Use the absolute path from which npx (or where npx on Windows), or launch Cursor from a terminal so it inherits your shell's PATH.
• It connects but shows no tools, or tool calls fail with auth errors. A required environment variable is probably missing or empty. Check the env block and how Cursor was launched.
• A remote server returns 401 or keeps asking you to sign in. Complete the OAuth flow again, or check the header token. A 404 usually means the URL path is wrong, and many servers use /mcp.
• It works in the terminal but not in Cursor. Compare the exact command, arguments and environment. Relative paths are a common culprit, so use absolute ones.

The troubleshooting guide goes deeper on each of these.

Find servers for Cursor

The Cursor client page lists servers you can install in Cursor with ready-made configs. Popular starting points are browser automation for testing web apps, documentation lookup for current library docs, and GitHub issues and pull requests.