Set Up Cursor MCP Servers: 12 Steps, 45 Min [2026]

Cursor shipped CLI release v2026.10.08 with a quiet but important change: the agent now tells the difference between a Model Context Protocol action that merely drafts, previews, or reads something, and one that sends, publishes, applies, or deletes it. That distinction only matters if your MCP servers are actually configured, authenticated, and approved in the first place. Search interest around “cursor mcp” has climbed as more teams wire GitHub, Figma, Postgres, and internal tooling directly into their agent sessions, yet the setup path spans three different surfaces: the Cursor editor, the Cursor CLI, and Cursor’s cloud agents. Each reads the same mcp.json file but handles authentication and approval differently.

We will configure a local stdio server, an HTTP remote server, verify discovery inside the editor, authenticate from the terminal, inspect exposed tools, and lock down the risky actions before they run unattended. By the end you will have a repeatable project template plus a troubleshooting checklist for the errors that show up most often.

Don't miss new tech stories on Google

Add Shattered once in the Google app and our stories show up in your news suggestions.

Add now

What MCP Actually Does Inside Cursor #

Model Context Protocol is the open standard that lets an AI agent call out to external tools, APIs, and data sources through a consistent interface instead of a pile of one-off integrations. Inside Cursor, an MCP server might expose a database query tool, a ticket-creation tool, a design-file reader, or a deployment trigger. The agent discovers these tools, decides when to call them based on your prompt, and (depending on your approval settings) either runs them automatically or waits for you to click approve.

Cursor supports two server transport types. A stdio server runs as a local process on your machine, typically started with a command like npx or python, and communicates over standard input and output. An HTTP (or SSE) server runs remotely and Cursor talks to it over a URL, which is the shape most third-party SaaS integrations use. Both are declared in the same mcp.json file, and both are visible to the editor, the Cursor CLI, and cloud agents once configured correctly.

What changed recently is the approval model around those tool calls. Earlier CLI builds treated every MCP action as equally risky, which meant constant interruptions even for a read-only lookup. The v2026.10.08 release separates low-risk actions (drafting, previewing, planning, reading) from high-impact ones (sending, publishing, applying, deleting), so a workflow that reads a dozen files and only writes one commit does not require a dozen manual approvals.

That split matters more than it sounds. Before the change, a lot of teams either disabled approval prompts entirely out of fatigue, which removed the one guardrail between an agent and a production system, or kept prompts on and accepted the interruption cost on every single tool call, which pushed people away from using MCP servers at all for anything beyond quick experiments. The new model is an attempt to keep the guardrail where it actually protects you while getting it out of the way everywhere else, and the setup steps below are built around taking advantage of that distinction rather than just getting a server to connect.

Prerequisites and Versions #

Before starting, confirm you have the following in place. Version mismatches are the single most common reason an MCP server shows up in the editor but fails silently in the CLI, or vice versa.

• Cursor editor, latest stable build (Settings → General → Check for Updates)
• Cursor CLI v2026.10.08 or later (run agent --version to check)
• Node.js 18 or later, if any of your stdio MCP servers run via npx
• Python 3.10 or later, if any stdio server runs via uvx orpython
• A terminal with write access to your project root and your home directory
• Admin access to any third-party service (GitHub, a database, an internal API) you plan to connect through MCP, since several setups require generating a personal access token or OAuth client ID first

Install the CLI if you have not already. On macOS, Linux, and Windows under WSL, run:

curl https://cursor.com/install -fsS | bash

On native Windows PowerShell, use the equivalent installer:

irm 'https://cursor.com/install?win32=true' | iex

After installation, the binary lands in ~/.local/bin on Unix-like systems. If agent --version comes back as “command not found,” add that directory to your shell’s PATH and reopen the terminal before continuing.

Step 1: Decide Project-Level or Global Configuration #

