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

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

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

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:

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:

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 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 and implemented in 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.

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