Home › Learn › Add an MCP server to Cursor

Add an MCP server to Cursor

Updated 2026-09-23

Cursor reads MCP servers from a JSON file named mcp.json, and also installs servers from its Customize page and marketplace. This article covers the file-based route, which is what a server's README usually gives you. Everything here comes from the Cursor MCP documentation as read on 2026-09-23; the page at cursor.com/docs/context/mcp redirects to cursor.com/docs/mcp.

Two file locations

Project: .cursor/mcp.json in the project root, for tools specific to that repository.
Global: ~/.cursor/mcp.json in your home directory, for tools available everywhere.

Both files use the same shape: a top-level mcpServers object whose keys are server names.

Transports Cursor supports

The docs list three: stdio (a local process Cursor manages, single user, configured with a shell command), SSE and Streamable HTTP (a URL, deployable as a shared server, with OAuth as the auth option). Cursor supports tools, prompts, resources, roots, elicitation, and the MCP Apps extension.

stdio (local command) entries

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

A Python server looks the same with "command": "python" and "args": ["mcp-server.py"]. The field reference on the page lists:

Field	Required	Meaning
`type`	yes	connection type, `"stdio"`
`command`	yes	executable to start; must be on `PATH` or given as a full path (`npx`, `node`, `python`, `docker`)
`args`	no	array of arguments
`env`	no	environment variables for the server
`envFile`	no	path to a `.env` file with more variables, e.g. `"${workspaceFolder}/.env"`

Note that the page's own examples omit type; the table marks it required. Adding "type": "stdio" is harmless and matches the table. envFile is stdio-only; remote entries cannot use it.

Remote (HTTP or SSE) entries

{
  "mcpServers": {
    "server-name": {
      "url": "http://localhost:3000/mcp",
      "headers": {
        "API_KEY": "value"
      }
    }
  }
}

The comment on the doc's example reads "MCP server using HTTP or SSE - runs on a server". There is no separate transport field in the remote example; Cursor is given the URL and the headers to send.

Keeping secrets out of the file

Cursor resolves variables in command, args, env, url and headers:

${env:NAME}: an environment variable
${userHome}: your home folder
${workspaceFolder}: the project root (the folder that contains .cursor/mcp.json)
${workspaceFolderBasename}: the project root's name
${pathSeparator} or ${/}: the OS path separator

{
  "mcpServers": {
    "remote-server": {
      "url": "https://api.example.com/mcp",
      "headers": {
        "Authorization": "Bearer ${env:MY_SERVICE_TOKEN}"
      }
    }
  }
}

This is the pattern to use in a committed .cursor/mcp.json: the file names the variable, each developer sets it in their shell profile or system environment, and no token lands in git.

OAuth for remote servers

Cursor supports OAuth for servers that require it. When a provider hands you a fixed client ID, requires a whitelisted redirect URL, or does not support Dynamic Client Registration, add an auth object to the remote entry:

{
  "mcpServers": {
    "oauth-server": {
      "url": "https://api.example.com/mcp",
      "auth": {
        "CLIENT_ID": "your-oauth-client-id",
        "CLIENT_SECRET": "your-client-secret",
        "scopes": ["read", "write"]
      }
    }
  }
}

CLIENT_ID is required; CLIENT_SECRET and scopes are optional, and if scopes is omitted Cursor discovers scopes_supported from /.well-known/oauth-authorization-server. auth values accept the same ${env:...} interpolation, which the docs recommend over hardcoding. Cursor's redirect URLs are fixed: https://www.cursor.com/agents/mcp/oauth/callback for web and Cursor Agents, and http://localhost:8787/callback for the desktop app; register both with the provider if people sign in from both surfaces.

After you save the file

Cursor picks up the servers and lists their tools under Available Tools in chat. By default it asks for approval before running an MCP tool; clicking the arrow next to the tool name shows the arguments. You can toggle a server on or off from Customize in the sidebar without deleting its entry.

To debug a server that will not connect, open the Output panel (Cmd+Shift+U on macOS, Ctrl+Shift+U elsewhere) and choose "MCP Logs" from the dropdown; it shows initialization, tool calls and errors. For npm-based servers that seem stuck on an old version, the docs suggest removing the server, running npm cache clean --force, and re-adding it.

Security notes from the same page

Cursor's own guidance is short and worth repeating: install only from developers and repositories you trust, check what data and APIs a server reaches, use restricted API keys with minimal permissions, and review the source for critical integrations. For sensitive data it suggests running servers locally over stdio and considering isolated environments. Enterprise admins can additionally enforce an MCP allowlist by command pattern or URL pattern, restrict which tools may run automatically, and set per-server network modes for local servers.

Where mcpnav fits

The Connect block on each mcpnav server page emits a mcpServers JSON snippet generated from the Registry's packages and remotes fields; paste it into .cursor/mcp.json and replace the <YOUR_VALUE> placeholders with ${env:...} references.

Sources

Cursor documentation, "Model Context Protocol (MCP)": https://cursor.com/docs/mcp (accessed 2026-09-23; https://cursor.com/docs/context/mcp redirects here)

Sources

https://cursor.com/docs/mcp