Cursor MCP setup: add an MCP server

Add an MCP server to Cursor with mcp.json, for one project or for all: the url and headers entry, where to check it loaded, and the MCP Logs.

Last updated Sep 22, 2026

Cursor reads MCP servers from a JSON file: one per project, or one for everything you open.

The worked example is Scalebrowser's own server, which gives the agent a real browser on your machine. Any other HTTP MCP server takes the same entry with its own address.

Before you start

Everything below assumes a daemon that is already running and a token to reach it with.

Windows desktop app

The app starts the daemon for you. The token is the contents of %LOCALAPPDATA%\Scalebrowser\token, and the address it is listening on is the native_addr field of %LOCALAPPDATA%\Scalebrowser\runtime.json. That is usually 127.0.0.1:8787, but the app moves up a port when something else already holds it.

Self-hosted daemon

scalebrowser-daemon --generate-token prints a token and stores it under <data_dir>/token. The address is whatever bind_addr says, which is 127.0.0.1:8787 unless you changed it. See Install & run.

The token is a full-power credential. It reaches every profile, every stored session and the whole management API. Treat it like a password: keep it out of a repository, and prefer your client's environment-variable syntax over a literal in a config file that gets committed.

Add the server

Two locations, same shape. .cursor/mcp.json in a project applies to that project; ~/.cursor/mcp.json in your home directory applies everywhere. Cursor reads both, and when a server name appears in both, the project entry wins.

.cursor/mcp.jsonjson

{
  "mcpServers": {
    "scalebrowser": {
      "url": "http://127.0.0.1:8787/v1/mcp",
      "headers": {
        "Authorization": "Bearer ${env:SCALEBROWSER_TOKEN}"
      }
    }
  }
}

The ${env:...} form keeps the token out of the file, which matters for the project-scoped copy, because that one sits in your repository. Cursor resolves it from its own environment, so a variable you set after Cursor started is only seen after a restart.

Check that it loaded

Editor: open Customize in the sidebar, then MCPs. Each server has a toggle; turning it off and on again reloads it. The command palette entry Open MCPs gets there directly.
Chat: the tools list at the top of the chat panel shows each tool, and a single tool can be switched off there.
Logs: the Output panel, channel MCP Logs, shows why a server did not connect.
CLI: agent mcp list shows the configured servers and agent mcp list-tools scalebrowser the tools of one.

Cursor speaks stdio, SSE and Streamable HTTP, and a plain http:// address on loopback is fine.

When it does not load

What you see	What to do
`401` in MCP Logs	The variable was empty when Cursor started. Set `SCALEBROWSER_TOKEN`, then restart Cursor rather than only the server.
A connection error in MCP Logs	Nothing answered at that address. Check the daemon runs and that the port matches `native_addr` in `runtime.json`; `curl http://127.0.0.1:8787/health` answers without a token.
The server works but is missing from Customize	Known for multi-root workspaces. The project file still applies; the global file shows reliably.

What the agent can do now

Ask it to open a page and it will lease a profile, bind a tab and start reading. The tool set, the page map and the failure shapes are on MCP server; what the agent is allowed to do is decided by the daemon, not by the client, so see tool profiles.

Run it on your own machine

Seven days to try it with your own agents on your own sites. Starting the trial needs a card.

Get started