# How to add MCP servers to Cursor: mcp.json, OAuth and CLI

> Add any MCP server to Cursor: mcp.json entries for remote and local servers, project and global config, OAuth sign-in, the agent mcp CLI and MCP logs.

Page: https://hallwaytest.ai/learn/add-mcp-server-cursor
Author: Marian Kushnir, Product Manager
Published: November 6, 2026. Last updated: November 9, 2026

**Short answer:** Add an entry under mcpServers in .cursor/mcp.json for one project, or in ~/.cursor/mcp.json for every project. A remote server needs a url and optional headers; a local stdio server needs a command, args and env. Cursor handles OAuth sign-in for remote servers. Enable servers in Customize, and if one fails, read the MCP Logs in the Output panel.

Cursor's agent can use tools from any Model Context Protocol (MCP) server: a browser, a database, design files or your own internal API. Official servers install in one click from the Cursor Marketplace; any other server is one entry in an `mcp.json` file.

## What an MCP server does in Cursor

An MCP server connects Cursor to an external tool or data source and exposes functions the agent can call. Cursor supports three transports:

| Transport | Runs | Connect with | Auth |
| --- | --- | --- | --- |
| `stdio` | Locally, Cursor starts it | A shell command | Manual (keys in `env`) |
| `SSE` | Locally or remotely | URL of an SSE endpoint | OAuth |
| `Streamable HTTP` | Locally or remotely | URL of an HTTP endpoint | OAuth |

## Where the configuration lives

Cursor reads servers from two files with the same format; you can also install and manage servers from the **Customize** page.

| File | Use it for |
| --- | --- |
| `.cursor/mcp.json` in a project | Servers that belong to that project; commit it to share with the team |
| `~/.cursor/mcp.json` in your home directory | Servers you want in every project |

For servers listed in the Cursor Marketplace, click **Add to Cursor** on the entry: Cursor installs it and runs the OAuth sign-in. Everything else goes into `mcp.json`.

## Add a remote server

A remote server needs a `url`, plus `headers` if it uses a static key instead of OAuth.

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

`${env:NAME}` reads the value from your environment, so the key never lands in the file. Cursor resolves variables in `command`, `args`, `env`, `url` and `headers`; others include `${userHome}` and `${workspaceFolder}`, the folder that contains `.cursor/mcp.json`.

## Add a local (stdio) server

A local server needs a `command` that is on your PATH (or a full path), plus optional `args` and `env`.

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

For Python, use `"command": "python"` and the script in `args`. Stdio servers also accept `envFile`, a path such as `"${workspaceFolder}/.env"` to load more variables from.

## Sign in with OAuth

Cursor handles OAuth for remote servers itself, so most servers need only the URL. It uses the authorization code flow with PKCE, finds the server's authorization server from its metadata, and registers itself as a client automatically when the server supports dynamic client registration. The desktop app receives the sign-in on `http://localhost:8787/callback`, so that port has to be free.

If a provider does not support dynamic registration, add static credentials in an `auth` object:

```json
{
  "mcpServers": {
    "oauth-server": {
      "url": "https://api.example.com/mcp",
      "auth": {
        "CLIENT_ID": "${env:MCP_CLIENT_ID}",
        "scopes": ["read", "write"]
      }
    }
  }
}
```

`CLIENT_SECRET` is optional, for providers that use confidential clients. Cloud Agents keep their own sign-ins on Cursor's servers, separate from the ones on your machine.

## Check the server and its tools

Open **Customize** in the sidebar to see the server and switch it on or off. In chat, the agent uses MCP tools listed under **Available Tools** when they are relevant, including in Plan Mode, and you can ask for a tool by name. Cursor asks for approval before running an MCP tool by default.

The Cursor CLI reads the same configuration and gives a quicker check:

```bash
agent mcp list
agent mcp list-tools <identifier>
agent mcp login <identifier>
```

`agent mcp list` shows each server's connection status, source (project or global) and transport, and `list-tools` prints the tools with their parameters.

## Troubleshooting

When a server fails, Cursor shows an error in chat and keeps the other servers running; the details are in the MCP logs.

1. Open the Output panel (Cmd+Shift+U on macOS, Ctrl+Shift+U on Windows and Linux).
2. Select **MCP Logs** in the dropdown.
3. Look for connection errors, authentication problems or crashes.

Common causes:

- **A local server never starts.** The `command` is not on the PATH Cursor sees. Use the full path to the executable.
- **A remote server ignores your `.env`.** `envFile` works only for stdio servers; use `${env:NAME}` and set the variable in your shell profile.
- **An npm server is stuck on an old version.** Remove it in **Customize**, run `npm cache clean --force` and add it again.
- **Changes to a custom server do not show up.** Restart Cursor after updating its files.

## Example: add Hallway Test to Cursor

Hallway Test is a remote MCP server with OAuth, so the entry is only a URL. It lets the agent send a flow it just built to a real person from our in-house team, who runs it while thinking aloud; see [what the usability testing MCP does](https://hallwaytest.ai/usability-testing-mcp).

```json
{
  "mcpServers": {
    "hallwaytest": {
      "url": "https://mcp.hallwaytest.ai/mcp"
    }
  }
}
```

Put it in `~/.cursor/mcp.json` for every project, or commit it in `.cursor/mcp.json` so each teammate signs in with their own account. Start the sign-in from the server's entry in Cursor, or with `agent mcp login hallwaytest`, then sign in with Google and approve the connection. Its tools, among them `create_usability_task`, then show up in Cursor.

A new account can connect right away, but the first request to dispatch a test answers with a link to book the free pilot call. After the 30-minute call we activate the account, with no need to reconnect, and results come back within 24 hours. After public launch a test costs $29. Step-by-step screens are on [Connect Hallway Test to Cursor](https://hallwaytest.ai/connect-cursor).

## Sources

1. [Model Context Protocol (MCP), Cursor documentation](https://cursor.com/docs/mcp)
2. [MCP in the Cursor CLI, Cursor documentation](https://cursor.com/docs/cli/mcp)

## FAQ

**Where is the MCP config file in Cursor?**
There are two: .cursor/mcp.json inside a project for servers that belong to that project, and ~/.cursor/mcp.json in your home directory for servers you want everywhere. Both use the same mcpServers format.

**Do MCP servers in Cursor work in the Cursor CLI too?**
Yes. The CLI uses the same configuration as the editor, so every server in mcp.json is available to the agent CLI. agent mcp list shows them with their connection status.

**How do I keep API keys out of mcp.json?**
Use interpolation: write ${env:NAME} in env, url or headers and set the variable in your shell. For a local stdio server you can also point envFile at a .env file. Remote servers do not support envFile.

**Can I turn off an MCP server without deleting it?**
Yes. Open Customize in the sidebar, find the server and use its toggle. Disabled servers do not load or appear in chat, which also helps when too many tools crowd the agent.

**Does Cursor ask before running an MCP tool?**
By default, yes: Cursor asks for approval before it uses an MCP tool, and you can expand the call to see its arguments. MCP tools follow the same Run Modes as terminal commands.

## Related

- [Home](https://hallwaytest.ai/index.md)
- [Pricing](https://hallwaytest.ai/pricing.md)
- [Book a free pilot](https://hallwaytest.ai/book.md)