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

# Configuration

> Flags, environment variables and diagnostics

Every flag has a matching `BROWSER_TOOLS_*` environment variable, so you can configure the server whether your MCP client lets you pass arguments or only environment.

***

## Flags

| Flag                      | Environment variable           | Purpose                                                |
| ------------------------- | ------------------------------ | ------------------------------------------------------ |
| `--port <n>`              | `BROWSER_TOOLS_PORT`           | Connector port the extension talks to (default `3025`) |
| `--host <addr>`           | `BROWSER_TOOLS_HOST`           | Loopback address to bind (default `127.0.0.1`)         |
| `--screenshot-dir <path>` | `BROWSER_TOOLS_SCREENSHOT_DIR` | Where screenshots are written                          |
| `--only <a,b>`            | `BROWSER_TOOLS_TOOLS`          | Expose only these tools                                |
| `--exclude <a,b>`         | `BROWSER_TOOLS_EXCLUDE_TOOLS`  | Hide these tools                                       |
| `--connect <url>`         | —                              | Attach to a connector already running elsewhere        |
| `--token <t>`             | `BROWSER_TOOLS_TOKEN`          | Auth token to use with `--connect`                     |
| `--verbose`               | `BROWSER_TOOLS_VERBOSE`        | Print each captured entry as it arrives                |
| `--no-redact`             | `BROWSER_TOOLS_REDACT=false`   | Disable credential scrubbing (not recommended)         |
| `--doctor`                | —                              | Check the setup and exit                               |
| `--version`, `--help`     | —                              | Print and exit                                         |

`BROWSER_TOOLS_STATE_DIR` and `BROWSER_TOOLS_LOG_LEVEL` are also honoured.

Passing them through an MCP client config looks like this:

```json theme={null}
{
  "mcpServers": {
    "browser-tools": {
      "command": "npx",
      "args": [
        "-y",
        "@agentdeskai/browser-tools-mcp@latest",
        "--port", "3030",
        "--screenshot-dir", "./screenshots"
      ]
    }
  }
}
```

<Info>
  A relative `--screenshot-dir` resolves against the working directory your MCP
  client launched the server in, which is not always your project. Use an
  absolute path if you are not sure.
</Info>

***

## Diagnostics

### `--doctor`

The first thing to run when something is not working:

```bash theme={null}
npx @agentdeskai/browser-tools-mcp --doctor
```

It reports your Node version, whether the connector started, whether the extension is connected, whether the screenshot directory is writable, and which browser audits will use — with a suggested fix for each problem it finds, then exits.

### `--verbose`

Watch capture happen as it arrives, which is the fastest way to confirm a fresh install is really working:

```bash theme={null}
npx @agentdeskai/browser-tools-mcp --verbose
```

```
· console error tab 42 Uncaught TypeError: total is not a function
· network 500 POST tab 42 https://myapp.local/api/pay (1310ms)
```

Output goes to stderr, so it is safe to enable on the MCP server without corrupting the JSON-RPC stream, and values are printed **after** redaction.

Without it the connector reports only connect and disconnect, so a working capture and a silent one look identical.

***

## Sharing one browser session

By default the MCP server runs its own connector, which is all you need. If you want several MCP clients — say Cursor and Claude Code at once — reading the same browser session, start the connector once:

```bash theme={null}
npx @agentdeskai/browser-tools-server
```

Every client then attaches to it automatically. To attach explicitly, or to reach a connector on a non-default port:

```bash theme={null}
npx @agentdeskai/browser-tools-mcp --connect http://127.0.0.1:3025 --token <token>
```

The connector publishes its port and token to `~/.browser-tools-mcp/session.json`, written owner-only (`0600`), so an MCP process started separately can attach without probing anything. Override the location with `BROWSER_TOOLS_STATE_DIR`.

<Info>
  If port 3025 is taken, the connector picks the next free port in the 3025–3035
  range and the extension discovers it. You do not normally need to set `--port`.
</Info>

***

## The extension panel

A few settings live in the browser rather than on the command line, because they control what the extension captures before anything is sent. Open DevTools and select the **BrowserTools** panel:

| Setting                           | What it controls                                        |
| --------------------------------- | ------------------------------------------------------- |
| Host and port                     | Which connector to talk to, plus a **Reconnect** button |
| Capture console / network         | Whether each kind of telemetry is captured at all       |
| Capture response bodies           | Whether response payloads are included                  |
| Show request / response headers   | Off by default, independently per direction             |
| Capture mode                      | DevTools protocol, or wrapping the page console         |
| Enable cookie access              | Grants the optional `cookies` permission                |
| Log, query and string size limits | How much is retained and how much any one value can be  |

### Capture modes

**DevTools protocol** is richer, and is the default. It makes Chrome display a "started debugging this browser" banner.

**Wrap page console** replaces the page's console methods instead. No banner, and it is the mode that works in Firefox — at the cost of missing some browser-generated messages the protocol would report.

<Info>
  Headers are off by default in both directions, and storage values are withheld
  unless a tool asks for them. See [privacy & security](/security).
</Info>