MCP tools reference

The Buron MCP server's tools are grouped into six areas. Your editor's agent calls these automatically based on your questions, you don't need to invoke them directly. This reference is useful when you're building custom skills or want to know exactly what's available.

The server registers 27 tools. Summary:

Datasets

You query your data by picking metrics, dimensions, and filters from a dataset — there is no query language to write. Live Google Ads datasets answer ad questions on the free tier; warehouse datasets cover your synced sources (organic search, YouTube, cross-channel, attribution). The flow is always: listDatasets → describeDataset → queryDataset.

listDatasets

List every dataset this team can query, with availability. No parameters.

Returns { datasets: [...] }. Each entry carries an id, name, description, family (ads / organic / cross-channel / attribution), live (true for free-tier live datasets), and an availability object — for unavailable datasets, the reason and the action that would unlock it.

describeDataset

Describe one dataset's fields before you query it.

Returns the dataset's dimensions and metrics (each with its aggregation semantics), available date grains, the legal filter operators per field type, and the dataset's grain in plain language.

queryDataset

Run a query by picking fields — no SQL or GAQL.

Returns typed columns, positional rows, rowCount, a truncated flag, and an applied echo of the request. Validation errors name the problem and suggest valid fields, operators, or values.

runGoogleAdsGaql

Escape hatch: run a single read-only GAQL query against live Google Ads when no dataset covers the question. Prefer queryDataset for metrics; reach for this on config-graph and "what is it right now" reads: bidding strategies and targets, conversion actions, campaign criteria, ad approval status, goal wiring. Works on the free tier (it reads the live connection, not the warehouse).

Returns { rows, meta } — rows are keyed by dotted GAQL field paths exactly as queried. Guarantees: every SELECTed field is present on every row (explicit null when Google omits it), int64 metrics arrive as real numbers, results are capped at 2,000 rows with an explicit meta.truncated flag, and per-account failures are reported verbatim in meta.errorsByCustomer — never silently dropped. Write metrics.cost in SELECT (auto-expanded to metrics.cost_micros and normalized back to currency units); Buron's synthetic.channel_group / synthetic.country_group dimensions work in SELECT, WHERE, and ORDER BY. GAQL is not SQL: no JOIN, no GROUP BY, no OR, no subqueries. Google Ads API v23 — field names change across versions.

The previous raw query tool and POST /api/v1/query were replaced by this surface and removed.

Saved queries

Saved queries store the same structured definition the Explore builder uses, so an agent-saved query reopens fully editable in the product, and a query saved from the product runs here.

saveQuery

Save a semantic query for reuse.

Returns the saved query with its buron://query/{uuid} URI.

runQuery

Execute a saved query by id, recompiled from its current definition (a later edit in the product is reflected).

Returns the same result envelope as queryDataset.

listQueries

List saved queries, optionally filtered by dataset.

Returns { queries: [...] }. Each entry includes id, name, dataset, kind (structured / raw-sql), the picked query, and the buron://query/{uuid} URI.

Dashboards

Dashboards are pre-built views that combine multiple queries into KPIs, charts, and tables. Buron ships with default dashboards and your team can create custom ones.

listDashboards

List every dashboard available to your team: default dashboards plus any custom dashboards. Returns the fully-hydrated shape: each dashboard carries a description, tags, and panel definitions. Each panel is either a query tile (backed by a structured dataset query) or a rollup tile (a bespoke computed panel). For an ad-hoc question not covered by a saved dashboard, use queryDataset instead.

No parameters.

Returns { dashboards: [...] }.

runDashboard

Run a dashboard for a date range and return panel data.

Returns the computed panel data: KPIs, chart series, and detail tables.

createDashboard

Assemble a custom dashboard from existing saved queries.

Returns the dashboard with its buron://dashboard/{uuid} URI.

addDashboardPanel

Append a saved query as a tile on a custom dashboard your team owns.

Returns the updated dashboard.

Integrations & account topology

getIntegration

Check the connection status of an ad platform integration.

Returns { connected, provider, status, externalAccountId }. For google-ads the response also carries the account topology: accounts[] (customerId, name, currency, time zone for every enabled account), managerCustomerId (the MCC linkage, when manager-scoped), and selectedConversionAction — the team's primary conversion action, the config behind synthetic.selected_conversions and the dashboard KPIs.

listGoogleAdsAccounts

List every enabled Google Ads account on the team's connection — the first read in any MCC or account-split situation. No parameters.

Returns { accounts: [{ customerId, descriptiveName, currencyCode, timeZone }], count }.

This roster is the boundary. Account selection happens once, in the connection flow, where you see only the accounts your Google login grants access to and choose which ones Buron may use. Every read on this surface — queryDataset, runGoogleAdsGaql, dashboards — is confined to that chosen set; asking for an account outside it returns an error naming the account, not data. Changing the selection means reconnecting. There is deliberately no tool for enumerating accounts under a manager account: for an agency, the rest of your client roster is not visible to agents, only the accounts you enabled for this team.

Mutations (write rail — entitlement-gated)

Teams with mutations enabled get the proposal rail: agents draft typed, guardrailed account-change proposals; nothing is ever applied by an agent — a human reviews and approves in-app, every applied change lands in an audit ledger, and applied changes carry a drafted inverse for one-click revert. Tools: createMutationProposal, listMutationProposals, getMutationProposal, dismissMutationProposal, refreshMutationProposal (re-checks a proposal's basis against live state), requestMutationRevert, listMutationLedger. Teams without the entitlement don't see these tools at all.

Knowledge files

Your team's knowledge layer is a file system. These tools give your editor full read/write access.

readFile

Read a file by path.

Returns the file content as text. Returns an error if the file doesn't exist.

writeFile

Write or update a file.

Returns confirmation with the path and character count.

listFiles

List files in a directory.

Returns { files: [...] }.

glob

Find files matching a glob pattern.

Returns { files: [...] }.

grep

Search file contents for a pattern.

Returns { matches: [...] }.

Editor skills

These tools let your editor discover and install Buron skills (like /launch) directly.

listEditorSkills

List skills that can be installed into your project. Returns each skill's name and description, plus the install targets for each supported editor.

No parameters.

Returns { skills: [...], installTargets: [...] }.

readEditorSkill

Get the full template for a skill.

Returns the full SKILL.md template as text. Write it to {projectRoot}/{editorSkillsDir}/{name}/SKILL.md to install.