How MCP works inside Cursor: where the config lives, the three transports, the JSON shape for local and remote servers, static OAuth credentials and the enterprise controls, read from the Cursor documentation on 2 September 2026.
Interactive examples · No account is connected on this page
Updated
Cursor MCP is Cursor's support for the Model Context Protocol. You install servers from the Cursor Marketplace or configure them in mcp.json, either per project at .cursor/mcp.json or globally at ~/.cursor/mcp.json. Cursor supports three transports — stdio, SSE and Streamable HTTP — and supports tools, prompts, resources, roots, elicitation and the MCP Apps extension for interactive UI.
Pick an example to see which Cursor MCP tools a task would call and what the result looks like. Examples are illustrative; nothing on this page connects to Cursor.
Cursor reads MCP servers from mcp.json: .cursor/mcp.json in the project root for one project, or ~/.cursor/mcp.json for every project. A local server is a command Cursor starts; a remote server is a URL plus optional headers or an auth object. Secrets belong in config interpolation such as ${env:NAME}, and tool calls ask for approval by default.
Two locations, and the choice is about scope rather than syntax. A .cursor/mcp.json in the project root gives that project its own tools, which is what you commit for a team. A ~/.cursor/mcp.json in your home directory makes a server available everywhere. Team admins have a third route and can distribute servers through a team marketplace, where they appear in Customize alongside personal and workspace servers.
.cursor/mcp.json # this project
~/.cursor/mcp.json # every projectA stdio server is a command Cursor starts and manages for you. command is required and must be on your system path or given in full; args and env are optional. envFile is stdio-only — remote servers cannot use it, and the docs point those at config interpolation instead.
{
"mcpServers": {
"server-name": {
"command": "npx",
"args": ["-y", "mcp-server"],
"env": {
"API_KEY": "value"
}
}
}
}A remote server is a url plus optional headers. Cursor supports both SSE and Streamable HTTP for remote endpoints, and both are multi-user: the server is deployed once and several people point at it, with OAuth rather than a manually pasted key.
{
"mcpServers": {
"server-name": {
"url": "http://localhost:3000/mcp",
"headers": {
"API_KEY": "value"
}
}
}
}Some providers hand you a fixed client ID, require a whitelisted redirect URL, or do not support OAuth 2.0 Dynamic Client Registration at all — Cursor's docs name Figma and Linear as redirect-whitelisting examples. For those, add an auth object to the remote entry. Omit scopes and Cursor discovers them from the server's /.well-known/oauth-authorization-server metadata.
{
"mcpServers": {
"oauth-server": {
"url": "https://api.example.com/mcp",
"auth": {
"CLIENT_ID": "your-oauth-client-id",
"CLIENT_SECRET": "your-client-secret",
"scopes": ["read", "write"]
}
}
}
}Cursor uses fixed OAuth redirect URLs, and they differ by surface: web and Cursor Agents come back to the cursor.com callback, while the desktop app comes back to localhost. If your users authenticate from both, register both as allowed redirect URIs. The docs note the server is identified through the OAuth state parameter, so these two URLs serve every MCP server.
https://www.cursor.com/agents/mcp/oauth/callback
http://localhost:8787/callbackCursor resolves variables in command, args, env, url and headers. ${env:NAME} pulls from the environment, and ${workspaceFolder}, ${userHome}, ${workspaceFolderBasename}, ${pathSeparator} and ${/} cover paths. This is the documented way to keep a client ID or a bearer token out of a file you commit.
{
"mcpServers": {
"remote-server": {
"url": "https://api.example.com/mcp",
"headers": {
"Authorization": "Bearer ${env:MY_SERVICE_TOKEN}"
}
}
}
}Servers are toggled on and off from Customize in the sidebar, and Cursor picks up MCP tools listed under Available Tools when they are relevant, including in Plan Mode. Tool calls ask for approval by default, and MCP follows the same Run Modes as terminal commands — in Auto-review, allowlisted tools run immediately and everything else goes through the classifier.
Customize → find the MCP server → toggle onOfficial documentation: Read the Cursor MCP docs.
Cursor supports three MCP transports, and the choice decides who runs the server and how it authenticates. stdio is a local command Cursor manages for a single user, authenticated through environment variables. SSE and Streamable HTTP are deployed servers that several people can share, authenticated with OAuth, and neither supports envFile, so secrets go through interpolation instead.
| What differs | stdio | SSE | Streamable HTTP |
|---|---|---|---|
| Execution environment | Local | Local or remote | Local or remote |
| Deployment | Cursor manages the process | Deploy as a server | Deploy as a server |
| Users | Single user | Multiple users | Multiple users |
| What you configure | A shell command | A URL to an SSE endpoint | A URL to an HTTP endpoint |
| Authentication | Manual, via env | OAuth | OAuth |
| envFile support | Yes | No; use config interpolation | No; use config interpolation |
Transport table, config shapes and redirect URLs transcribed from the Cursor MCP documentation at cursor.com/docs/mcp, read 2026-09-02.
Cursor supports more of the protocol than tool calls. The docs list prompts, resources, roots and elicitation, the MCP Apps extension for tools that return interactive UI, and images returned as context. Around that sit marketplace installs, a split between team distribution and enterprise allowlists, and per-server network modes for local command-based servers.
Cursor lists tools, prompts, resources, roots and elicitation as supported. Roots let a server ask about URI or filesystem boundaries; elicitation lets a server ask the user for more information mid-call. A server that uses those is not limited to a single-shot function call.
Cursor supports the MCP Apps extension, so a tool can return an interactive view alongside its normal output. It follows progressive enhancement — a host that cannot render app UI still gets the same tool working through ordinary MCP responses.
A server can return screenshots or diagrams as base64-encoded strings with an image content type. Cursor attaches them to the chat, and if the model supports images it analyses them.
The Cursor Marketplace carries official plugins with one-click install from Customize, and cursor.directory collects community plugins and servers. Add to Cursor installs the entry and runs the OAuth flow.
The docs draw a line most teams blur. Team admins distribute shared servers under Dashboard, Integrations and MCP. Enterprise admins separately set policy in Team Settings, MCP Configuration: command entries approve local stdio servers by command pattern, URL entries approve remote ones by URL pattern, and per-server tool allowlists restrict which tools run automatically. Allowlisting approves a configuration; it does not install anything.
Local command-based servers each carry a network mode: allow all, allowlist only, deny all outbound, or no sandbox. Remote MCP URLs are restricted to the configured URL entry pattern, and a User MCP Network Denylist can block destinations for servers users add themselves.
Cursor MCP is Cursor’s client-side support for the Model Context Protocol. Cursor is the host: it loads servers from mcp.json or the Cursor Marketplace and lets the agent call their tools, prompts and resources while you work.
Cursor connects over stdio for local commands, and over SSE or Streamable HTTP for servers you deploy. Beyond tools it supports roots, elicitation and the MCP Apps extension, so a server can ask follow-up questions or return interactive UI.
Cursor is the client, so these guides cover the servers most often wired into it. Each page gives the config entry for mcp.json, the transport the server uses, how it signs in, and the tools it adds, so you can register one in Cursor and check it lists its tools before adding another.
GitHub MCP ServerCursor needs a personal access token for this one.Playwright MCP ServerBrowser automation through accessibility snapshots.
Notion MCP ServerA url entry plus OAuth from Customize.
Slack MCP ServerOne of four clients Slack supports today.Zapier MCP ServerInstalled as a marketplace plugin rather than by hand.
Claude MCPThe same servers, configured for Claude clients.n8n MCP Servern8n workflows exposed as MCP tools..cursor/mcp.json for one project, ~/.cursor/mcp.json for all of them, or one-click install from the Marketplace.
A command for stdio, a URL for SSE or Streamable HTTP, plus static OAuth details if the provider requires them.
Toggle it on in Customize and check which tool calls Cursor asks you to approve.
Add a remote server such as GitHub MCP to .cursor/mcp.json so the agent can read issues and pull requests before it edits code. See the GitHub MCP guide.
Add Playwright MCP as a local stdio server so the agent can open and inspect pages through accessibility snapshots. See Playwright MCP.
Admins distribute shared servers from the dashboard, while Enterprise allowlists approve commands and URLs separately and restrict which tools run automatically.
These answers cover the practical questions that come up after the first server works: where mcp.json lives, how to disable a server temporarily, where Cursor writes MCP logs, how to update an npm-based server, how to keep API keys out of a committed config, and whether Cursor asks before it runs an MCP tool.
Two places. .cursor/mcp.json in the project root configures servers for that project only. ~/.cursor/mcp.json in your home directory configures servers available in every project. Both use the same mcpServers object, so a config can be moved between them unchanged.
Open Customize in the sidebar, find the server and use the toggle. Disabled servers do not load and do not appear in chat, which the docs suggest as a way to troubleshoot or to cut down tool clutter. You do not have to remove the entry from mcp.json.
Open the Output panel with Cmd+Shift+U and select MCP Logs from the dropdown. The logs cover server initialisation, tool calls and error messages, which is where connection errors, authentication failures and crashes show up. If a server does crash, Cursor marks the tool call failed and isolates it, so other servers keep working.
The documented sequence is to remove the server from Customize, clear the npm cache with npm cache clean --force, then re-add it so the latest version is fetched. For a custom server you wrote, update the local files and restart Cursor.
Yes, using config interpolation. Cursor resolves variables in command, args, env, url and headers, so "Authorization": "Bearer ${env:MY_SERVICE_TOKEN}" reads from the environment instead of storing the token. The same works for static OAuth credentials via ${env:MCP_CLIENT_ID}. Note that envFile is stdio-only — remote servers have to use interpolation with variables set in your shell profile or system environment.
By default, yes: Cursor prompts for approval and you can expand the arrow next to the tool name to inspect the arguments. Beyond that, MCP follows the same Run Modes as terminal commands — in Auto-review, allowlisted tools run immediately and everything else is routed through the classifier. Enterprise tool allowlists narrow this further per server.
The same servers you wire into Cursor have to run somewhere unattended eventually: on a schedule, on a webhook, with no one to approve each tool call. Moving from an editor session to a job that runs on its own means deciding triggers, retries and which steps still need a human to review them.