# How to Troubleshoot MCP Connection Issues in Chrome DevTools MCP

> Resolve Chrome DevTools MCP connection issues by troubleshooting invalid CLI arguments, remote debugging errors, and sandbox restrictions. Verify URLs and adjust launch flags for a stable connection.

- Repository: [ChromeDevTools/chrome-devtools-mcp](https://github.com/chromedevtools/chrome-devtools-mcp)
- Tags: how-to-guide
- Published: 2026-02-16

---

**Common MCP connection issues stem from invalid CLI arguments, remote debugging configuration errors, or sandbox restrictions, and can be resolved by verifying browser URLs, enabling remote debugging ports, and adjusting launch flags.**

The Chrome DevTools MCP (Model Context Protocol) server enables AI assistants to control Chrome via Puppeteer, but connection failures often occur when bridging the MCP server to a Chrome instance. Understanding how the connection layer works in [`src/browser.ts`](https://github.com/ChromeDevTools/chrome-devtools-mcp/blob/main/src/browser.ts) is essential for diagnosing these MCP connection issues effectively.

## Understanding the MCP Connection Architecture

### The Connection Layer in src/browser.ts

The core connection logic resides in [`src/browser.ts`](https://github.com/ChromeDevTools/chrome-devtools-mcp/blob/main/src/browser.ts), specifically within the `ensureBrowserConnected` function (lines 46-98). This function attempts to connect to an existing Chrome instance through multiple fallback mechanisms:

- **WebSocket Endpoint**: Connects via `wsEndpoint` using `connectOptions.browserWSEndpoint`
- **Browser URL**: Falls back to `browserURL` for HTTP-based remote debugging
- **User Data Directory**: Reads `DevToolsActivePort` from a custom user-data-dir to discover the debugging port

If all connection attempts fail, the system falls back to the `launch` function (lines 51-96) to spawn a fresh Chrome instance with specified arguments, viewport settings, and headless mode configuration.

### CLI Argument Parsing in src/cli.ts

The command-line interface in [`src/cli.ts`](https://github.com/ChromeDevTools/chrome-devtools-mcp/blob/main/src/cli.ts) (lines 24-66) defines the flags that control connection behavior:

- `--browserUrl`: Validates full HTTP URLs for remote debugging
- `--wsEndpoint`: Validates WebSocket endpoints (`ws://` or `wss://`)
- `--wsHeaders`: Parses JSON authentication headers for WebSocket connections
- `--autoConnect`: Enables automatic connection to existing Chrome instances (Chrome 144+)
- `--userDataDir`: Specifies custom Chrome profile directories

## Common MCP Connection Issues and Solutions

### Invalid Browser URLs or WebSocket Endpoints

Connection failures often occur when CLI arguments contain malformed URLs. The validation logic in [`src/cli.ts`](https://github.com/ChromeDevTools/chrome-devtools-mcp/blob/main/src/cli.ts) requires full protocol specifications.

**Solution**: Verify that `--browserUrl` uses `http://` or `https://` and `--wsEndpoint` uses `ws://` or `wss://`.

```bash
npx chrome-devtools-mcp@latest --browserUrl http://127.0.0.1:9222

```

### Remote Debugging Port Not Enabled

If Chrome is not started with the `--remote-debugging-port` flag, the MCP server cannot establish a connection.

**Solution**: Launch Chrome with remote debugging enabled:

```bash
google-chrome --remote-debugging-port=9222

```

Verify the port is accessible by opening `chrome://inspect/#remote-debugging` in Chrome.

### DevToolsActivePort File Missing or Corrupted

When using `--userDataDir`, the `ensureBrowserConnected` function expects a `DevToolsActivePort` file inside the specified directory. If Chrome crashed or the directory is corrupted, this file may be missing.

**Solution**: Verify that `<userDataDir>/DevToolsActivePort` exists and contains valid port information. If corrupted, clear the user data directory or specify a new one.

### Host Header Validation Errors in VM Environments

Virtual machines or containers connecting to a host Chrome instance often encounter "Host header validation" errors because Chrome rejects requests from non-localhost origins.

**Solution**: Create an SSH tunnel to make the remote Chrome appear local:

```bash
ssh -N -L 127.0.0.1:9222:127.0.0.1:9222 user@host
npx chrome-devtools-mcp@latest --browserUrl http://127.0.0.1:9222

```

### Sandbox and Permission Restrictions

Containerized environments (Docker, Kubernetes) or macOS Seatbelt restrictions often prevent Chrome from creating its own sandbox, resulting in launch failures.

**Solution**: Disable sandboxing via Chrome arguments:

```bash
npx chrome-devtools-mcp@latest \
  --chromeArg='--no-sandbox' \
  --chromeArg='--disable-setuid-sandbox'

```

These arguments are forwarded to Puppeteer's `launch` function in [`src/browser.ts`](https://github.com/ChromeDevTools/chrome-devtools-mcp/blob/main/src/browser.ts) at line 71.

### WSL Environment Challenges

Windows Subsystem for Linux cannot access Windows Chrome binaries directly, and Chrome may not be installed inside WSL.

**Solution**: Install Chrome inside WSL and run with remote debugging:

```bash
wget https://dl.google.com/linux/direct/google-chrome-stable_current_amd64.deb
sudo dpkg -i google-chrome-stable_current_amd64.deb

google-chrome --remote-debugging-port=9222 &
npx chrome-devtools-mcp@latest --browserUrl http://127.0.0.1:9222

```

Alternatively, expose Windows Chrome via `chrome.exe --remote-debugging-port=9222` and forward the port.

## Diagnostic Code Examples

### Connect via WebSocket with Authentication Headers

When connecting to secured Chrome instances, pass custom headers:

```bash
npx chrome-devtools-mcp@latest \
  --wsEndpoint ws://127.0.0.1:9222/devtools/browser/abcd1234 \
  --wsHeaders '{"Authorization":"Bearer my-token"}'

```

The `wsHeaders` JSON is parsed in [`src/cli.ts`](https://github.com/ChromeDevTools/chrome-devtools-mcp/blob/main/src/cli.ts) and passed to `ensureBrowserConnected` as `connectOptions.headers`.

### Auto-Connect to Existing Chrome (Chrome 144+)

For Chrome version 144 and newer, use the auto-connect feature:

```bash
npx chrome-devtools-mcp@latest --autoConnect --channel canary

```

This triggers the `channel` option in `ensureBrowserConnected`, allowing Puppeteer to attach to an existing user-data-dir without specifying a port.

## Summary

- **Verify CLI arguments** using full protocols (`http://`, `ws://`) as validated in [`src/cli.ts`](https://github.com/ChromeDevTools/chrome-devtools-mcp/blob/main/src/cli.ts)
- **Enable remote debugging** on Chrome with `--remote-debugging-port=9222` before starting MCP
- **Check `DevToolsActivePort`** files when using `--userDataDir` to ensure Chrome wrote valid connection data
- **Use SSH tunnels** to bypass Host header validation when connecting from VMs or containers
- **Disable sandboxing** with `--chromeArg='--no-sandbox'` for containerized environments
- **Install Chrome in WSL** or forward Windows ports rather than attempting cross-OS binary access

## Frequently Asked Questions

### Why does MCP fail with "Host header validation" error?

This error occurs when connecting from a virtual machine or remote host to a Chrome instance that rejects non-localhost origins. Chrome's remote debugging protocol validates the Host header for security. To resolve this, create an SSH tunnel that forwards the remote port to localhost, then point MCP at `http://127.0.0.1:9222`.

### How do I fix the "DevToolsActivePort file not found" error?

This error indicates that `ensureBrowserConnected` in [`src/browser.ts`](https://github.com/ChromeDevTools/chrome-devtools-mcp/blob/main/src/browser.ts) cannot find the `DevToolsActivePort` file in your specified `--userDataDir`. This typically happens when Chrome crashed or was not started with remote debugging enabled. Verify that Chrome is running with `--remote-debugging-port`, check that the user data directory path is correct, and ensure the file exists at `<userDataDir>/DevToolsActivePort`.

### Can I use MCP with Chrome running inside Docker or Kubernetes?

Yes, but you must disable Chrome's sandboxing mechanisms because containers typically lack the privileges required to create sandboxes. Pass `--chromeArg='--no-sandbox'` and `--chromeArg='--disable-setuid-sandbox'` when starting MCP. These arguments are forwarded to Puppeteer's launch function in [`src/browser.ts`](https://github.com/ChromeDevTools/chrome-devtools-mcp/blob/main/src/browser.ts) at line 71, allowing Chrome to start without sandbox restrictions.

### What is the difference between --browserUrl and --wsEndpoint?

The `--browserUrl` flag accepts an HTTP URL (e.g., `http://127.0.0.1:9222`) and uses Chrome's HTTP-based remote debugging protocol, handled by the `browserURL` branch in `ensureBrowserConnected`. The `--wsEndpoint` flag accepts a WebSocket URL (e.g., `ws://127.0.0.1:9222/devtools/browser/...`) and establishes a direct WebSocket connection, supporting custom headers via `--wsHeaders`. Use `--browserUrl` for standard connections and `--wsEndpoint` when you need specific WebSocket paths or authentication headers.