Guides7 min read

Cursor MCP: How to Add an MCP Server to Cursor (Local and Remote, 2026)

Cursor MCP setup in plain steps: add local or remote MCP servers with mcp.json or Customize, sign in with OAuth, approve tool calls and fix silent failures.

By The Unorderly teamPublished

Cursor MCP is how you connect Cursor's agent to tools outside your codebase: databases, design files, issue trackers, or an app on your phone. You add a server in one of two ways: install it from Customize, or list it in an mcp.json file. Local servers run as a command on your machine. Remote servers sit at a URL and usually sign you in with OAuth.

Quick answer

To add an MCP server to Cursor, open Customize in the sidebar and install it from the Marketplace, or create .cursor/mcp.json in your project (or ~/.cursor/mcp.json for every project). Give a local server a command and args, or give a remote server a url. Sign in when Cursor asks, check the server is switched on, and approve its first tool call (Cursor docs).

What is MCP in Cursor?

The Model Context Protocol is an open standard for connecting AI applications to external systems. The MCP docs compare it to a USB-C port for AI apps: one standard plug instead of a custom integration for every tool. Anthropic introduced it in November 2024, and Cursor is one of the clients that supports it.

In Cursor, an MCP server hands the agent a list of tools it can call. Cursor's docs put the benefit plainly: instead of explaining your project structure over and over, you connect the agent directly to your tools. Cursor supports MCP tools, prompts, resources, roots, elicitation and the MCP Apps extension, so a server can even return small interactive views alongside its normal output.

If the local vs remote distinction is new to you, our guide to what a remote MCP server is covers it in plain English.

Local vs remote MCP servers in Cursor

Cursor supports three ways to talk to a server. Which one you use depends on where the server runs.

Transport Where it runs What you put in mcp.json How it signs in Good for
stdio On your machine; Cursor starts it command, args, optional env / envFile Manual (keys in environment variables) Dev tools, local files, anything that shouldn't leave your laptop
SSE Local or remote server url OAuth Older remote servers
Streamable HTTP Local or remote server url OAuth Most hosted servers today

The MCP specification defines stdio and Streamable HTTP as its two standard transports. Streamable HTTP replaced the older HTTP+SSE transport, which is why Cursor still supports SSE for older servers.

Step-by-step: how to add an MCP server to Cursor

  1. Check the Marketplace first. Open Customize in Cursor's sidebar and browse the Cursor Marketplace. For official plugins, click Add to Cursor and sign in with OAuth when asked. Cursor's docs point to cursor.directory for community servers.
  2. Or create an mcp.json file. For one project, create .cursor/mcp.json in the project root. For every project, create ~/.cursor/mcp.json in your home folder. Both use the same mcpServers format.
  3. Add a local (stdio) server. Give it a name, the command that starts it and its arguments, for example "command": "npx", "args": ["-y", "mcp-server"]. Put secrets in env using interpolation such as ${env:API_KEY}, not as plain text.
  4. Or add a remote server by URL. A remote entry only needs "url": "https://…/mcp". If the provider uses OAuth, that's enough: Cursor reads the server's protected resource metadata (RFC 9728), finds its sign-in server and registers itself. If the provider gives you a fixed client ID, add an auth object with CLIENT_ID (and CLIENT_SECRET if needed).
  5. Sign in. The first time Cursor connects to an OAuth server, a browser sign-in opens. Cursor uses the authorization code flow with PKCE, and renews the token with a refresh token when the server issues one. From the CLI, run agent mcp login <name>.
  6. Switch it on and check the tools. In Customize, make sure the server's toggle is on. In the CLI, agent mcp list shows each server's status and agent mcp list-tools <name> shows what it offers (Cursor CLI docs).
  7. Ask for something that needs the tool. Cursor's agent uses MCP tools when they're relevant, including in Plan Mode. You can also name the tool you want. Read the approval prompt before you click run.

A remote server example: Unorderly

Here's what a remote entry looks like with a real OAuth server. Unorderly shows its MCP link on its homepage as api.unorderly.app/mcp:

{
  "mcpServers": {
    "unorderly": {
      "url": "https://api.unorderly.app/mcp"
    }
  }
}

Save the file, let Cursor open the sign-in page, and log in with your Unorderly account. No API key goes into the file. The same pattern works for any hosted MCP server that supports OAuth sign-in. If you also use Claude, the steps there are in how to add a custom connector in Claude.

Approving MCP tool calls in Cursor