Cursor reads MCP configuration from two locations, and the choice affects who can see and use a given server. Project-level configuration lives at .cursor/mcp.json inside the repository, gets committed to version control (minus any secrets, which belong in environment variables), and only applies while you have that project open. Global configuration lives at ~/.cursor/mcp.json in your home directory and applies across every project you open on that machine.

Both the editor and the CLI follow the same precedence order: project configuration first, then global, then any nested configuration further down the directory tree. For a team setup, put shared servers like an internal ticketing tool or a shared Postgres read replica at the project level so every contributor gets the same tools automatically. Keep personal servers, like a local filesystem browser scoped to your own dotfiles, in the global file.

Create the project-level file now:

mkdir -p .cursor
touch .cursor/mcp.json

Step 2: Add a Local stdio MCP Server #

stdio servers are the fastest way to get started because most published MCP servers ship as an npm package you run with npx, with no deployment step. The configuration schema uses a top-level mcpServers object, where each key is a name you choose and each value describes how to launch that one server.

Open .cursor/mcp.json and add a filesystem server, which is a common first server because it lets the agent read and list files outside the project directory when you explicitly grant that access:

{
  "mcpServers": {
    "filesystem": {
      "command": "npx",
      "args": ["-y", "mcp-server", "--root", "/Users/you/reference-docs"],
      "env": {
        "LOG_LEVEL": "info"
      }
    }
  }
}

The command field is required and must resolve on your system PATH. args is optional and gets passed straight to that command. env injects environment variables scoped to that one server process, which is where API keys and tokens belong rather than hard-coded in args. There is also an envFile field if you would rather point at a separate .env file instead of inlining values.

Step 3: Add a Remote HTTP MCP Server #

Remote servers skip the local process entirely and point Cursor at a URL, which is how most SaaS vendors expose MCP today. The same mcpServers object holds both types side by side, so your project can mix a local stdio server with a hosted one without any extra wiring:

{
  "mcpServers": {
    "filesystem": {
      "command": "npx",
      "args": ["-y", "mcp-server", "--root", "/Users/you/reference-docs"]
    },
    "internal-api": {
      "url": "https://api.yourcompany.com/mcp",
      "headers": {
        "Authorization": "Bearer ${API_TOKEN}"
      }
    }
  }
}

For services that support full OAuth instead of a static bearer token, Cursor accepts an auth block with a client ID, client secret, and scopes list:

{
  "mcpServers": {
    "oauth-server": {
      "url": "https://api.example.com/mcp",
      "auth": {
        "CLIENT_ID": "your-oauth-client-id",
        "CLIENT_SECRET": "your-client-secret",
        "scopes": ["read", "write"]
      }
    }
  }
}

Never commit a real client secret to version control, even in a project-level file. Reference an environment variable the same way the bearer token example does above, and keep the actual value in your shell profile, a secrets manager, or an untracked .env file loaded through envFile.

Step 4: Open Cursor and Verify Server Discovery #

Save mcp.json and open (or reload) the project in the Cursor editor. Go to Settings → MCP, where both servers should appear in the list with a status indicator. A green or active status means Cursor successfully started the stdio process or reached the HTTP endpoint. A gray or error status usually points to a bad command path, a missing dependency, or a malformed JSON file.

If nothing shows up at all, check that the file is valid JSON first. A single trailing comma will cause Cursor to silently ignore the entire file rather than show a parse error in some builds, so running the file through any JSON validator before troubleshooting further saves time.

Step 5: Authenticate from the Cursor CLI #

The CLI automatically detects and respects the same mcp.json file the editor uses, so there is no separate configuration step for the terminal. What does need a separate action is authentication for any server that requires it. Run:

agent mcp login internal-api

This triggers a streamlined login flow with automatic callback handling, meaning the CLI opens a browser tab for the OAuth exchange and picks up the resulting token on its own without you pasting anything back into the terminal. For servers using a static bearer token instead of OAuth, this command is unnecessary since the token already lives in the headers field of the config.

