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

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.

{
  "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.

{
  "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:

{
  "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:

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.

{
  "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.

Sources

1. Model Context Protocol (MCP), Cursor documentation
2. MCP in the Cursor CLI, Cursor documentation