# How autoConnect Works with Chrome 144+ for Multi-Session Testing in chrome-devtools-mcp

> Discover how autoConnect in chrome-devtools-mcp facilitates multi-session testing with Chrome 144+ by attaching to existing instances via remote debugging. Boost your parallel testing efficiency.

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

---

**The `autoConnect` feature in `chrome-devtools-mcp` attaches to existing Chrome instances via remote debugging instead of launching new browsers, enabling parallel multi-session testing by reading the `DevToolsActivePort` file from distinct user data directories.**

The `chrome-devtools-mcp` repository provides a Model Context Protocol (MCP) server for controlling Chrome via the DevTools Protocol. When testing multiple independent browser sessions simultaneously—such as running parallel test suites with different user profiles or Chrome channels—the `autoConnect` mechanism allows the server to attach to already-running Chrome 144+ instances rather than spawning new processes.

## Understanding the autoConnect Flow

The implementation spans three core files that handle argument parsing, connection strategy selection, and the actual browser attachment logic.

### CLI Flag Configuration

The `--auto-connect` flag is defined in [`src/cli.ts`](https://github.com/ChromeDevTools/chrome-devtools-mcp/blob/main/src/cli.ts) at lines 11-18, where it is parsed alongside other server options. When present, this boolean flag signals that the server should attempt to connect to an existing Chrome instance rather than launch a new one.

### Launch vs. Connect Decision

In [`src/main.ts`](https://github.com/ChromeDevTools/chrome-devtools-mcp/blob/main/src/main.ts) at lines 89-96, the server uses a ternary expression to decide between launching fresh Chrome (`ensureBrowserLaunched`) or connecting to existing Chrome (`ensureBrowserConnected`). Critically, the `channel` argument is only passed when `autoConnect` is true, as the channel determines which Chrome binary's profile directory to inspect.

### Browser Connection Logic

The `ensureBrowserConnected` function in [`src/browser.ts`](https://github.com/ChromeDevTools/chrome-devtools-mcp/blob/main/src/browser.ts) (lines 70-96) implements the actual connection mechanism:

- If an explicit `wsEndpoint` or `browserURL` is provided, it connects directly using those values.
- Otherwise, it locates the `DevToolsActivePort` file within the specified `userDataDir` (or the default profile directory for the selected channel).
- This file contains the remote debugging port and WebSocket path that Puppeteer uses to attach to Chrome.
- If the file cannot be read—indicating Chrome isn't running with remote debugging enabled—the function throws an informative error.

## Multi-Session Testing with Chrome 144+

Multi-session testing requires running multiple Chrome instances with isolated user data directories, each exposing a unique remote debugging port. The `autoConnect` feature enables the MCP server to attach to these specific instances by reading their respective `DevToolsActivePort` files.

To achieve parallel sessions:

1. Launch multiple Chrome instances, each with a distinct `--user-data-dir` and `--remote-debugging-port`.
2. Start separate MCP server processes, each configured with `--auto-connect` and pointing to the corresponding user data directory.
3. Each server attaches to its designated Chrome instance, enabling independent control for concurrent test execution.

### Multi-Session Example

```bash

# Start two Chrome instances with separate profiles

chrome --remote-debugging-port=9222 \
       --user-data-dir=/tmp/chrome-profile-1 &
chrome --remote-debugging-port=9223 \
       --user-data-dir=/tmp/chrome-profile-2 &

# Launch two MCP servers that auto-connect to each Chrome

npx chrome-devtools-mcp@latest --auto-connect \
    --user-data-dir=/tmp/chrome-profile-1 &
npx chrome-devtools-mcp@latest --auto-connect \
    --user-data-dir=/tmp/chrome-profile-2 &

```

Each MCP server now controls its own Chrome process, allowing independent test suites to run in parallel without session interference.

## Practical Implementation Examples

### CLI Usage

Enable auto-connect from the command line using the `--auto-connect` flag combined with channel and user data directory specifications:

```bash
npx chrome-devtools-mcp@latest --auto-connect \
    --channel=beta \
    --user-data-dir=/tmp/chrome-beta-profile

```

- `--auto-connect` instructs the server to attach rather than launch.
- `--channel=beta` specifies the Chrome channel to locate the profile directory (only relevant when auto-connecting).
- `--user-data-dir` points to the profile directory containing the `DevToolsActivePort` file.

### Programmatic API Usage

For Node.js applications, import the argument parser and browser connection functions directly:

```typescript
import {parseArguments} from './src/cli.js';
import {ensureBrowserConnected} from './src/browser.js';
import {puppeteer} from './src/third_party/index.js';

const args = parseArguments('0.17.1', [
  'node', 'main.js',
  '--auto-connect',
  '--user-data-dir=/tmp/chrome-profile',
]);

if (args.autoConnect) {
  const browser = await ensureBrowserConnected({
    channel: args.channel,           // only passed when autoConnect is true
    userDataDir: args.userDataDir,
    devtools: false,
  });
  // `browser` is a Puppeteer Browser attached to the existing Chrome.
}

```

This pattern allows custom orchestration logic for complex multi-session testing scenarios.

### WebSocket Endpoint Connection

Instead of relying on the `DevToolsActivePort` file discovery, you can connect directly to a specific WebSocket endpoint:

```bash
npx chrome-devtools-mcp@latest \
    --wsEndpoint=ws://127.0.0.1:9223/devtools/browser/abcd1234 \
    --auto-connect

```

When `wsEndpoint` is provided, `ensureBrowserConnected` in [`src/browser.ts`](https://github.com/ChromeDevTools/chrome-devtools-mcp/blob/main/src/browser.ts) skips the profile directory inspection and connects directly to the specified URL.

## Summary

- **`autoConnect` enables attachment to existing Chrome instances** rather than launching new browsers, defined in [`src/cli.ts`](https://github.com/ChromeDevTools/chrome-devtools-mcp/blob/main/src/cli.ts) and implemented in [`src/browser.ts`](https://github.com/ChromeDevTools/chrome-devtools-mcp/blob/main/src/browser.ts).
- **Multi-session testing requires isolated user data directories**, with each Chrome instance writing a `DevToolsActivePort` file that the server reads to establish the connection.
- **The `channel` argument is only relevant when auto-connecting**, as it determines which Chrome binary's default profile directory to inspect when `userDataDir` is not explicitly provided.
- **Direct WebSocket endpoints can bypass file discovery**, allowing connection to Chrome instances running in containers or remote environments.

## Frequently Asked Questions

### What is the DevToolsActivePort file and where is it located?

The `DevToolsActivePort` file is a text file generated by Chrome when running with remote debugging enabled. It contains the port number and WebSocket path needed to connect to the browser. The file is located inside the Chrome profile directory specified by `--user-data-dir`, typically at `Default/DevToolsActivePort` within that directory. If you do not specify a custom user data directory, the server uses the default profile path for the selected Chrome channel.

### Why does autoConnect require the channel argument while normal launch does not?

When `autoConnect` is true, the server must locate the `DevToolsActivePort` file to determine how to connect to the running Chrome instance. If you do not explicitly provide a `userDataDir`, the server needs to know which Chrome channel (`stable`, `beta`, `dev`, or `canary`) you are using so it can inspect the default profile directory for that specific binary. In contrast, when launching Chrome normally, the server controls the launch parameters and does not need to search for an existing profile's debug port.

### Can I use autoConnect with Chrome running in a Docker container?

Yes, you can use `autoConnect` with containerized Chrome, but you must ensure the remote debugging port is exposed and accessible from the host. You have two connection options: either map the Chrome profile directory to a host volume so the MCP server can read the `DevToolsActivePort` file, or use the `--wsEndpoint` argument to connect directly to the WebSocket URL exposed by the container (e.g., `ws://container-host:9222/devtools/browser/...`). The direct WebSocket approach is often more reliable for containerized environments where file system sharing may be problematic.

### How do I troubleshoot when autoConnect fails to find the Chrome instance?

If `autoConnect` fails, the error typically indicates that the `DevToolsActivePort` file cannot be read. First, verify that Chrome is actually running with remote debugging enabled by checking for the `--remote-debugging-port` flag in the process list. Second, confirm that the `--user-data-dir` path provided to the MCP server matches the directory used by the running Chrome instance. Third, check file permissions to ensure the server can read the profile directory. If Chrome is running but the file is missing, the browser may not have fully initialized yet; add a short delay before starting the MCP server to allow Chrome to write the port file.