Step 6: List Configured Servers and Inspect Their Tools #

Confirm the CLI sees everything the editor sees:

agent mcp list

This prints every configured server and its current status. Once a server shows as reachable, inspect exactly which tools it exposes and what arguments each one accepts, which matters before you let an agent call something you have not reviewed:

agent mcp list-tools internal-api

Read through the tool names and argument schemas here before moving on. This is the step most tutorials skip, and it is the one that catches a server exposing a destructive “delete_record” tool you did not expect to have access to.

Step 7: Enable the Server for Agent Use #

A configured server is not automatically trusted. Add it to your local approved list with:

agent mcp enable internal-api

If you ever want to pull a server out of rotation without deleting its configuration, for example while you investigate unexpected behavior, the inverse command stops it from or prompting for approval at all:

agent mcp disable internal-api

Step 8: Test the Integration in Agent Mode #

Back in the editor, open a chat and switch to Agent mode. Ask something that clearly requires the new server, such as “list the open tickets assigned to me” if you connected a project-tracker MCP server, or “read the README in the reference-docs folder” for the filesystem example above. Watch the tool-call card that appears in the conversation. It should name the exact server and tool it is invoking, along with the arguments, before (or after) running it depending on your approval settings.

If the agent answers from general knowledge instead of calling the tool, it usually means either the server is not enabled, or your prompt was too vague for the agent to recognize the tool as relevant. Being explicit about which tool or server to use in the first test prompt removes that ambiguity.

Step 9: Reuse the Exact Same Setup from the Terminal #

Because the CLI shares configuration, rules, and MCP servers with the editor, you can run the identical workflow from a terminal session, which matters for CI pipelines, remote servers without a GUI, or just a faster keyboard-driven loop. The CLI exposes a handful of mode shortcuts worth knowing:

• /plan switches to planning mode before any code changes happen
• /ask switches to a read-only exploration mode with no file modifications
• Shift+Tab rotates between modes without typing a command
• @ followed by a path includes a specific file or folder in context
• /summarize compresses the current context window when it gets long
• Prefixing a prompt with & hands the task off to a cloud agent instead of running locally

For scripted or CI use, run the CLI non-interactively and capture structured output:

agent -p "check the internal-api MCP server for any tickets labeled urgent" \
  --output-format json \
  --approve-mcps

The --approve-mcps flag skips interactive approval prompts entirely, auto-approving every configured server for that run. Reserve it for pipelines you trust and for servers you have already reviewed with list-tools, since it removes the one safety check that normally sits between the agent and a high-impact tool call.

Step 10: Add Project Guidance with .cursor/rules #

MCP gives the agent tools, and rules tell it when and how to use them. Both the editor and the CLI read the same rules system, stored as files inside a .cursor/rules directory at your project root, plus any AGENTS.md or CLAUDE.md file sitting directly in the root. Create a rule that steers tool usage:

mkdir -p .cursor/rules
cat > .cursor/rules/mcp-usage.md << 'EOF'
---
description: Guidance for using the internal-api MCP server
alwaysApply: true
---

- Always call `list-tools` logic before assuming a tool exists; do not guess argument names.
- Never call a delete or close-ticket tool without explicit user confirmation in the same turn.
- Prefer the filesystem MCP server over shell commands when reading files outside the repo root.
EOF

If your team already maintains an AGENTS.md file for other agent tooling, Cursor's CLI will pick it up automatically alongside this directory, so there is no need to duplicate guidance across both formats.

Step 11: Set Approval Boundaries for High-Impact Actions #

This is where the v2026.10.08 CLI release matters directly. The agent now classifies MCP tool calls into lower-risk actions (drafting, previewing, planning, reading) and higher-impact ones (sending, publishing, applying, deleting), and only the second group should require your explicit approval by default. In Cursor's settings, review the approval policy for each enabled MCP server and confirm that any tool name containing "delete," "send," "publish," "merge," or "deploy" is flagged for manual review rather than silently approved.

