How to Add MCP Tools to Cursor

To add MCP tools to Cursor, create a project-level .cursor/mcp.json or a global ~/.cursor/mcp.json, add either a local command config or a remote url config, and then let Cursor's agent use the tools with approval enabled by default. That is the current documented path as of April 23, 2026.

Cursor's official MCP docs say Cursor supports stdio, SSE, and Streamable HTTP transports, supports OAuth for servers that need it, and lets you install servers either through a one-click collection or by editing mcp.json directly. The same docs also explicitly list support for tools, prompts, roots, and elicitation. If you need the protocol background first, start with What Is MCP?. If you want the Claude Desktop equivalent, read How to Set Up MCP in Claude Desktop.

The shortest useful version

Here is the setup in four steps:

1. Decide whether the server belongs in a project or in your global Cursor config.
2. Add the server in .cursor/mcp.json or ~/.cursor/mcp.json.
3. Restart or reload Cursor and confirm the tools appear in chat.
4. Approve the tool call when Cursor asks, or enable auto-run later if you trust the workflow.

Cursor's current docs also say the same MCP configuration is reused by Cursor's CLI. As of January 8, 2026, Cursor documents agent as the primary CLI entry point and keeps cursor-agent as a backward-compatible alias, which is useful when you move between the editor and the terminal.

Why MCP in Cursor is different from chat-first clients

Cursor is not primarily a general-purpose chat product. It is an IDE with an agent built around code context.

That changes the value of MCP. In Cursor, MCP is most useful when the model needs both:

• your codebase context
• external tool context

That combination is why coding-oriented servers tend to shine here:

• GitHub
• Sentry
• Playwright
• Vercel
• Postman
• DuckDB
• Neon

The current Cursor MCP servers page is explicitly framed as a curated set of official developer-facing MCP tools rather than a broad consumer app directory.

Project config versus global config

Cursor's official MCP docs distinguish two config locations:

• project config: .cursor/mcp.json
• global config: ~/.cursor/mcp.json

Use project config when the tool is specific to one codebase, such as:

• a repo-specific API
• a staging database
• a deployment tool for one product

Use global config when the tool should follow you everywhere, such as:

• GitHub
• filesystem tools
• a docs search server
• general-purpose browser automation

This split is one of Cursor's best workflow advantages over chat-only clients.

The two installation paths

Cursor currently documents two clean ways to add MCP servers.

Option 1: one-click installation

Cursor's MCP docs say you can install servers from its collection and use Add to Cursor buttons in developer documentation.

Use this when:

• you want an official server from a known provider
• the install flow already handles auth cleanly
• you do not want to hand-edit JSON unless needed

Option 2: manual mcp.json

Cursor also documents direct configuration with mcp.json.

For a local stdio server:

{
  "mcpServers": {
    "filesystem": {
      "command": "npx",
      "args": ["-y", "@modelcontextprotocol/server-filesystem", "."]
    }
  }
}

For a remote server:

{
  "mcpServers": {
    "company-api": {
      "url": "https://example.com/mcp",
      "headers": {
        "Authorization": "Bearer ${env:COMPANY_MCP_TOKEN}"
      }
    }
  }
}

Cursor's docs also say it supports variable interpolation in fields like command, args, env, url, and headers, which is helpful for keeping tokens and machine-specific paths out of checked-in config.

Supported transports and auth

Cursor's official MCP docs currently describe three transport methods:

• stdio
• SSE
• Streamable HTTP

They also say:

• local stdio is managed by Cursor
• remote servers can use SSE or Streamable HTTP
• Cursor supports OAuth for servers that require it

That makes Cursor one of the more flexible IDE-side clients right now.

How Cursor uses MCP in chat

Cursor's docs describe the chat behavior pretty clearly:

• the Composer Agent automatically uses relevant MCP tools
• tools appear under Available Tools
• you can toggle specific tools on and off
• the agent asks for approval before using MCP tools by default
• you can enable auto-run later if you trust the workflow

That approval model matters. Cursor is optimized for coding speed, but it still keeps a human in the loop by default.

Real workflows that make Cursor MCP worth it

The setup only matters if the workflows get better. In Cursor, the biggest wins usually come from combining repo context with one external system.

GitHub plus local code

Use Cursor to inspect a PR, read the changed files locally, and make the fix without switching contexts between browser and editor.

Sentry plus local code

Ask Cursor to inspect a recent error, then jump straight into the relevant code path with the stack trace and repo context already in hand.

Deployments plus code

Use Vercel, Railway, or other deployment servers to check status while editing the code that actually produced the issue.

Playwright plus code changes

Use browser automation tools to validate a UI flow after an edit without leaving the editor loop.

This is the main reason Cursor often beats a general-purpose chat app for MCP in developer workflows.

Using Cursor CLI with the same MCP config

Cursor's CLI docs say cursor-agent uses the same MCP configuration as the editor. It also documents commands such as:

• cursor-agent mcp list
• cursor-agent mcp list-tools <identifier>
• cursor-agent mcp login <identifier>
• cursor-agent mcp disable <identifier>

That makes troubleshooting easier because you can inspect server status and tools without guessing from the editor alone.

Troubleshooting the common failures

The tools never appear

Check these first:

• wrong config location
• malformed JSON
• server process does not start
• missing env vars

If the server exists but stays disconnected, inspect it through the CLI or reload Cursor.

Auth works in theory, but tool calls fail

Cursor's docs say auth is usually handled through environment variables or OAuth. In practice, that means you should verify the actual token source rather than assume the JSON alone is enough.

Cursor keeps asking before every tool call

That is the documented default. Approval comes first, then optional auto-run if you want a faster workflow and trust the tool.

The wrong tool fires

Disable overlapping tools in the tool list for that session or narrow the tool set. Cursor lets you toggle tools directly in the chat UI for exactly this reason.

Using drio with Cursor

If you build a remote MCP server in drio, the Cursor-side setup is simple:

1. copy the deployed MCP endpoint
2. add it as a remote server in mcp.json
3. authenticate if needed
4. let Cursor use it like any other server

That gives you the same server in Cursor, Claude, and ChatGPT without a client-specific rebuild. For the broader portability picture, go next to MCP Client Comparison.

Summary

Cursor MCP setup is straightforward once you keep the model simple: project-specific servers belong in .cursor/mcp.json, shared tools belong in ~/.cursor/mcp.json, and Cursor can connect through stdio, SSE, or Streamable HTTP. Tools are approved by default, can be toggled in chat, and the same config also works in cursor-agent.

The reason to use MCP in Cursor is not novelty. It is leverage. Cursor already understands your code, and MCP lets it bring the right external systems into that same workflow.

FAQ

Where does Cursor look for MCP config?

Cursor's docs describe two main locations: .cursor/mcp.json for project-level config and ~/.cursor/mcp.json for global config.

Does Cursor support remote MCP servers?

Yes. Cursor's docs say it supports remote servers over both SSE and Streamable HTTP, alongside local stdio servers.

Does Cursor support OAuth for MCP servers?

Yes. Cursor's MCP docs explicitly say OAuth is supported for servers that require it.

Does Cursor ask before using MCP tools?

Yes by default. Cursor's docs say agent tool approval is on by default, and auto-run is an optional faster mode.

What should I read after this?

Read MCP Client Comparison if you are choosing between Cursor, Claude Desktop, ChatGPT, VS Code, and Windsurf. Read How to Set Up MCP in Claude Desktop if you need the mixed local-and-remote desktop flow on Anthropic's side.

If you already know the tool you want to ship, the next step is not more setup theory. It is picking the smallest useful server, wiring it into mcp.json, and testing the real coding task you want Cursor to help with.