RFC: GraphQL Support for Chrome DevTools MCP

[natorion]

Is your feature request related to a problem? Please describe.

This is an Request For Comments issue. This is a proposal that we would like to get feedback on, before proceeding with implementation. Please add your thoughts and upvotes.

The current MCP interaction model creates a "chatty" and observation-heavy protocol. While the CLI wrapper (#797) successfully addresses Action Batching by allowing agents to execute sequences of commands in a single bash script, agents still face a bottleneck in Data Orchestration.

To diagnose a failure or gather context, an agent currently must perform multiple "Read" calls—such as list_console_messages, list_network_requests, and take_snapshot. This leads to:

Over-fetching: Agents receive massive JSON blobs with irrelevant metadata, consuming excessive context window tokens.

Observation Latency: Multiple round-trips are required to assemble a complete picture of the browser state.

Disjointed Relationships: Agents must manually "join" related data, such as connecting a console error to the specific network request that triggered it.

Describe the solution you'd like

I would like to discuss the introduction of a query_devtools tool that provides a GraphQL interface to the browser state.

This tool would allow agents to act as "frontends," performing high-density, single-turn data fetches where they "cherry-pick" only the exact attributes needed from multiple sources like console and network data.

Example agent-authored query:

{
  currentPage {
    url
    # Only get errors, and only get the message + stack
    consoleLogs(level: "error") {
      message
      stackTrace
    }
    # Link network failures to their specific response codes
    networkRequests(filter: "failed") {
      url
      status
      method
    }
  }
}

Key Benefits:

• Token Efficiency: Agents can request specific fields, preventing "token explosion" from large, unoptimized resource reads.
• Relational Depth: The schema would allow agents to "walk" the graph—for instance, fetching the initiator script source of a failed network request in the same call as the request itself.
• Self-Healing Documentation: Agents can use GraphQL introspection to discover the schema, similar to how they use --help for the CLI, reducing hallucinations regarding available data fields.

Describe alternatives you've considered

MCP Resources: While the standard MCP Resource spec is excellent for fetching specific "file-like" resources, it lacks the ability to filter fields or join multiple data types in a single request, which can lead to the "chatty" behavior we are trying to solve.

Extended CLI Flags: We could add more complex flags to CLI commands (e.g., chrome-devtools list_network_requests --include-console-errors), but this would lead to a bloated interface that is harder for agents to learn and maintain compared to a typed schema.

Status Quo (Single Tool Calls): Continuing to rely on granular tool calls keeps the protocol simple but keeps latency high and limits the "advanced mode" capabilities of the most capable agents.

Additional context

Relationship to the CLI Wrapper

The GraphQL tool is the "Observation" counterpart to the CLI's "Action".

The CLI (): Allows agents to write logic-heavy scripts to perform tasks, such as retrying a form submission if a username is taken.

The GraphQL Tool (query_devtools): Allows agents to gather the specific, multi-domain data needed to write those scripts or to debug them when they fail, all in one trip.

Together, they transform the agent from a "remote controller" clicking one button at a time into a "script writer" capable of high-level browser orchestration.

[yaonyan]

hi @natorion
great idea! this approach definitely saves tokens and reduces latency by retrieving only the most relevant context.

however, it does introduce a few trade-offs:

• complexity: (minor concern) it adds some implementation complexity.
• input context inflation: by reducing the output (context), we unintentionally increase the input size:
  • query syntax: the query itself makes the tool input more verbose.
  • tool definition overhead: to ensure the ai knows how to construct valid queries, we have to include a detailed schema (keys, filters) in the tool description. this bloats the tool definition passed to the model.

that said, i think in general, the graphql approach is more token efficient.

maybe we can start with a minimal schema (only essential filters) to keep the tool description lean, and run a quick benchmark to verify the net token savings?

[yaonyan]

one more point to consider:

multi-turn tool calling involves dynamic decision-making, which allows the model to avoid logical detours.

debugging is often exploratory. with multi-turn calls, the model can inspect an intermediate result and "prune" irrelevant paths immediately.

graphql requires predicting the data needs upfront. if the model has to "guess" the relationship or defensively over-fetch data to be safe, it might not actually be more token-efficient than the precise, step-by-step approach.

[WebCloud]

I see the points on the original draft as to avoid excessive use of CLI flags, but I see a similar concern to @yaonyan.

Considering that LLMs lack domain specific knowledge, I'd expect bias or course corrections to end up consuming more tokens in a session in total than a regular and more 'tabular' retrieval.

Filtering and pagination with pre-curated queries allows for a richer parsing and analysis process that can help reveal root-cause much faster.

I've built a custom CLI tool to give querying powers, included with a 'forensics' skill to debug very complex problems and help getting that initial analysis, using filters and pagination to avoid context bloat.

I'm not saying it's perfect, but it's quite good.

The true power is when you connect the CLI to a good Skill in a workflow. Since the biggest difference maker is still who's prompting and how they are prompting. So I'd say having a chrome-devtools skill being available with this future version would be someting to look into.