For a server you fully trust and have already audited with list-tools, such as a read-only analytics dashboard, auto-approval is reasonable. For anything that writes to a production system, keep the approval prompt on even if it adds friction. The whole point of separating risk tiers is so that friction only shows up where it is earning its keep.

Step 12: Extend MCP to Cloud Agents and Teams #

Local mcp.json configuration only helps the person running it. For a team running agents in Cursor's cloud environment, servers need to be registered at the team level instead. Go to the MCP dropdown at cursor.com/agents and add the same server definitions there. Cloud agents support both HTTP and stdio transports, OAuth authentication for servers that need it, and ship with a built-in Cursor Cloud MCP that exposes run diagnostics such as transcripts, run events, environment details, and setup logs for any agent run, which is useful when a cloud run fails and you need to see exactly what the agent attempted.

Keep in mind that cloud-agent MCP configuration is managed separately from your local file, so a server you added to your laptop's ~/.cursor/mcp.json will not automatically appear for cloud runs. Add anything a cloud agent needs through the web dashboard as a deliberate second step.

Cursor MCP CLI Command Reference #

Keep this table nearby while you work through the steps above. These are every agent mcp subcommand documented for the Cursor CLI as of the v2026.10.08 release.

Command	What it does	Typical use
agent mcp list	Shows every configured server and its current status	First check after editing mcp.json
agent mcp list-tools <id>	Lists tools exposed by one server, with argument names	Audit before enabling a new server
agent mcp login <id>	Runs the OAuth login flow for a server that requires it	First-time setup of an authenticated server
agent mcp enable <id>	Adds a server to the local approved list	After reviewing its tools
agent mcp disable <id>	Stops a server from or prompting for approval	Temporarily pulling a server out of rotation
agent --version	Confirms your installed CLI version	Checking you are on v2026.10.08 or later

stdio vs HTTP vs Cloud-Agent MCP: Which Transport to Pick #

Most projects end up mixing transport types rather than picking one, but knowing the tradeoffs upfront saves a rewrite later.

Transport	Runs where	Best for	Auth options	Visible to cloud agents?
stdio	Local process on your machine	Filesystem access, local dev databases, CLI wrappers	Environment variables, envFile	Only if registered separately at team level
HTTP/SSE	Remote server you or a vendor host	SaaS integrations, shared internal APIs	Bearer headers, OAuth (auth block)	Yes, same URL works for both
Cloud-agent registered	Configured via cursor.com/agents dashboard	Team-wide tools for unattended cloud runs	OAuth, HTTP, stdio all supported	Yes, by definition

A practical rule of thumb: default to stdio for anything that only needs to run on your own machine, such as a local filesystem browser or a wrapper around a CLI tool you already have installed. Reach for HTTP the moment more than one person needs the same server, since a remote endpoint means everyone points at the same running instance instead of each person installing and maintaining their own local copy. Reserve cloud-agent registration for servers that unattended, scheduled, or long-running agent tasks need to reach, since those runs have no local machine to fall back on at all.

A Complete Working Project #

Here is a full .cursor/mcp.json that combines everything from the steps above into one project: a local filesystem server for reference docs, an authenticated internal API over HTTP, and an OAuth-secured third-party service, alongside a rules file that constrains how the agent uses them.

The Configuration File

{
  "mcpServers": {
    "filesystem": {
      "command": "npx",
      "args": ["-y", "mcp-server", "--root", "./docs"],
      "env": {
        "LOG_LEVEL": "info"
      }
    },
    "internal-api": {
      "url": "https://api.yourcompany.com/mcp",
      "headers": {
        "Authorization": "Bearer ${API_TOKEN}"
      }
    },
    "ticketing": {
      "url": "https://tickets.example.com/mcp",
      "auth": {
        "CLIENT_ID": "${TICKETING_CLIENT_ID}",
        "CLIENT_SECRET": "${TICKETING_CLIENT_SECRET}",
        "scopes": ["read", "comment"]
      }
    }
  }
}

