# How Experimental Features Are Managed in the Chrome DevTools MCP Tool Registration System

> Learn how Chrome DevTools MCP manages experimental features using CLI flags and tool annotations for controlled registration and access. Optimize your DevTools experience today.

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

---

**Experimental features in the Chrome DevTools MCP server are gated through command-line flags defined in [`src/cli.ts`](https://github.com/ChromeDevTools/chrome-devtools-mcp/blob/main/src/cli.ts) and filtered during the `registerTool` execution in [`src/main.ts`](https://github.com/ChromeDevTools/chrome-devtools-mcp/blob/main/src/main.ts) based on conditions declared in each tool's annotations.**

The Chrome DevTools MCP server implements a runtime gating system that determines which tools are exposed to clients based on explicit opt-in flags. This architecture, centered in the `chrome-devtools-mcp` repository, allows developers to ship new capabilities without disrupting existing workflows by requiring users to enable experimental features via CLI arguments.

## CLI Flags That Control Experimental Features

The [`src/cli.ts`](https://github.com/ChromeDevTools/chrome-devtools-mcp/blob/main/src/cli.ts) file defines hidden command-line flags that toggle experimental capabilities. These flags default to `false` and must be explicitly enabled.

| Flag | Description | Default | Source Location |
|------|-------------|---------|-----------------|
| `--experimental-devtools` | Enables automation over DevTools targets | `false` (hidden) | `cli.ts:50-54` |
| `--experimental-vision` | Turns on vision-based tools | `false` (hidden) | `cli.ts:55-59` |
| `--experimental-structured-content` | Emits structured JSON in tool responses | `false` (hidden) | `cli.ts:60-64` |
| `--experimental-include-all-pages` | Includes webviews/background pages in page listings | `false` (hidden) | `cli.ts:65-70` |
| `--experimental-interop-tools` | Enables inter-op-tool commands (e.g., tab-ID lookup) | `false` (hidden) | `cli.ts:71-75` |
| `--category-extensions` | Controls registration of the Extensions tool suite | `false` (hidden) | `cli.ts:200-206` |

The parsed arguments are stored in the global `args` object returned by `parseArguments` in [`src/main.ts`](https://github.com/ChromeDevTools/chrome-devtools-mcp/blob/main/src/main.ts) at line 37.

## How Tools Declare Experimental Dependencies

Individual tools specify their experimental requirements through the `annotations.conditions` array in their tool definition. This declarative approach allows the registration system to filter tools dynamically based on the CLI flags provided at startup.

The **Extensions** tools require the condition `experimentalExtensionSupport`, defined in [`src/tools/extensions.ts`](https://github.com/ChromeDevTools/chrome-devtools-mcp/blob/main/src/tools/extensions.ts) at lines 12-13:

```typescript
annotations: {
  conditions: ['experimentalExtensionSupport'],
  // ...
}

```

The **Interop** tool `get_tab_id` declares `experimentalInteropTools` as a condition in [`src/tools/pages.ts`](https://github.com/ChromeDevTools/chrome-devtools-mcp/blob/main/src/tools/pages.ts) at lines 58-59:

```typescript
annotations: {
  conditions: ['experimentalInteropTools'],
  // ...
}

```

Other experimental capabilities, such as computer vision tools, use the same pattern with conditions like `computerVision` that map to specific CLI flags.

## The Registration Gate in main.ts

The central filtering logic resides in the `registerTool` function within [`src/main.ts`](https://github.com/ChromeDevTools/chrome-devtools-mcp/blob/main/src/main.ts) (lines 48-84). This function evaluates each tool against the parsed CLI arguments before exposing it to the MCP client.

The registration process checks two primary constraints:

1. **Category switches**: Tools belonging to specific categories (e.g., Extensions) are omitted if their corresponding category flag is disabled.
2. **Experimental conditions**: The function inspects `tool.annotations.conditions` and skips registration if a required experimental flag is not present in `args`.

The filtering implementation from [`src/main.ts`](https://github.com/ChromeDevTools/chrome-devtools-mcp/blob/main/src/main.ts) lines 73-84 demonstrates this logic:

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

```

Only tools that pass these guards proceed to the `server.registerTool()` call, making them available via the JSON-RPC protocol.

## Runtime Behavior and Client Impact

When the Chrome DevTools MCP server initializes, the experimental flag state determines the final tool manifest exposed to clients. This runtime gating produces distinct behaviors based on configuration:

- **Enabled flags**: Tools with matching experimental conditions are registered and appear in the client's tool list. Clients can invoke these tools through standard MCP JSON-RPC requests.
- **Disabled flags**: Tools requiring unmet experimental conditions are silently omitted during registration. Clients receive "tool not found" errors if they attempt to invoke these capabilities, as the tools never enter the server's exposed manifest.

This architecture ensures backward compatibility while allowing rapid iteration on new features. Developers can introduce breaking changes or unstable APIs behind experimental flags without affecting production workflows, requiring explicit user opt-in through the CLI.

## Summary

- Experimental features in the Chrome DevTools MCP server are controlled via hidden CLI flags defined in [`src/cli.ts`](https://github.com/ChromeDevTools/chrome-devtools-mcp/blob/main/src/cli.ts), defaulting to `false`.
- Tools declare their experimental requirements through the `annotations.conditions` array in their tool definitions.
- The `registerTool` function in [`src/main.ts`](https://github.com/ChromeDevTools/chrome-devtools-mcp/blob/main/src/main.ts) acts as a central gate, filtering tools based on CLI flags and their declared conditions.
- Unregistered tools are invisible to MCP clients, preventing invocation of experimental capabilities without explicit opt-in.
- This system enables safe iteration on new features while maintaining stable default behavior.

## Frequently Asked Questions

### How do I enable experimental DevTools automation tools?

Enable the `--experimental-devtools` flag when starting the server. This exposes tools that interact with DevTools targets, allowing automation over DevTools instances. The flag is defined in [`src/cli.ts`](https://github.com/ChromeDevTools/chrome-devtools-mcp/blob/main/src/cli.ts) at lines 50-54 and defaults to `false`.

### What happens if a client tries to call an experimental tool that hasn't been enabled?

The client receives a "tool not found" error. During server initialization, the `registerTool` function in [`src/main.ts`](https://github.com/ChromeDevTools/chrome-devtools-mcp/blob/main/src/main.ts) skips registration of tools whose `annotations.conditions` require experimental flags that were not provided. Since the tool is never added to the server's manifest, the MCP protocol returns a standard not-found response.

### Where are experimental conditions defined for individual tools?

Experimental conditions are defined in the tool definition files within `src/tools/`. For example, the Extensions tools specify `experimentalExtensionSupport` in [`src/tools/extensions.ts`](https://github.com/ChromeDevTools/chrome-devtools-mcp/blob/main/src/tools/extensions.ts) (lines 12-13), while the `get_tab_id` interop tool declares `experimentalInteropTools` in [`src/tools/pages.ts`](https://github.com/ChromeDevTools/chrome-devtools-mcp/blob/main/src/tools/pages.ts) (lines 58-59). These conditions are checked against CLI flags during registration.

### Can I enable multiple experimental features at once?

Yes. You can combine multiple experimental flags in a single command. For example, to enable both vision tools and structured content output simultaneously, run: `npx chrome-devtools-mcp@latest --experimental-vision --experimental-structured-content`. Each flag independently controls its respective set of tools through the condition-checking logic in [`src/main.ts`](https://github.com/ChromeDevTools/chrome-devtools-mcp/blob/main/src/main.ts).