# Add an MCP Server to Cursor (.cursor/mcp.json)

> Configure a local or remote MCP server in Cursor, global or per project, keep the API key out of git, and verify it with a real tool call.

- Canonical: https://guides-ai.pages.dev/guides/cursor-mcp-servers/
- Plate 08.02 · Topic: Cursor (https://guides-ai.pages.dev/topics/cursor/)
- Published: 06 Sept 2026 · 3 min read
- Source site: guides-ai — https://guides-ai.pages.dev/

MCP gives Cursor's agent tools beyond your repo — a database, an issue tracker, a docs
search. Cursor reads the same `mcpServers` shape you may know from other clients, from one
of two files.

## 1. Global or project

- `~/.cursor/mcp.json` — available in every project you open.
- `.cursor/mcp.json` — checked into the repo, for tools the whole team needs.

Project config is the better default for anything repo-specific; a teammate who clones gets
it without setup instructions.

## 2. A local server

```json
{
  "mcpServers": {
    "filesystem": {
      "command": "npx",
      "args": ["-y", "@modelcontextprotocol/server-filesystem", "${workspaceFolder}"],
      "env": { "LOG_LEVEL": "info" }
    }
  }
}
```

What it does: launches the server as a child process over stdio. `command` is required;
`args` and `env` are optional. `${workspaceFolder}` expands to the project root — Cursor
also substitutes `${env:NAME}`, `${userHome}`, and `${pathSeparator}` in `command`, `args`,
`env`, `url` and `headers`.

## 3. A remote server

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

What it does: connects over HTTP and sends your token as a header. Because the value is
`${env:...}`, the committed file holds no secret — each developer exports
`COMPANY_MCP_TOKEN` in their own shell. For servers that use OAuth instead, Cursor supports
an `auth` block with `CLIENT_ID`, `CLIENT_SECRET` and `scopes`.

## 4. Enable and verify

Open **Customize** in the sidebar and toggle the server on. Then prove it works by naming a
tool in chat rather than trusting the green dot:

```text
Use the company-api MCP server to list the open incidents, then summarise the top three.
```

What it does: forces a real tool call, so a bad token or wrong URL surfaces immediately as
an error instead of the agent quietly answering from memory. If the server never appears,
check that the JSON parses and that `command` resolves on your `PATH` — on Windows, `npx`
usually needs no change, but a bare script path does.

---

Next: [write a project rule](/guides/cursor-rules-file/), see
[which MCP servers are worth starting with](/guides/best-mcp-servers-to-start/), or generate
the file with the [MCP config generator](/tools/mcp-config/).