# Chrome DevTools MCP Experimental Flags: How They Unlock Advanced Browser Automation

> Unlock advanced browser automation with Chrome DevTools MCP experimental flags. Explore computer vision, debugging, and extension management features for powerful DevTools capabilities.

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

---

**Chrome DevTools MCP experimental flags are boolean CLI options that activate optional tool-sets—such as computer vision, DevTools debugging, and extension management—by filtering tool registration at runtime based on conditions stored in `McpContext`.**

The `chrome-devtools-mcp` repository provides a Model Context Protocol (MCP) server that exposes Chrome browser automation capabilities to AI assistants. By default, the server runs a conservative, stable configuration. However, developers can unlock advanced functionality by enabling **chrome-devtools-mcp experimental flags** at startup. These flags extend the server's surface area without compromising security or performance for users who do not need the extra capabilities.

## What Are Chrome DevTools MCP Experimental Flags?

Experimental flags in `chrome-devtools-mcp` are hidden CLI options defined in [`src/cli.ts`](https://github.com/ChromeDevTools/chrome-devtools-mcp/blob/main/src/cli.ts). Each flag follows the naming convention `--experimental-<name>` (except for `--category-extensions`, which drives a related condition). When parsed, these boolean values are stored in the `McpContext` options object and evaluated during tool registration in [`src/main.ts`](https://github.com/ChromeDevTools/chrome-devtools-mcp/blob/main/src/main.ts).

If a tool's definition includes a `conditions` array in its annotations, the server checks whether the corresponding experimental flag is enabled. When the flag is **off**, the tool is silently omitted from the MCP server’s capability list. When the flag is **on**, the tool is registered and becomes callable by the client.

## Available Experimental Flags in chrome-devtools-mcp

The following CLI flags extend the server's functionality by gating specific tool categories.

### --experimental-devtools (DevTools Target Automation)

The `--experimental-devtools` flag enables automation over DevTools targets via `chrome.debugger`. When activated, the flag is propagated to `McpContext` as `experimentalDevToolsDebugging` and passed to browser launch and connection routines (`ensureBrowserLaunched` and `ensureBrowserConnected`). This allows the MCP server to attach to and control the Chrome DevTools protocol directly for advanced debugging scenarios.

### --experimental-vision (Computer Vision Tools)

Activating `--experimental-vision` unlocks **computer-vision** tools such as image-to-text and OCR. In [`src/main.ts`](https://github.com/ChromeDevTools/chrome-devtools-mcp/blob/main/src/main.ts), tools annotated with the `computerVision` condition are filtered out unless this flag is set to `true`. The filtering logic explicitly checks `tool.annotations.conditions?.includes('computerVision') && !args.experimentalVision` to determine exclusion.

### --experimental-structured-content (Machine-Readable Output)

The `--experimental-structured-content` flag modifies the response format of every tool. When enabled, the server appends a `structuredContent` field containing machine-readable JSON to the standard text response. In [`src/main.ts`](https://github.com/ChromeDevTools/chrome-devtools-mcp/blob/main/src/main.ts) (lines 180-185), the code assigns `result.structuredContent = structuredContent` only when the flag is present, allowing AI clients to parse structured data without regex extraction.

### --experimental-include-all-pages (Extended Page Enumeration)

This flag expands the definition of "pages" to include webviews, background pages, and service workers. Stored in `McpContext` as `experimentalIncludeAllPages`, it is consulted by the page-enumeration logic in [`src/tools/pages.ts`](https://github.com/ChromeDevTools/chrome-devtools-mcp/blob/main/src/tools/pages.ts). When enabled, pagination and listing tools return these additional target types alongside standard tabs.

### --experimental-interop-tools (Inter-Process Interoperability)

The `--experimental-interop-tools` flag exposes Chrome’s internal identifiers, such as tab IDs, to the MCP client. This is guarded in [`src/main.ts`](https://github.com/ChromeDevTools/chrome-devtools-mcp/blob/main/src/main.ts) (lines 174-182) and each tool’s definition lists `experimentalInteropTools` in its `conditions` array. For example, the `get_tab_id` tool in [`src/tools/pages.ts`](https://github.com/ChromeDevTools/chrome-devtools-mcp/blob/main/src/tools/pages.ts) is only registered when this flag is active, allowing external processes to correlate MCP resources with native Chrome identifiers.

### --category-extensions (Extension Management)

While not prefixed with "experimental," `--category-extensions` drives the `experimentalExtensionSupport` condition. When set to `true`, it enables tools for installing, listing, reloading, and uninstalling Chrome extensions. The constant `EXTENSIONS_CONDITION = 'experimentalExtensionSupport'` is defined in [`src/tools/extensions.ts`](https://github.com/ChromeDevTools/chrome-devtools-mcp/blob/main/src/tools/extensions.ts), and the flag defaults to `false` unless explicitly enabled via CLI.

## How Experimental Flags Work Under the Hood

### Flag Definitions in src/cli.ts

All experimental flags are defined as hidden boolean options in [`src/cli.ts`](https://github.com/ChromeDevTools/chrome-devtools-mcp/blob/main/src/cli.ts) (lines 150-175). The `hidden: true` property keeps them from appearing in standard help output while still allowing parsing:

```typescript
experimentalDevtools: {
  type: 'boolean',
  describe: 'Whether to enable automation over DevTools targets',
  hidden: true,
},
experimentalVision: {
  type: 'boolean',
  describe: 'Whether to enable vision tools',
  hidden: true,
},
experimentalStructuredContent: {
  type: 'boolean',
  describe: 'Whether to output structured formatted content.',
  hidden: true,
},

```

### Tool Filtering in src/main.ts

During server initialization, [`src/main.ts`](https://github.com/ChromeDevTools/chrome-devtools-mcp/blob/main/src/main.ts) iterates over tool definitions and applies conditional filtering. If a tool’s `annotations.conditions` array contains a flag name that is not enabled in the CLI arguments, the tool is skipped:

```typescript
if (
  tool.annotations.conditions?.includes('experimentalInteropTools') &&
  !args.experimentalInteropTools
) {
  return;
}

```

This pattern ensures that experimental capabilities are strictly opt-in and cannot be invoked accidentally.

### Conditional Tool Registration

Tools declare their requirements in their definition objects. For example, the `get_tab_id` tool in [`src/tools/pages.ts`](https://github.com/ChromeDevTools/chrome-devtools-mcp/blob/main/src/tools/pages.ts) specifies `experimentalInteropTools` as a condition:

```typescript
export const getTabId = defineTool({
  name: 'get_tab_id',
  description: `Get the tab ID of the page`,
  annotations: {
    category: ToolCategory.NAVIGATION,
    readOnlyHint: true,
    conditions: ['experimentalInteropTools'],
  },
  // …
});

```

Only when `--experimental-interop-tools` is passed to the CLI will this tool appear in the server’s capability list.

## Practical Examples

### Enabling Vision Tools for OCR

To activate computer-vision capabilities such as image-to-text extraction, launch the server with the vision flag:

```bash
npx chrome-devtools-mcp@latest --experimental-vision

```

Once enabled, tools annotated with the `computerVision` condition become available for processing screenshots and DOM images.

### Retrieving Internal Tab IDs

For workflows that require correlating MCP resources with native Chrome identifiers, enable interoperability tools:

```bash
npx chrome-devtools-mcp@latest --experimental-interop-tools

```

This exposes the `get_tab_id` tool, which returns the internal Chrome tab ID for a given page context.

### Consuming Structured Content

To receive machine-readable JSON alongside human-readable text responses, enable structured output:

```bash
npx chrome-devtools-mcp@latest --experimental-structured-content

```

Every tool response will then include a `structuredContent` field containing parsed data, eliminating the need for clients to extract information from text strings.

## Summary

- **Chrome DevTools MCP experimental flags** are hidden CLI options defined in [`src/cli.ts`](https://github.com/ChromeDevTools/chrome-devtools-mcp/blob/main/src/cli.ts) that gate access to advanced browser automation features.
- Each flag is a boolean (e.g., `--experimental-vision`) stored in `McpContext` and evaluated during tool registration in [`src/main.ts`](https://github.com/ChromeDevTools/chrome-devtools-mcp/blob/main/src/main.ts).
- **Conditional filtering** ensures tools only appear when their required flags are enabled, keeping the default server lightweight and secure.
- Key flags include `--experimental-devtools` (DevTools protocol automation), `--experimental-vision` (OCR and image analysis), `--experimental-structured-content` (JSON output), and `--category-extensions` (extension management).

## Frequently Asked Questions

### How do I enable multiple experimental flags simultaneously?

You can pass multiple flags in a single command. Each flag is independent, so combining them expands the available tool-set accordingly:

```bash
npx chrome-devtools-mcp@latest --experimental-vision --experimental-interop-tools --experimental-structured-content

```

### Are experimental flags stable for production use?

Experimental flags are marked as `hidden: true` in [`src/cli.ts`](https://github.com/ChromeDevTools/chrome-devtools-mcp/blob/main/src/cli.ts) and are not part of the stable API contract. They may change behavior, be renamed, or be removed in future releases. Use them for advanced automation workflows, but pin your dependency version and test thoroughly before deploying to production environments.

### What happens if I call a tool without its required experimental flag?

If a tool requires an experimental condition (e.g., `experimentalInteropTools`) and the corresponding flag is not enabled, the tool is never registered with the MCP server. Consequently, the client will receive an error indicating that the tool does not exist, rather than a runtime failure. This design prevents accidental invocation of privileged operations.

### How does --category-extensions relate to experimentalExtensionSupport?

The `--category-extensions` CLI flag is the user-facing switch that enables the `experimentalExtensionSupport` condition internally. Unlike other experimental flags that use the `--experimental-` prefix, this flag uses `--category-extensions` to activate tools for installing, listing, and uninstalling Chrome extensions. When enabled, the constant `EXTENSIONS_CONDITION = 'experimentalExtensionSupport'` defined in [`src/tools/extensions.ts`](https://github.com/ChromeDevTools/chrome-devtools-mcp/blob/main/src/tools/extensions.ts) evaluates to true, registering the extension management tool-set.