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

# Migrating from 1.x

> What changed in 2.0, and what you need to do

<Warning>
  **Upgrade regardless of what else you want from 2.0.** 1.2.x contains a
  critical remote code execution vulnerability. See [privacy & security](/security).
</Warning>

Version 2.0 is a rewrite. This page covers everything you have to change.

***

## You no longer run a second process

1.x needed three processes: the MCP server, a separate `browser-tools-server`, and the extension. Forgetting the middle one was the single most common failure.

2.0 embeds the connector in the MCP server. **Delete any "start the browser tools server" step** from your setup, your scripts and your own docs.

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

`@agentdeskai/browser-tools-server` still exists for the case where several MCP clients share one browser session, but you no longer need it for normal use. See [sharing one browser session](/configuration#sharing-one-browser-session).

***

## Stop pinning `@1.2.0`

Older instructions — including earlier versions of this site — told you to pin `npx @agentdeskai/browser-tools-mcp@1.2.0`. That advice existed to work around clients fetching a stale version, and it is now actively harmful: it pins you to the vulnerable release.

Use `@latest`.

***

## Reinstall the extension

The extension was rewritten. Remove the old one from `chrome://extensions` and load the `chrome-extension` directory again. Old and new are not compatible — the wire protocol, the permissions and the settings all changed.

The extension now requests **fewer** permissions. `<all_urls>` and `tabs` are gone from the default set, and cookie access is optional and granted from the panel.

***

## Node 22.19 or newer

1.x ran on Node 18. Lighthouse 13 and the current toolchain require Node 22.19+. The package now declares `engines`, so an unsupported version fails at install with a clear message instead of at runtime with `fetch is not defined`.

***

## You do not need to select the panel

In 1.x capture only started once you clicked the BrowserTools panel. In 2.0 it starts as soon as DevTools is open. The panel is for settings and status.

***

## Tool changes

| 1.x                                                                                    | 2.0                                                                                                                                                          |
| -------------------------------------------------------------------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------ |
| `getConsoleLogs`, `getConsoleErrors`                                                   | Same names, now take `keywords`, `limit`, `offset`                                                                                                           |
| `getNetworkLogs`, `getNetworkErrors`                                                   | Same names, now take `urlKeywords`, `bodyKeywords`, `limit`, `offset`                                                                                        |
| `takeScreenshot`                                                                       | Now returns the **image itself** plus the saved path, instead of the string "Successfully saved screenshot"                                                  |
| `getSelectedElement`, `wipeLogs`                                                       | Unchanged                                                                                                                                                    |
| `runAccessibilityAudit`, `runPerformanceAudit`, `runSEOAudit`, `runBestPracticesAudit` | Same names; reports are restructured and accept an optional `url`                                                                                            |
| `runDebuggerMode`, `runAuditMode`, `runNextJSAudit`                                    | **Removed as tools.** They returned static text and cost context on every request. They are now MCP *prompts*: `debuggerMode`, `auditMode`, `nextjsSeoAudit` |
| —                                                                                      | New: `getPageInfo`, `getConnectionStatus`, `refreshBrowser`, `getBrowserStorage`, `listBrowserTabs`                                                          |

Every tool now declares an MCP output schema, so results arrive as structured data rather than prose. Read-only tools are annotated `readOnlyHint`, which lets clients auto-approve them. See the [tools reference](/tools).

### Audit report shape

Reports are flatter and consistently shaped across all four categories:

```jsonc theme={null}
{
  "category": "accessibility",
  "score": 72,
  "metadata": { "url": "...", "timestamp": "...", "lighthouseVersion": "13.4.1" },
  "summary": { "failed": 4, "passed": 1, "manual": 1, "informative": 1, "notApplicable": 1 },
  "issues": [
    { "id": "color-contrast", "impact": "critical", "details": { "items": [], "omittedItems": 0 } }
  ],
  "metrics": { }
}
```

`omittedItems` tells you how many detail rows were withheld to keep the payload small. Critical issues are never truncated, and the unabridged report is available at `browser-tools://audit/{reportId}`.

***

## Behaviour changes worth knowing

* **Credentials are redacted.** `Authorization` and `Cookie` headers, JWTs, cloud keys and vendor tokens become `[REDACTED]` before storage. A value reading `[REDACTED]` is this tool protecting you, not your app misbehaving. `--no-redact` disables it if you genuinely need raw values.
* **Headers are off by default,** independently for requests and responses.
* **Storage values are withheld** unless you pass `includeValues: true`.
* **Auto-paste into Cursor is gone.** It existed because screenshots could not reach the model; they now do. It was also the mechanism behind the RCE.
* **Newest logs win.** When a response exceeds the character budget, 1.x returned the *oldest* entries and stopped at the first oversized one. 2.0 returns the newest and never lets one large entry hide the rest.
* **Network capture starts when DevTools opens.** Reload the page to capture a full page load.
* **Screenshots are held to a byte budget** and degrade to JPEG, then downscale, rather than blowing past what a model can accept.

***

## Configuration

| 1.x                                          | 2.0                                                       |
| -------------------------------------------- | --------------------------------------------------------- |
| `PORT`                                       | `BROWSER_TOOLS_PORT` or `--port`                          |
| `SERVER_HOST` (defaulted to `0.0.0.0`)       | `BROWSER_TOOLS_HOST` or `--host`, **loopback only**       |
| Screenshot path set from the extension panel | `BROWSER_TOOLS_SCREENSHOT_DIR` or `--screenshot-dir`      |
| —                                            | `--only` / `--exclude` to control which tools are exposed |
| —                                            | `--doctor` to diagnose a broken setup                     |
| —                                            | `--verbose` to watch capture as it happens                |

See [configuration](/configuration) for the full list.

***

## If something is wrong

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

It reports your Node version, whether the connector started, whether the extension is connected, and whether the screenshot directory is writable, with a suggested fix for each problem it finds.