# How to add an MCP server to Cursor

Level 3: Connect AI to your tools · 6 min · Updated 19 November 2026 · Path: Connect MCP servers to your assistant

By the end you'll add MCP servers to Cursor for one project or globally, and check that the agent can use their tools.

You want Cursor's agent to check the database schema before it writes a migration, or to read the design file before it builds the component. Out of the box it can only see your code. An [MCP](https://ai-powered.com/academy/glossary/mcp) server gives it a way to reach the rest, and in Cursor that's one small JSON file.

*Diagram: Adding a server, step by step.* Pick a server you trust, add it to your app (a URL or a command), sign in or restart, then try a small task and approve the first tool call.

## Pick where the file goes

Cursor reads servers from `mcp.json`. Where you put it decides where the servers work:

**One project**

- `.cursor/mcp.json` inside the project.
- Commit it so your team gets the same servers (leave keys out).

**Every project**

- `~/.cursor/mcp.json` in your home folder.
- Good for servers you want everywhere, like documentation lookup.

Both files have the same shape: an `mcpServers` object with one entry per server.

## A remote server

A hosted server needs only its `url`. Add `headers` if it takes an API key:

```json
{
  "mcpServers": {
    "server-name": {
      "url": "https://mcp.example.com/mcp",
      "headers": {
        "API_KEY": "value"
      }
    }
  }
}
```

Cursor supports Streamable HTTP and SSE. If a server uses OAuth and you don't have credentials to paste, Cursor registers itself with the server and opens a sign-in page in your browser.

Here's the entry for Context7, a hosted server for library documentation. The button opens Cursor, which asks you to confirm:

[Context7](https://ai-powered.com/mcp/context7) in Cursor (~/.cursor/mcp.json):

```json
{
  "mcpServers": {
    "context7": {
      "url": "https://mcp.context7.com/mcp"
    }
  }
}
```

## A local server

A local server needs the `command` that starts it and its `args`. Keys go in `env`:

```json
{
  "mcpServers": {
    "server-name": {
      "command": "npx",
      "args": ["-y", "mcp-server"],
      "env": {
        "API_KEY": "value"
      }
    }
  }
}
```

The command must be on your system path, or written as a full path. Here's Microsoft's Playwright server, which lets the agent open and test pages in a browser:

[Playwright MCP](https://ai-powered.com/mcp/playwright-mcp-2) in Cursor (~/.cursor/mcp.json):

```json
{
  "mcpServers": {
    "playwright-mcp": {
      "command": "npx",
      "args": [
        "-y",
        "@playwright/mcp"
      ]
    }
  }
}
```

Already have an `mcp.json`? Add the new entry inside the existing `mcpServers` object.

## Check that it worked

As of 19 November 2026, Cursor's docs say you switch servers on and off from **Customize** in the sidebar. The agent uses a server's tools when they fit the task; they're listed under **Available Tools**, and you can also ask for one by name.

**Try it**

Add Context7, then ask the agent: "Use Context7 to check how this project's version of React handles form actions." Cursor asks before it runs an MCP [tool](https://ai-powered.com/academy/glossary/tool-call); select the arrow next to the tool's name to see exactly what it will send.

If a server doesn't start, open the Output panel (Cmd+Shift+U on macOS) and choose **MCP Logs**.

## Servers worth a look

MCP servers for developer tools from the directory:

- [GitHub](https://ai-powered.com/mcp/github-2): Official MCP server connecting AI assistants to GitHub repos, issues and workflows
- [fastmcp](https://ai-powered.com/mcp/fastmcp): Python framework for building MCP servers, clients and interactive apps
- [Codebase Memory](https://ai-powered.com/mcp/codebase-memory): Local MCP server that builds a code knowledge graph for AI coding agents
- [XERJ](https://ai-powered.com/mcp/xerj): Local search engine for AI agents with cited answers over your code and docs
- [REA](https://ai-powered.com/mcp/rea): CLI and MCP server that lets coding agents reverse engineer apps and binaries

**Watch out**

MCP tools follow the same run modes as terminal commands. Before you let tools run without asking, check those settings, and remember a local server runs on your computer with your permissions. Use `envFile` (local servers only) or environment variables instead of writing keys into a committed `.cursor/mcp.json`.

## Key takeaways

- Project servers: `.cursor/mcp.json`. Everywhere: `~/.cursor/mcp.json`.
- Remote: `url` (+ `headers`). Local: `command`, `args`, `env`.
- Turn servers on and off under **Customize**; read **MCP Logs** when something fails.

## What to try next

- Using VS Code as well? Its file is similar but not the same: see [VS Code](https://ai-powered.com/academy/connect-mcp-servers/vs-code).
- Look up the difference between [local and remote servers](https://ai-powered.com/academy/glossary/remote-vs-local-mcp-server) before you pick one for your team.

## Sources

Official documentation, checked on 19 November 2026:

- [Model Context Protocol (Cursor docs)](https://cursor.com/docs/context/mcp)

Next lesson: [How to add an MCP server to VS Code](https://ai-powered.com/academy/connect-mcp-servers/vs-code)
