Cursor MCP Servers

Quick answer

MCP servers are external tool processes that Cursor Composer calls during agent runs. Enable MCP in Settings > Features, then add servers to .cursor/mcp.json in your project or ~/.cursor/mcp.json globally. Each server runs as a child process and appears in the Composer tool picker. The six servers most teams start with: filesystem, GitHub, Postgres, Brave Search, Slack, and Supabase. Setup is free. Most servers install via npx with one line of config.

What MCP is in Cursor

Model Context Protocol (MCP) is the plug system that lets Cursor Composer call external tools during an agent run. Instead of pasting API docs or copy-pasting data into chat, you wire up a server once and Composer can query a database, open GitHub issues, or hit the web at will. This page covers enabling MCP, writing an mcp.json, six servers worth adding on day one, transport choices, debug flags, and how MCP compares to the older @Docs feature.

Why MCP matters

MCP is a shared protocol from Anthropic that standardizes how AI clients talk to tool servers. Cursor added first-class MCP support in late 2025. Any process that speaks MCP over stdio or SSE can show up in Composer as a new tool. Composer then picks tools based on your prompt the same way it picks the Edit File or Run Terminal tools.

The practical impact: Composer stops being a closed box. You can give it a Postgres connection and it will actually query your schema. You can give it a GitHub token and it will open a PR with a written description.

Enabling MCP

Open Settings. On macOS that is Cmd+, and on Windows Ctrl+,. Navigate to Features and find the MCP section. Toggle Enable MCP servers to on. Restart Composer panels if you had any open.

There is no separate per-workspace toggle. Once MCP is on, Cursor looks for two config files: a global one at ~/.cursor/mcp.json and a project-scoped one at .cursor/mcp.json in the workspace root. Project config overrides global keys with the same name.

Writing mcp.json

The file shape is a single object with a mcpServers key. Each entry maps a server name to a command and args plus optional env variables.

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

Cursor starts the command as a child process the first time Composer needs it. The -y flag on npx skips the install prompt. Save the file, then open Composer. You should see the new server listed in the tool picker.

Six MCP servers worth adding first

Below are six servers that cover most day-to-day needs: filesystem, GitHub, Postgres, web search, Slack, and Supabase. Each entry includes the npx command and a short note on what it unlocks.

1. Filesystem server

"filesystem": {
  "command": "npx",
  "args": ["-y", "@modelcontextprotocol/server-filesystem", "/Users/you/notes", "/Users/you/designs"]
}

Gives Composer read and write access to directories outside the current workspace. Useful when your design tokens live in one repo, your app in another, and you want Composer to copy between them without you doing the shuffling.

Pass one or more absolute paths as trailing args. Composer can only touch those roots.

2. GitHub server

"github": {
  "command": "npx",
  "args": ["-y", "@modelcontextprotocol/server-github"],
  "env": {
    "GITHUB_PERSONAL_ACCESS_TOKEN": "ghp_your_token_here"
  }
}

Composer can list issues, read PR diffs, add comments, and create branches. Scope the token: repo for private repositories, read:org if you want org-level issue search.

Prompt examples that start working once this is wired up: "read issue 412 and draft a fix", "summarize the last 10 merged PRs in this repo".

3. Postgres server

"postgres": {
  "command": "npx",
  "args": ["-y", "@modelcontextprotocol/server-postgres", "postgresql://user:pass@localhost:5432/mydb"]
}

Composer can run read-only queries against the connection string. This turns "why is the join slow" from a 10-minute copy-paste exercise into a direct question. The server defaults to read-only; do not give it a write-enabled role on a production database.

4. Brave Search server

"brave-search": {
  "command": "npx",
  "args": ["-y", "@modelcontextprotocol/server-brave-search"],
  "env": {
    "BRAVE_API_KEY": "your_brave_api_key"
  }
}

Gives Composer a real web search call instead of hallucinating URLs. Brave has a free API tier with 2000 queries per month. Composer will use it for questions like "find the release notes for Postgres 17.2" or "what is the current rate limit on Stripe webhooks".

5. Slack server