Rules and Guardrails

Pair it with this rules file, saved at .cursor/rules/mcp-usage.md, and an AGENTS.md at the project root that a terminal-based agent (including non-Cursor tooling) can also read:

This project connects three MCP servers: filesystem (local docs),
internal-api (company backend, read and write), and ticketing
(read and comment only, no ticket creation or closing).

Rules:
- Treat internal-api write calls as high-impact; confirm with the user first.
- ticketing is scoped to read and comment; never attempt to escalate scopes.
- Use filesystem for anything under ./docs instead of shell `cat` or `find`.

Verifying the Setup

With both files in place, run the full verification sequence once to confirm everything is wired correctly end to end:

agent mcp list
agent mcp login internal-api
agent mcp login ticketing
agent mcp list-tools internal-api
agent mcp list-tools ticketing
agent mcp enable internal-api
agent mcp enable ticketing
agent mcp enable filesystem

Expected output from agent mcp list after a clean setup looks like this:

NAME           STATUS      TRANSPORT   AUTH
filesystem     connected   stdio       none
internal-api   connected   http        bearer
ticketing      connected   http        oauth

If any row shows "error" or "unauthorized" instead of "connected," jump to the troubleshooting section below before re-running the enable commands, since enabling a broken server just moves the same error into the editor.

Security Considerations Before You Connect Production Systems #

An MCP server is, functionally, a new API client with credentials that an AI agent can decide to invoke on its own. That is a different risk profile than a human running a CLI command, because the agent is reasoning about intent from natural language rather than executing a command you typed character by character. Before pointing any MCP server at a production database, billing system, or customer-facing API, scope the credentials it uses down to the minimum the intended workflow needs, the same way you would for a CI service account.

For OAuth-based servers, request the narrowest scopes array that still supports your use case. The example ticketing server earlier in this tutorial requests only read and comment scopes rather than full write access, which means even if a prompt injection or a confused agent tries to close or delete a ticket, the underlying token physically cannot perform that action. This is a stronger control than an approval prompt, because it holds even if a teammate later disables approval prompts for convenience.

For HTTP-based servers, treat the url field as sensitive if it points at an internal network address rather than a public SaaS endpoint. A misconfigured server pointed at an internal admin panel with no additional auth layer is a bigger liability than the same misconfiguration against a public API with its own rate limiting and access logs. Where possible, put internal MCP endpoints behind the same authentication gateway your other internal tools already use, rather than treating MCP traffic as a special case that bypasses existing controls.

Finally, audit who can edit .cursor/mcp.json in your repository the same way you would audit who can edit a CI pipeline file. Anyone with write access to that file can point a server name at a different, malicious endpoint while leaving the rest of the config looking identical, which is the kind of change a quick glance during code review can miss. Treat changes to MCP configuration as worth a second reviewer, the same way you would treat a change to deployment credentials.

Debugging MCP Server Logs #

When a server reports "connected" but tool calls still fail, or when the editor and CLI disagree about a server's status, raw logs save more time than retrying the same command. For a stdio server, redirect its output to a file so you can inspect what the process actually printed rather than what Cursor's UI summarized:

npx -y mcp-server --root ./docs > /tmp/mcp-filesystem.log 2>&1
cat /tmp/mcp-filesystem.log

Running the exact command from mcp.json by hand, outside of Cursor, isolates whether the problem is in the server itself or in how Cursor is invoking it. If the command fails identically in both places, the fix belongs to the server or its dependencies. If it works fine standalone but fails inside Cursor, check for environment variables that exist in your interactive shell but were never exported, since Cursor launches the process with its own environment rather than inheriting your terminal session's exports by default.

