Checked against the official docs: Oct 20, 2026
MCP (Model Context Protocol) servers give Cursor's Agent extra tools, such as reading GitHub issues, driving a browser or looking up current library docs. There are two ways to add one: one click from Cursor's Customize panel, or a few lines in an mcp.json file. This guide covers both, with copy-paste configs and fixes for the errors people hit most.
~/.cursor/mcp.json (all your projects) or .cursor/mcp.json in your project folder (that project only).mcpServers key: a command for a local server, or a url for a remote one (examples below).
Prefer not to edit JSON? Use the one-click install first and come back to mcp.json for anything it doesn't list.
These entries come from the Cursor Marketplace. Cursor also points to cursor.directory for community plugins and MCP servers; community servers aren't reviewed by Cursor, so check who publishes them before installing.
Cursor merges both files. If the same server name appears in both, the project file wins.
A local server is a program Cursor starts on your machine. You give it a command and optional args and env. This adds Playwright MCP, which lets the Agent open and control a browser (it needs Node.js 18 or newer):
~/.cursor/mcp.json:
{
"mcpServers": {
"playwright": {
"command": "npx",
"args": ["@playwright/mcp@latest"]
}
}
}
The key (playwright here) is just a label you choose. The command has to be on your system PATH or be a full path to the program.
A remote server is hosted by the provider and reached over HTTP. Cursor supports Streamable HTTP and SSE endpoints with a url. This adds the Notion MCP server. After saving, enable it in Customize and complete Notion's OAuth sign-in to connect your workspace:
{
"mcpServers": {
"notion": {
"url": "https://mcp.notion.com/mcp"
}
}
}
Some servers take an API key or token in a header instead of OAuth. The GitHub MCP Server's Cursor guide uses a GitHub personal access token as a Bearer header. Rather than pasting the token into the file, read it from an environment variable with ${env:NAME}:
{
"mcpServers": {
"github": {
"url": "https://api.githubcopilot.com/mcp/",
"headers": {
"Authorization": "Bearer ${env:GITHUB_PAT}"
}
}
}
}
Set GITHUB_PAT in your shell profile (for example export GITHUB_PAT=... in ~/.zshrc), then restart Cursor so it picks up the variable. Give the token only the repositories and permissions you want the Agent to have.
Each server is one entry inside the same mcpServers object. Separate entries with a comma, and don't leave a comma after the last one:
{
"mcpServers": {
"playwright": {
"command": "npx",
"args": ["@playwright/mcp@latest"]
},
"notion": {
"url": "https://mcp.notion.com/mcp"
}
}
}
A project .cursor/mcp.json is meant to be committed, so never put real keys in it. Cursor resolves these variables in command, args, env, url and headers:
${env:NAME}: an environment variable.${userHome}: your home folder.${workspaceFolder}: the project root (the folder that contains ${workspaceFolderBasename}: the project folder's name.${pathSeparator} or ${/}: the OS path separator.
Local (stdio) servers can also load variables from a file with envFile, for example "envFile": "${workspaceFolder}/.env". Remote servers don't support envFile, so use ${env:NAME} for them. Keep .env in .gitignore.
{
"mcpServers": {
"my-local-server": {
"command": "npx",
"args": ["-y", "some-mcp-server"],
"envFile": "${workspaceFolder}/.env"
}
}
}
If you want to build your own MCP server, the (paid) Agent Builder Rules + Prompts pack has Cursor and Claude Code rules, 2 Claude Code skills, 10 scaffolding prompts for TypeScript or Python, and 12 eval prompt templates. You don't need it just to add servers.
mcp.json inside a .cursor folder, either in your home folder or in the project root.
Open the Output panel (Cmd+Shift+U on Mac, Ctrl+Shift+U on Windows/Linux) and pick MCP Logs from the dropdown. It shows connection errors, authentication problems and server crashes, which usually name the fix.
npx or uvx, so install Node.js (for which npx on macOS/Linux or where npx on Windows to get it).npx @playwright/mcp@latest). If it errors there, the message tells you what's missing. If it starts and waits silently, the server works and the problem is in the config.cmd /c: set "command": "cmd" and put "/c", "npx" at the start of args.
If the server relies on variables set in your shell profile, make sure Cursor can see them and restart Cursor after changing the profile. For local servers, putting the key in env or an envFile avoids the problem.
Authorization: Bearer <token>), that the token hasn't expired, and that it has the permissions the tool needs.
Servers that run with "command": "docker" (such as the local version of the GitHub MCP Server) need Docker Desktop installed and running before Cursor starts them.
Cursor's docs suggest removing the server in Customize, running npm cache clean --force, then adding it again.
Every server adds tools the Agent has to choose from. Switch off servers you're not using with their toggle in Customize → MCPs; disabled servers don't load or appear in chat, and you keep their config.
See every server we list in MCP Servers. Each page has setup steps checked against the official docs.
Use ~/.cursor/mcp.json for personal tools you want everywhere, and .cursor/mcp.json for tools a project's team should share. Keep keys out of the project file with ${env:NAME}.
stdio (a local command Cursor starts), SSE and Streamable HTTP (both by URL). If a provider offers both an SSE endpoint and a Streamable HTTP endpoint, use the one its docs recommend for Cursor.
Yes. Use the toggle next to it in Customize → MCPs.
Claude Code reads the same kind of mcpServers entries but stores them differently. See the best MCP servers for Claude Code for the claude mcp add commands.
Commands and config above come from these official docs. Tools change often, so check them for the latest steps.
PluginStack is independent and not affiliated with or endorsed by the companies mentioned. Spotted something out of date? Email pluginstackai@gmail.com.
This guide was first published on PluginStack. Browse the PluginStack directory for more hand-checked MCP servers, plugins and setup guides.