MCP

BigQuery MCP server: connect your warehouse to Claude or Codex

TL;DR

BigQuery is where true ROAS gets computed, because it is the one place ad cost and settled revenue can sit in the same table. It is also the family where a write tool is most dangerous, and this page is straightforward about why the general query path refuses to run DML at all.

What already exists for this platform

Google ships an MCP Toolbox for Databases that covers BigQuery, and there are several community servers. Any of them will run a SELECT for you.

  • Reading is a solved problem. A server that runs parameterised SQL against BigQuery is not hard to find or to write.
  • The interesting question is writes, which is where most servers either refuse entirely or expose a bare SQL tool with nothing around it.
  • Cost control matters more here than anywhere else — a careless query against a large partitioned table is a real bill, not just a slow answer.

What a full MCP server adds

Typical option todayAgent Planners MCP
BigQuery toolsUsually one SQL tool4 reads
DML / DDL through the query toolOften allowedRefused — fail-closed by design
Bytes-billed ceilingRarely enforcedEnforced
Joined to ad platformsNo16 other families on one key
Tool counts are derived from the live catalogue rather than typed by hand: this family exposes 4 reads and 0 writes of the 384 tools on the endpoint. A key only sees the writes if it carries `tools:write`.

How to configure it

  1. 1Create a key in API & MCP. `tools:read` for questions; add `tools:write` if the agent should be able to change things. Tools mode needs a paid plan and fails closed.
  2. 2Connect BigQuery under Integrations — that OAuth step is why the MCP key never carries platform credentials.
  3. 3Add the server to Claude Code, Claude Desktop or Codex using the snippet below.
  4. 4Have the agent call `describe_permissions` first — it reports the key's mode, scopes, plan entitlement and connected accounts.
  5. 5Call `list_accounts` for the account ids, and scope each call with one. Resolution is exact or it refuses, naming the candidates.
bash
claude mcp add --transport http agentplanners https://www.agentplanners.com/api/mcp \
  --header "Authorization: Bearer ap_live_…"

Claude Desktop and Codex

Claude Desktop takes the same endpoint as JSON:

json
{
  "mcpServers": {
    "agentplanners": {
      "url": "https://www.agentplanners.com/api/mcp",
      "headers": {
        "Authorization": "Bearer ap_live_…"
      }
    }
  }
}
Codex uses the same endpoint from `~/.codex/config.toml`, with the key in an environment variable rather than the file: `[mcp_servers.agentplanners]` / `url = "…/api/mcp"` / `bearer_token_env_var = "AGENTPLANNERS_API_KEY"`.

Why the query tool refuses to write, and stays that way

The tempting shortcut is to let one SQL tool run whatever it is given. That was tried here and rejected for a specific reason: the query tool is registered as a READ. A `DELETE FROM …` running through it would carry no approval gate, no write budget, no audit row and no cache invalidation — the exact class of ungated write that every other platform's guardrails exist to prevent.

The autonomy guardrails cannot help either. They are built for ad mutations: a change cap, protected campaigns, a monthly spend ceiling. A `DROP TABLE` has no change percentage and no protected campaign, so there is nothing for them to grip. The honest answer was to make the agent path fail closed rather than to ship a write that only looks governed.

A dedicated, approval-gated BigQuery write tool exists separately, carrying the gate, the budget and the audit row that the query path cannot. Reading is unchanged and available to everyone.

Use cases

  • True ROAS — joining ad cost to revenue that actually settled, rather than to platform-reported conversion values.
  • Margin-aware campaign ranking, once COGS is in the warehouse, which is the question no ad platform can answer about itself.
  • Reconciling a platform's numbers against your own, in the same session as the platform that reported them.
  • Feeding a conversion upload from a query result, where the rows are counted and the unusable ones dropped before anything is sent.

Frequently asked questions

Can an AI agent run DELETE or UPDATE on my BigQuery data?
Not through the analytics query tool — it classifies any DML or DDL statement as a write and refuses, asking for a SELECT instead. That refusal is not configurable from the agent surface. A separate, approval-gated write tool exists for cases that genuinely need it.
Is there an official BigQuery MCP server?
Google ships an MCP Toolbox for Databases covering BigQuery, and community servers exist. They handle reading well; the differences show up around writes, cost ceilings and what else is on the same key.
How is query cost controlled?
A maximum-bytes-billed ceiling is enforced on the job, so a careless query against a large partitioned table is rejected rather than silently expensive.
Put a human-approved agent on your ad ops

Start free — 2,500 credits a month, no credit card. Reads are free; every write waits for you.

Related reading