Cursor asks for approval before it uses an MCP tool by default. Click the arrow next to the tool name to see the exact arguments the agent wants to send. MCP follows the same Run Modes as terminal commands, so in some modes allowlisted tools run straight away while everything else is checked first.

On teams, admins can go further. Enterprise admins can set an MCP allowlist that approves servers by command or URL pattern and limits which tools from a server can run automatically. The CLI has an --approve-mcps flag that skips approval prompts. Use it only for servers you'd trust to run unsupervised.

This matters most for tools that write: sending an email, merging a pull request, changing a database. The MCP project's own security best practices spend a lot of time on exactly this kind of risk. For a fuller framework on which actions should wait for a person, see our guide to human-in-the-loop AI agent approval.

Mistakes to avoid

  • Hardcoding API keys in mcp.json. Anyone who sees the file, or the repo it's committed to, sees the key. Use ${env:NAME} interpolation, or an OAuth server that never needs a key in the file.
  • Using envFile with a remote server. Cursor only supports envFile for stdio servers. For remote servers, set environment variables in your shell profile or system environment and reference them with interpolation.
  • Assuming "connected" means "working". A server can respond and still fail to list its tools. If tools are missing, open the Output panel (Cmd+Shift+U), choose MCP Logs, and look for handshake, sign-in or crash errors.
  • Forgetting Cloud Agents sign in separately. Cursor's docs explain that Cloud Agents keep their own MCP sign-ins on Cursor's servers. Signing out on your machine doesn't sign them out; do that from the server's Cloud row in Customize.
  • Leaving every server on. Each enabled server adds tools the agent has to choose between. Toggle off the ones you don't need for this task; disabled servers don't load or appear in chat.

Where do the results go?

Most MCP servers you add to Cursor pull information in: docs, tickets, designs, query results. The other direction is just as useful. When the agent finishes a long task, you want the result somewhere you'll actually see it, and you want to say yes or no to the risky parts without sitting at your desk.

That's the gap a results-side MCP server fills. We compared the two kinds of tool, session viewers and results dashboards, in our AI agent dashboard app for iPhone guide.

How Unorderly helps

Unorderly is a command center where AI agents, including Cursor, publish dashboards, to-dos, pipelines and approval requests to native iPhone, iPad and Mac apps. Add it to Cursor as a remote MCP server, sign in once, and the agent can choose from 14 native widgets. You can approve or reject from a notification, and every write is labelled with the agent and the time. It's free for one agent. Get Unorderly on the App Store. If you also tidy writing on the Mac between agent tasks, Saywand is a free menu-bar app that rewrites selected text in one keystroke.

FAQ

Where is the MCP config file in Cursor?

Cursor reads two mcp.json files. Put project-only servers in .cursor/mcp.json inside the project, and servers you want everywhere in ~/.cursor/mcp.json in your home folder. The Cursor CLI reads the same files, so a server you add for the editor also works with the agent command.

Does Cursor support remote MCP servers?

Yes. Cursor supports three transports: stdio for local commands, plus SSE and Streamable HTTP for servers at a URL. Remote servers can sign you in with OAuth, so you don't need to paste an API key into a config file.

How do I log in to an MCP server in Cursor?

For a remote server that uses OAuth, Cursor opens the provider's sign-in page the first time it connects, using the authorization code flow with PKCE. In the CLI, run agent mcp login followed by the server's name from mcp.json.

Why isn't my MCP server showing tools in Cursor?

Check that the server is switched on in Customize, that the JSON in mcp.json is valid, and that the sign-in finished. Then open the Output panel (Cmd+Shift+U), choose MCP Logs, and look for connection, authentication or startup errors.

Does Cursor ask before running MCP tools?

By default, yes. Cursor asks for approval before it uses an MCP tool, and you can expand the call to see the arguments first. Run Modes and team allowlists can let some tools run without asking, so check your settings before you trust a server with writes.

Can Cursor send results to my phone?

Not by itself, but an MCP server can do it. Connect a server like Unorderly and Cursor's agent can publish dashboards, to-dos and approval requests to native iPhone, iPad and Mac apps, where you approve or reject from a notification.

About Unorderly

Unorderly is an app for iPhone, iPad and Mac where AI agents such as Grok, Claude, Cursor and OpenClaw publish live dashboards: KPIs, pipelines, to-dos and approvals, built from fourteen native widgets. Agents connect through one remote MCP server with a single sign-in, and approvals can be answered from the lock screen. It is free to download on the App Store; every new account starts with 14 days of Pro, and Pro costs $9.99 a month or $79.99 a year. Unorderly is made by Swiftful Dynamics in Australia.