{"slug": "how-to-add-an-mcp-server-to-cursor-mcp-json-examples-fixes", "title": "How to add an MCP server to Cursor (mcp.json, examples & fixes)", "summary": "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.", "body_md": "Checked against the official docs: Oct 20, 2026\n\nMCP (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.\n\n`~/.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).\nPrefer not to edit JSON? Use the one-click install first and come back to `mcp.json` for anything it doesn't list.\n\nThese 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.\n\nCursor merges both files. If the same server name appears in both, the project file wins.\n\nA 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):\n\n`~/.cursor/mcp.json`:\n\n```\n{\n  \"mcpServers\": {\n    \"playwright\": {\n      \"command\": \"npx\",\n      \"args\": [\"@playwright/mcp@latest\"]\n    }\n  }\n}\n```\n\nThe 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.\n\nA 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:\n\n```\n{\n  \"mcpServers\": {\n    \"notion\": {\n      \"url\": \"https://mcp.notion.com/mcp\"\n    }\n  }\n}\n```\n\nSome 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}`:\n\n```\n{\n  \"mcpServers\": {\n    \"github\": {\n      \"url\": \"https://api.githubcopilot.com/mcp/\",\n      \"headers\": {\n        \"Authorization\": \"Bearer ${env:GITHUB_PAT}\"\n      }\n    }\n  }\n}\n```\n\nSet `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.\n\nEach server is one entry inside the same `mcpServers` object. Separate entries with a comma, and don't leave a comma after the last one:\n\n```\n{\n  \"mcpServers\": {\n    \"playwright\": {\n      \"command\": \"npx\",\n      \"args\": [\"@playwright/mcp@latest\"]\n    },\n    \"notion\": {\n      \"url\": \"https://mcp.notion.com/mcp\"\n    }\n  }\n}\n```\n\nA 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`:\n\n`${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.\nLocal (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`.\n\n```\n{\n  \"mcpServers\": {\n    \"my-local-server\": {\n      \"command\": \"npx\",\n      \"args\": [\"-y\", \"some-mcp-server\"],\n      \"envFile\": \"${workspaceFolder}/.env\"\n    }\n  }\n}\n```\n\nIf 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.\n\n`mcp.json` inside a `.cursor` folder, either in your home folder or in the project root.\nOpen 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.\n\n`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`.\nIf 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.\n\n`Authorization: Bearer <token>`), that the token hasn't expired, and that it has the permissions the tool needs.\nServers 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.\n\nCursor's docs suggest removing the server in Customize, running `npm cache clean --force`, then adding it again.\n\nEvery 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.\n\nSee every server we list in [MCP Servers](https://www.pluginstackai.com/categories/mcp-servers/). Each page has setup steps checked against the official docs.\n\nUse `~/.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}`.\n\nstdio (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.\n\nYes. Use the toggle next to it in **Customize → MCPs**.\n\nClaude Code reads the same kind of `mcpServers` entries but stores them differently. See [the best MCP servers for Claude Code](https://www.pluginstackai.com/guides/best-mcp-servers-for-claude-code/) for the `claude mcp add` commands.\n\nCommands and config above come from these official docs. Tools change often, so check them for the latest steps.\n\nPluginStack is independent and not affiliated with or endorsed by the companies mentioned. Spotted something out of date? Email [pluginstackai@gmail.com](mailto:pluginstackai@gmail.com).\n\nThis guide was first published on [PluginStack](https://www.pluginstackai.com/guides/add-mcp-server-to-cursor/). Browse the [PluginStack directory](https://www.pluginstackai.com/) for more hand-checked MCP servers, plugins and setup guides.", "url": "https://wpnews.pro/news/how-to-add-an-mcp-server-to-cursor-mcp-json-examples-fixes", "canonical_source": "https://dev.to/pluginstackai/how-to-add-an-mcp-server-to-cursor-mcpjson-examples-published-true-kcm", "published_at": "2026-11-13 22:18:38+00:00", "updated_at": "2026-11-13 22:21:12.207117+00:00", "lang": "en", "topics": ["ai-agents", "agent-protocols", "ai-tools", "developer-tools"], "entities": ["Cursor", "Model Context Protocol", "Playwright MCP", "Notion MCP", "GitHub MCP Server", "cursor.directory"], "also_reported_by": [], "alternates": {"html": "https://wpnews.pro/news/how-to-add-an-mcp-server-to-cursor-mcp-json-examples-fixes", "markdown": "https://wpnews.pro/news/how-to-add-an-mcp-server-to-cursor-mcp-json-examples-fixes.md", "text": "https://wpnews.pro/news/how-to-add-an-mcp-server-to-cursor-mcp-json-examples-fixes.txt", "jsonld": "https://wpnews.pro/news/how-to-add-an-mcp-server-to-cursor-mcp-json-examples-fixes.jsonld"}}