How does Cursor discover and load MCP servers?

Attempt it

Cursor is the AI-first VS Code fork that ships with an MCP client built into the editor shell. You declare servers in one of two JSON files: globally at ~/.cursor/mcp.json (loads for every project) or per project at .cursor/mcp.json in the repo root (loads only when that repo is open). Both files use an mcpServers map where each entry specifies command + args + env for a local stdio server or url for a remote streamable HTTP endpoint. After a reload, Cursor lists the servers under Settings > Features > MCP with status indicators. Their tools become callable inside Composer and Agent mode alongside Cursor's built-in editor tools like edit_file and run_command. The per-project file is the standout feature: a repo can commit its MCP config so new engineers get the team's databases, ticketing, and ops servers wired up on first open.

Your answer

**Cursor** is an AI-first code editor (a VS Code fork) with an MCP client built into the editor shell. That makes Cursor an MCP host: it discovers MCP servers, connects to them, and exposes their tools to its AI features. You tell Cursor about servers by editing a JSON config file. Two locations are supported. Global servers go in `~/.cursor/mcp.json` and load for every project you open. Per-project servers go in `.cursor/mcp.json` at the repo root and load only when you open that repo. Both files use a shape that mirrors Claude Desktop's: an `mcpServers` map where each entry is either `command + args + env` for a local stdio subprocess or `url` for a remote streamable HTTP endpoint. After saving and reloading, Cursor lists the servers under Settings > Features > MCP with a status indicator for each (running, errored, disabled). The tools the servers advertise then appear inside Composer and Agent mode. The model can call MCP tools alongside Cursor's native editor tools like `edit_file` and `run_command` in the same agent turn. The per-project file is the headline feature. A team can commit `.cursor/mcp.json` to the repo so everyone who clones it gets the team's Postgres, GitHub, and Sentry servers wired in automatically, with no manual setup beyond opening the repo.

**Cursor** is the AI-first VS Code fork that ships with an MCP client in the core editor shell, making it one of the most widely used MCP hosts in 2026 alongside Claude Desktop. It is not an extension; the MCP client is part of Cursor itself. Configuration uses a two-tier model. Global servers live in `~/.cursor/mcp.json` and load for every project. Per-project servers live in `.cursor/mcp.json` at the repo root and load only when you open that repo. Both files use the canonical `mcpServers` map shape: server name as key, value of `{ command, args, env? }` for stdio or `{ url }` for remote streamable HTTP. Cursor exposes a polished settings panel at Settings > Features > MCP that lists loaded servers with status indicators and a one-click reload, which avoids the full quit and restart loop Claude Desktop requires. Once loaded, server tools are callable inside both Composer (single-turn) and Agent mode (multi-step). The model mixes MCP calls with Cursor's native editor tools (`edit_file`, `run_command`, `read_file`) in the same trajectory. A prompt like 'find the TODOs that reference the auth flow and create Linear tickets for them' can hop from the codebase to the Linear MCP server in one agent run. The per-project config is the feature that changes team workflows. Committing `.cursor/mcp.json` means the repo ships its own MCP toolchain. New engineers clone the repo, open it, and the tool surface lights up with the team's databases, ticketing systems, and ops servers on first launch.

Quick reference

TL;DR

Cursor loads MCP servers from `.cursor/mcp.json` per project or `~/.cursor/mcp.json` globally, exposing their tools inside Composer and Agent mode alongside the editor's native tools.

Memory aid

Sign in for the mnemonic that makes this stick. See Pro pricing.

Easy to grasp

Imagine your code editor has hands. By default the hands can only do editor things: open a file, type, run a build. MCP lets you give the editor extra hands by listing helpers in a small file inside your project folder. One helper might know how to talk to your team's database; another might know how to comment on a pull request; another might know how to read your team's docs. The editor reads the list, starts every helper listed, and now the AI inside the editor can ask any helper to do its job. When you switch projects, the helpers change with the project, because the list lives inside the project folder. You can also keep personal helpers in a file at home that load for every project.

Key concepts

Cursor editor IDE integration MCP host

Detailed answer & concept explanation

~6 min read

Everything you need to truly understand this topic: intuition, mechanics, step by step explanation, code, formulas, and worked example. Click to expand.

Everything you need to truly understand this topic: intuition, mechanics, step by step explanation, code, formulas, and worked example.

Sign in for 5 free unlocks/day or go Pro for unlimited. See Pro pricing.

Quick scan · 2–4 min

Everything important, quickly.

3 min: Cursor as an MCP host, the two config locations (global and per-project), the entry shapes for stdio and remote, where tools show up in Composer and Agent mode, per-project config as the team onboarding win, and secrets hygiene.

Real-world examples

Real products, models, and research that use this idea.

A monorepo commits `.cursor/mcp.json` with a Postgres MCP server pointed at the dev database. Every engineer who opens the repo gets schema introspection in Agent mode without local setup.
An ops team adds the Sentry MCP server globally in `~/.cursor/mcp.json` so Agent mode can fetch recent error groups when debugging any project.
A team uses the Linear MCP server per-project so 'create a ticket for this TODO' works inside Composer with the correct project pre-selected.

Interviewer follow-ups

What an interviewer would ask next. Try answering before peeking at the approach.

QWhy does per-project MCP config matter more than global config in a team setting?

Sign in or go Pro to see the approach for this follow-up.

QHow does Cursor disambiguate two MCP servers that expose tools with the same name?

Sign in or go Pro to see the approach for this follow-up.

QWhat is the secret-handling pattern for a `.cursor/mcp.json` you intend to commit?

Sign in or go Pro to see the approach for this follow-up.

Don't say this

Red flags and common mistakes that signal junior thinking. Click to expand.

Most common mistake

Thinking Cursor exposes built-in tools like edit_file through MCP. Those are native editor tools; MCP servers add capabilities beyond the IDE itself, like database access and ticketing.

Sign in or go Pro to see all red flags and common mistakes. See Pro pricing.

60-second cheat sheet

The night-before-the-interview bullets. Scan these on the way to the call.

Sign in for 5 unlocks/day or go Pro for unlimited revision sheets. See Pro pricing.

References

Primary sources. Skim if you want the original framing.