---
title: "Cursor MCP setup: add an MCP server"
description: "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."
canonical: "https://scalebrowser.net/docs/agents/mcp-clients/cursor"
last_modified: "2026-09-22T18:16:38.000Z"
---

> ## Documentation Index
> Fetch the complete documentation index at: https://scalebrowser.net/llms.txt
> Use this file to discover all available pages before exploring further.

# 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.

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.

<CardGroup columns={2}>
  <Card title="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.
  </Card>
  <Card title="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](/docs/install#the-api-token).
  </Card>
</CardGroup>

<Warning>

**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.

</Warning>

## 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.

```json .cursor/mcp.json
{
  "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](/docs/agents/mcp-server); what the
agent is **allowed** to do is decided by the daemon, not by the client, so see
[tool profiles](/docs/agents/mcp-server#the-tool-set).