How to add an MCP server to Cursor (mcp.json, examples & fixes) A developer guide details how to add Model Context Protocol (MCP) servers to Cursor's Agent, either through the Customize panel's one-click install or by editing an mcp.json file at the user level (~/.cursor/mcp.json) or project level (.cursor/mcp.json). The guide covers local stdio servers configured with a command and args, remote servers reached via Streamable HTTP or SSE URLs, Bearer-token auth through ${env:NAME} variables, and variable substitution including ${workspaceFolder} and envFile for local servers. It also notes that project files override user files when server names collide and warns against committing real keys to a project mcp.json. 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 https://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 https://www.pluginstackai.com/plugins/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 https://www.pluginstackai.com/plugins/notion-mcp/ . 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 https://www.pluginstackai.com/plugins/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 https://www.pluginstackai.com/packs/ 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