For HTTP servers, a quick manual request confirms whether the endpoint itself is the problem before blaming Cursor's configuration:

curl -i -H "Authorization: Bearer $API_TOKEN" https://api.yourcompany.com/mcp

A 401 or 403 response here confirms a token or scope problem independent of Cursor. A connection timeout or refused connection points to network access, firewall rules, or a server that is simply not running, none of which Cursor's own error messages always distinguish clearly.

Risk Tiers for MCP Tool Calls #

Use this as a starting checklist when you review a new server's tools with list-tools and decide which ones should require manual approval under the current risk-tiered model.

Tool name pattern	Risk tier	Default approval	Example
read, list, get, search, preview	Low	Auto-run	list_tickets, read_file, search_records
draft, plan, suggest, lint	Low	Auto-run	draft_reply, plan_migration
create, update, comment	Medium	Review on first use	create_ticket, comment_on_issue
send, publish, merge, deploy	High	Manual approval every time	send_email, publish_release, merge_pull_request
delete, close, revoke, drop	High	Manual approval every time	delete_record, revoke_access, drop_table

This mapping is a starting point, not a substitute for actually reading each tool's description with list-tools. Some servers name a destructive action something deceptively mild, such as "archive_record" for something that is functionally a permanent delete, so the name pattern alone is not a guarantee.

Common Pitfalls When Setting Up Cursor MCP #

These mistakes account for most of the "my MCP server isn't working" reports in community threads and support channels.

• Hardcoding secrets directly in mcp.json. If the project-level file gets committed, that token is now in your git history permanently, even after you remove it in a later commit. Use environment variable references instead.
• Forgetting that project config overrides global config. If a server behaves differently than expected, check whether a project-level.cursor/mcp.json is silently shadowing a server you defined globally with the same name.
• Treating every MCP tool call the same way. Approving a destructive tool out of habit because you got used to approving read-only ones defeats the entire purpose of the risk-tiered approval model in the current CLI.
• Skipping list-tools before enabling a new server. Third-party MCP servers sometimes expose more than their documentation mentions. Reading the actual tool list avoids surprises mid-session.
• Assuming cloud agents inherit your local config. Cloud-agent MCP servers are configured separately at cursor.com/agents, and nothing in your local~/.cursor/mcp.json travels there automatically.
• Using a relative path in a stdio command's args. A command that works when launched from your project root can fail silently when the CLI or editor launches it from a different working directory. Use absolute paths for anything outside the project.

Troubleshooting Cursor MCP Setup Issues #

Work through these in order when a server will not connect, will not authenticate, or will not show up where you expect it.

• Server does not appear in the editor at all. Validate the JSON syntax inmcp.json first. A single trailing comma or missing brace can make Cursor ignore the whole file without an error message.
• Server appears but status is stuck on "connecting." For stdio servers, run the exactcommand andargs manually in your terminal to see the raw error output Cursor is hiding.
• "agent: command not found" after installation. The binary lives in~/.local/bin . Confirm that directory is on your PATH and restart your terminal session.
• agent mcp list shows nothing even though mcp.json has entries. You are likely running the command from outside the project directory. The CLI resolves project-level config relative to your current working directory.
• OAuth login opens a browser but never completes. Check that no corporate firewall or proxy is blocking the local callback port the CLI uses to catch the redirect.
• A tool call fails with a permissions or scope error. Re-check thescopes array in yourauth block. Most OAuth providers reject a token request for a scope the registered app was never granted.
• The same server behaves differently in the CLI than in the editor. Confirm both are reading the samemcp.json by checking for a stray global config at~/.cursor/mcp.json that only one of the two surfaces is picking up.
• Cloud agent runs can't see a server you just added. Team-level MCP registration through the dashboard can take a short propagation delay. Also confirm you added it to the correct team if you belong to more than one.
• Environment variables in env or headers resolve as literal text instead of substituting a value. Confirm the variable is actually exported in the shell Cursor itself was launched from, not just a subshell you ran manually.
• --approve-mcps isn't skipping prompts in a CI job. Confirm the flag is passed to the same invocation using-p /--print , since interactive sessions ignore it by design.

