ScalebrowserDOCS

Claude Code and Claude Desktop MCP setup

Add an MCP server to Claude Code with claude mcp add over HTTP, and to the Claude desktop app over stdio, with a local browser server as the example.

Last updated

Claude Code speaks the HTTP transport directly. The Claude desktop app validates only stdio servers in its configuration file, so it takes the daemon's own stdio mode instead.

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.

Claude Code

One command, and the server is registered:

bash
claude mcp add --transport http scalebrowser http://127.0.0.1:8787/v1/mcp \
  --header "Authorization: Bearer $SCALEBROWSER_TOKEN"

It writes to the current project unless you add --scope user. The same entry written by hand, in a project's .mcp.json or in ~/.claude.json, looks like this:

.mcp.jsonjson
{
  "mcpServers": {
    "scalebrowser": {
      "type": "http",
      "url": "http://127.0.0.1:8787/v1/mcp",
      "headers": { "Authorization": "Bearer <token>" }
    }
  }
}

Leaving out type is a silent failure, not a default. Claude Code reads an entry that has a url but no type as a stdio server, skips it, and reports has a "url" but no "type". Write "type": "http".

Check it with claude mcp list; the server should report as connected.

Claude desktop app

Its claude_desktop_config.json validates stdio servers only, so point it at the daemon's own stdio mode. No token appears in this file, because the process resolves it from the data directory you name.

claude_desktop_config.jsonjson
{
  "mcpServers": {
    "scalebrowser": {
      "command": "C:\\Users\\<you>\\AppData\\Local\\Programs\\Scalebrowser\\resources\\daemon\\scalebrowser-daemon.exe",
      "args": ["--mcp-stdio", "--data-dir", "C:\\Users\\<you>\\AppData\\Local\\Scalebrowser"]
    }
  }
}

--data-dir is not optional with the desktop app. Without it the process looks in the daemon's default directory, which is %ProgramData%\Scalebrowser on Windows and is not the one the app uses. What happens next depends on what is in that directory, and neither outcome announces itself: if an earlier standalone run left a runtime.json there, the process finds a daemon on the address it names, attaches to it and answers every call with unauthorized; if the directory is empty, it starts a second daemon that responds normally and knows none of your profiles.

Since 0.9 the process detects both and stops with the directory it expected, the one it found and the command that fixes it. Older builds attach silently.

The app's own values are in Settings → General → Connect an agent, ready to copy: it fills in this exact block with the paths on your machine. The process becomes a relay to the daemon that already owns that data directory rather than a second daemon. See over stdio.

Claude Code inside WSL

The HTTP entry above will not connect from a WSL shell: WSL reaches Windows over its own network adapter, so 127.0.0.1 there is the Linux side, not Windows. Use the stdio entry, with both paths translated. See WSL and containers.

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