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

Experimental features in the Chrome DevTools MCP server are gated through command-line flags defined in src/cli.ts and filtered during the registerTool execution in 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 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 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 at lines 12-13:

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

The Interop tool get_tab_id declares experimentalInteropTools as a condition in src/tools/pages.ts at lines 58-59:

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 (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 lines 73-84 demonstrates this logic:

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, defaulting to false.
• Tools declare their experimental requirements through the annotations.conditions array in their tool definitions.
• The registerTool function in 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 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 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 (lines 12-13), while the get_tab_id interop tool declares experimentalInteropTools in 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.

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