How to Troubleshoot MCP Connection Issues in Chrome DevTools MCP

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 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, 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 (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 requires full protocol specifications.

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

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:

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:

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:

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 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:

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:

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 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:

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

{
  "mcpServers": {
    "instagit": {
      "command": "npx",
      "args": ["-y", "instagit@latest"]
    }
  }
}