"slack": {
  "command": "npx",
  "args": ["-y", "@modelcontextprotocol/server-slack"],
  "env": {
    "SLACK_BOT_TOKEN": "xoxb-your-token",
    "SLACK_TEAM_ID": "T0000000000"
  }
}

Lets Composer post messages, read channel history, and search messages. Common uses: drop a deploy note into #releases after a Composer-driven deploy, or pull a support thread into the IDE to triage a bug.

The bot token needs at minimum: chat:write, channels:history, channels:read, and search:read.

6. Supabase server

"supabase": {
  "command": "npx",
  "args": ["-y", "@supabase/mcp-server-supabase"],
  "env": {
    "SUPABASE_ACCESS_TOKEN": "sbp_your_pat"
  }
}

Manages Supabase projects: list tables, run SQL, deploy edge functions, inspect logs. A big productivity win if you use Supabase because it removes every trip to the dashboard.

Transport types: stdio vs SSE

MCP supports two transports. All six examples above use stdio, where Cursor spawns a local process and pipes JSON over stdin and stdout. Stdio is simple and works out of the box.

SSE (Server-Sent Events over HTTP) is for remote servers. The config looks different:

"remote-server": {
  "url": "https://mcp.example.com/sse",
  "headers": {
    "Authorization": "Bearer your_token"
  }
}

Use SSE when the server is shared across a team or runs on infrastructure you do not want every developer to install locally. Stdio is fine for personal tooling.

Debugging MCP connections

When a server does not appear in the Composer tool list, three things usually went wrong: the command is not on PATH, the env variable is missing or wrong, or the JSON is malformed.

Launch Cursor from the terminal with the debug flag:

cursor --mcp-debug

The developer console now prints every MCP handshake, including errors from the child process. Watch the output when you open a Composer. Most failures are one-line fixes: a typo in the token, a missing trailing arg, or a server package that needs a prior npm install.

You can also tail the Cursor log file directly. On macOS it sits at ~/Library/Application Support/Cursor/logs/.

MCP vs @Docs

@Docs is the older feature where you point Cursor at a documentation URL and it indexes the pages for reference. The two features look similar but serve different jobs.

Use @Docs when you want the model to read a library's API reference before it writes code. It is passive: the model fetches pages, but it never acts.

Use MCP when you want the model to take an action against live data. Reading your actual Postgres schema at the moment of the query is different from reading the Postgres docs in general.

In practice: keep @Docs for internal design systems and stable SDK references, use MCP for anything that needs real-time data.

Security and permissions

MCP servers run with the full permissions of whatever token you give them. A GitHub server with a write-scoped PAT can force-push. A Postgres server with a superuser role can drop tables. Cursor does not sandbox these calls beyond the boundaries the server itself enforces.

Rules that keep teams out of trouble:

• Give each server the smallest token scope that works. Read-only Postgres roles, repo:status GitHub tokens when you only need to read CI.
• Never commit mcp.json with secrets. Use env variable references and keep a .env file gitignored, or put secrets in ~/.cursor/mcp.json which is personal by default.
• Treat project .cursor/mcp.json as shared infrastructure. If you commit it, everyone on the team gets those servers on their next pull.
• For production databases, proxy through a read replica or a query-scoped user. Do not point the Postgres MCP server at primary.

The underlying principle: MCP gives the AI agent real hands. Configure it like you would configure any other system with real hands.

A setup checklist for the first hour

A short ordered list to get from zero to a working Composer with tools:

1. Open Settings and toggle Enable MCP servers in Features.
2. Create .cursor/mcp.json at the workspace root.
3. Add the GitHub server with a personal access token scoped to your repos.
4. Add the filesystem server pointing at one extra directory you care about.
5. Restart Composer and confirm the tools appear in the picker.
6. Run a test prompt like read the last five merged PRs and summarise them.
7. If nothing happens, launch Cursor from the terminal with the mcp-debug flag.

That full loop takes about 20 minutes for someone who has never touched MCP before.

Where to go next

Start with one server, usually GitHub or Postgres depending on your day job. Add others as the friction shows up. Within a week most Cursor users end up with three or four servers that map to their actual workflow, and the value of MCP becomes obvious once Composer is doing the boring parts of your dev loop on its own.