Advanced Tips for Production MCP Setups #

Once the basics work, a few habits separate a setup that survives six months of team growth from one that quietly rots.

First, isolate risky agent runs with git worktrees. The CLI's --worktree [name] flag spins up a temporary, isolated working copy for a given task, so an agent running with --approve-mcps enabled cannot accidentally touch your primary working tree if something goes sideways.

Second, treat /summarize as a tool for long MCP-heavy sessions specifically. Sessions that call list-tools against several servers and then make a dozen follow-up tool calls burn through context fast. Summarizing partway through keeps the agent's reasoning grounded instead of trailing off as the window fills.

Third, version your rules alongside your MCP config. A .cursor/rules/mcp-usage.md file that says which tools are safe to auto-approve is only useful if it stays in sync with what mcp.json actually declares. Review both files in the same pull request whenever either changes.

Fourth, for anything built on top of Claude models through Cursor's agent backend, the setup patterns are close enough to Anthropic's own MCP implementation that lessons from building a secure Claude MCP server carry over directly, particularly around scoping OAuth permissions down to the minimum your tool actually needs.

Fifth, if your team already standardized on .cursor/rules files for a Copilot-to-Cursor migration, as covered in our walkthrough on migrating Cursor rules from GitHub Copilot, extend those same files with MCP-specific guidance rather than starting a parallel rules system.

MCP Setup Checklist Before You Ship #

Run through this before calling the setup finished, especially for anything touching production data.

• No secrets are hardcoded in any committed mcp.json file
• agent mcp list shows every server as connected, not pending or errored
• agent mcp list-tools has been run and reviewed for every enabled server
• High-impact tools (delete, send, publish, deploy, merge) require manual approval
• A .cursor/rules file documents which servers exist and their intended scope
• Cloud-agent registration at cursor.com/agents matches what local contributors use, if cloud runs are part of the workflow
• Someone other than the person who wrote the config has tested it from a clean checkout

That last item catches more bugs than any of the others combined. Configuration that works because of a stray environment variable left over in your own shell session will fail the moment a teammate pulls the same repo.

How This Compares to Setting Up MCP Elsewhere #

Cursor is not the only place you will configure mcp.json-style files. Claude Desktop, Claude Code, and a growing list of other agentic coding tools use the same mcpServers schema with minor variations. That overlap is a genuine advantage: a server you already wired up for one client usually needs only the transport details copied into Cursor's file rather than a from-scratch rebuild. Teams running both Claude Code and Cursor CLI side by side often maintain one canonical server list and generate each tool's config file from it, rather than hand-editing three separate JSON files that drift out of sync over a few months.

Where Cursor's implementation stands apart is the risk-tiered approval model introduced in the October CLI release and the dedicated cloud-agent MCP layer with built-in run diagnostics. If you are coming from a tool that treats every tool call identically, budget time to actually configure approval boundaries rather than leaving every server on default settings, since the whole benefit of the new model disappears if nothing is marked high-impact.

In practice, most engineering teams end up supporting more than one agentic coding tool at once rather than standardizing on a single one, since different people on the same team often have strong preferences. The maintenance cost of that is almost always in configuration drift rather than in the servers themselves: the filesystem server that works perfectly in Cursor gets forgotten when someone adds a new MCP integration for Claude Code and never backports it. Keeping a single source-of-truth document, even something as simple as a shared markdown file listing every MCP server, its transport, and which tools it should expose, is cheap insurance against that drift and takes a few minutes to set up alongside the mcp.json file itself.

Keeping MCP Servers Current as Cursor Updates #

