Connect an MCP server to Cursor

Spec: 2026-07-28
Evidence: E1From official docs

Where the configuration lives

Cursor reads MCP servers from a file named mcp.json in two places:

File	Applies to
`.cursor/mcp.json` in the project root	That project only
`~/.cursor/mcp.json` in your home directory	Every project

On Windows, ~ is your user folder, such as C:\Users\you. Cursor’s documentation does not say what happens when both files define a server with the same name, so give servers distinct names.

Both files use the same shape: a mcpServers object with one entry per server.

A local (stdio) server

{
  "mcpServers": {
    "hello-ts": {
      "command": "node",
      "args": ["/absolute/path/to/hello-server/src/server.ts"],
      "env": { "API_KEY": "${env:API_KEY}" }
    }
  }
}

command must be on the system PATH or be a full path. Use absolute paths for script files, or build them from ${workspaceFolder}. The documentation does not say which working directory the server starts in.
env sets variables for the server. envFile can point to a file of variables instead; it only works for stdio servers.

A remote (Streamable HTTP) server

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

The field is url, not baseUrl. Cursor accepts both Streamable HTTP and the deprecated SSE endpoints at this field. Remote servers that use OAuth are signed in by Cursor itself, with dynamic client registration when the server supports it. For a provider that needs a fixed client, the documentation describes an auth object with CLIENT_ID, an optional CLIENT_SECRET and optional scopes.

Keep keys out of the file

Cursor replaces these variables in command, args, env, url and headers:

Variable	Value
`${env:NAME}`	The environment variable `NAME`
`${userHome}`	Your home folder
`${workspaceFolder}`	The project root, the folder that contains `.cursor/mcp.json`
`${workspaceFolderBasename}`	The name of the project root
`${pathSeparator}` or `${/}`	`/` or `\`, depending on the OS

With ${env:API_KEY}, a project file can be committed without the key in it. The variable has to be set in the environment Cursor itself starts with. A variable exported in a terminal profile may not reach an app started from the Dock or Start menu; see environment and PATH.

Tool approval

By default Cursor asks before it runs an MCP tool, and you can expand the call to see its arguments. In Auto-review run mode, tools on your allowlist run without asking.

When a server does not appear

Open the Output panel (Cmd+Shift+U on macOS) and choose MCP Logs from the drop-down. The log shows startup, tool calls and errors.
Run the exact command and args from mcp.json in a terminal. If it exits, the error it prints is the cause. See the stdio checklist.
Test the server on its own with the MCP Inspector. If the Inspector works, the problem is in mcp.json.

On Windows, npx is a batch file, so many guides wrap it in cmd /c. Cursor’s documentation shows plain npx and does not mention this. If npx fails to start, try "command": "cmd" with "args": ["/c", "npx", …].

Sources

Cursor documentation — Model Context Protocol (MCP)accessed 2026-10-29

MCPDev is community documentation. It is not affiliated with the Model Context Protocol project or with the vendors of the clients it covers.