Cursor ships CLI and editor updates frequently enough that an MCP workflow built six months ago is worth re-auditing rather than assumed to still be best practice, a pace that showed up again with the Cursor Origin launch and its own wave of configuration changes for teams moving between editors. Check the official Cursor changelog index or a dedicated tracker like changelogs.directory's Cursor history periodically, specifically scanning for the words "MCP," "approval," or "tool call" in release notes, since those are the entries most likely to change how your existing config behaves without any action on your part.

For teams managing CLI parameters and flags across multiple machines, third-party references such as Arantic's Cursor CLI documentation can be a useful secondary cross-check against Cursor's own docs when you are debugging a flag that behaves unexpectedly, though the official docs should always be the first stop for anything authoritative.

If your team is also comparing how Cursor's agent stacks up against GitHub Copilot's own tool-calling model, the hands-on numbers in our Cursor versus GitHub Copilot benchmark are a useful companion read once your MCP servers are live, since tool-call latency and approval friction are exactly the kind of thing raw benchmark numbers tend to miss.

Frequently Asked Questions #

What is the difference between a project-level and global MCP configuration in Cursor?

Project-level configuration lives at .cursor/mcp.json inside a specific repository and only applies while that project is open. Global configuration lives at ~/.cursor/mcp.json in your home directory and applies to every project on that machine. Project configuration takes precedence when both define a server with the same name.

Does the Cursor CLI need its own separate MCP setup from the editor?

No. The CLI automatically detects and respects the same mcp.json file the editor uses, along with the same .cursor/rules directory, AGENTS.md, and CLAUDE.md files. What does require a separate step per surface is authentication, since OAuth logins are tied to the session that initiated them.

What is the --approve-mcps flag and when should I use it?

It auto-approves every configured MCP server for a single CLI run, skipping interactive prompts. It is intended for scripted or CI use with servers you have already reviewed through agent mcp list-tools, not as a default setting for everyday interactive sessions.

Can I use the same MCP server with both stdio and HTTP configurations?

A single server entry uses one transport or the other, defined by whether you set a command field (stdio) or a url field (HTTP/SSE). If a vendor offers both options, you choose per entry. Running the same logical integration through two separate entries with different names is possible but adds maintenance overhead for no real benefit.

Why does my MCP server work in the editor but not when I use agent mcp list in the terminal?

The most common cause is running the CLI command from outside the project root, so it cannot find the project-level .cursor/mcp.json. Navigate to the project directory first, or check whether a global config at ~/.cursor/mcp.json is overriding what you expect.

Do cloud agents use my locally configured MCP servers automatically?

No. Cloud agents read MCP server configuration registered separately at cursor.com/agents through the MCP dropdown. A server defined only in your local mcp.json will not be available to a cloud-run agent until you add it there as well.

How do I know which MCP tools require manual approval versus running automatically?

Starting with CLI v2026.10.08, Cursor classifies MCP actions into lower-risk categories (drafting, previewing, planning, reading) and higher-impact categories (sending, publishing, applying, deleting). Review your per-server approval settings in Cursor's MCP settings panel to confirm high-impact tool names are flagged for manual review rather than auto-approved.

Is it safe to store API tokens directly in mcp.json?

Only in a global, untracked configuration file on your own machine, and even then an environment variable reference is safer. Never store a real token in a project-level mcp.json that gets committed to version control. Use the env, envFile, or ${VARIABLE} substitution patterns shown throughout this tutorial instead.

What should I do if an MCP server shows "connected" but every tool call fails?

Run agent mcp list-tools against that server to confirm the tool names and argument schemas match what you expect. A server can report a healthy connection status while still rejecting calls due to an expired token, an insufficient OAuth scope, or a tool that was renamed in a recent server update.

source & further reading

shattered.io — original article Cursor Origin Launches Amid GitHub’s 6-Hour Outage [2026] OpenCode Breach Exposes AI Keys for 1.4% of Users [2026] Nvidia Wins Modal CPU Deal, Claims 2x AI Agent Speed [2026]