Skip to main content
With the MCP chart tools, an AI tool can read your dashboards, run SQL on your events, preview a chart in the conversation and save it to a dashboard. Every chart is one chart spec: what it computes (the query) and how it is drawn (the view). The dashboard editor, Ask AI and the MCP tools write the same spec, and the API checks it the same way.

Scopes

dashboards:write does not include dashboards:read. A key that changes dashboards and also lists or reads them needs both scopes. A call to a tool without its scope returns an error that names the missing scope. A key with query:read or dashboards:write acts for the person who created it. The audit log shows each change as that person, marked via: mcp. If that person leaves the workspace, the key stops working. If their role goes below editor, the key keeps only its read scopes. With OAuth, the person who approved the app is the actor.

Workflow

  1. describe_schema returns the raw_events and sessions columns, the context keys, the SQL rules, one example spec for each view feature and the custom events of the last 30 days.
  2. execute_query runs your SQL and returns the result columns and up to 200 rows.
  3. preview_chart runs a spec and returns the rows with the spec unchanged. In clients that support MCP Apps, such as Claude, the chart shows in the conversation.
  4. create_chart saves the spec on a dashboard. update_chart replaces the title and the spec. delete_chart and delete_dashboard need "confirm": true.
create_chart arguments

How a spec is checked

  • The spec has exactly version (always 1), query and view. Unknown keys are refused.
  • A SQL query runs once over the last 30 days. Every column that the view names must be a result column. A number card needs one row.
  • Nothing is saved on a refusal. The error names the bad field, for example Invalid chart spec: spec.view: The view names 'sessions', which the query result does not have. Result columns: day, pageviews, visitors.
  • A dashboard has up to 24 charts.

SQL rules

  • One SELECT or WITH statement over raw_events, sessions or session_events. No other table, no comments.
  • For sessions, bounce rate and session duration, read sessions (one row for each session of the date range, the same sessions as the reports): SELECT day, count() AS sessions FROM sessions GROUP BY day ORDER BY day. Do not add a date condition to it, and never count sessions from raw_events.
  • The server adds the project filter. You do not filter on project_id.
  • Use {{date_from}} and {{date_to}} together: received_at >= toDateTime({{date_from}}) AND received_at < toDateTime({{date_to}}) + INTERVAL 1 DAY. A saved chart then follows the dashboard date range.
  • Return aggregates (count(), uniqExact(), sum()) grouped by the columns you chart.
  • A query runs at most 8 seconds. A chart reads up to 1,000 rows.
raw_events columns: anonymous_id, session_id, user_id, channel, type (page, track, identify), event, context (JSON), properties (JSON), original_timestamp, received_at, message_id. Read context keys with JSONExtractString(context,'utm_source'); the page path is JSONExtractString(context,'page','path'). sessions columns: anonymous_id, session_key, day, first_at, last_at, pageviews, custom_events, revenue, the landing columns of the first page view (channel_type, utm_source, utm_medium, utm_campaign, referrer, ref, paid_source, country), entry_page, exit_page. Name only the landing columns that the chart needs: each one uses memory, and a query over 256 MiB fails with a message that says so. See Explorer.

The view

The view is a small subset of Vega-Lite. Each channel (x, y, color, xOffset, yOffset, theta, text) names one result column with { "field": "<column>" } and never computes. Number formats are d3-format strings: "$,.2f" money, ".1%" percent (values are fractions), ".3~s" compact, ",.0f" integers.

Examples

One example for each view feature. Funnel, retention and user paths charts have no SQL: the API builds their queries from the settings, so preview_chart does not draw them; save them on a dashboard to see them.

Number

One value (1 row, 1 numeric column), or set encoding.text.field.

Number format

Money, fractions (0.25 = 25%) or large counts: a d3 format on text or on an axis.

Table

Several columns to read, not to compare visually.

Line

A time series with one metric.

Area

Volume over time.

Bar

Categories or a top N list.

Several value columns (fold)

Wide rows: one series per metric column. The as names must not be result columns.

Split line

Long rows: one line per value of a breakdown column (color differs from x).

Stacked bars

The total and its parts per x.

100% stacked

Shares or mix over time: each x adds up to 100%. Also with mark area.

Grouped bars

Compare a few series side by side per x (xOffset equals color).

Horizontal bars

Rankings with long labels: a nominal y and a quantitative x.

Pie

Proportions of 2 to 10 categories.

Scatter

Whether two numbers move together: one point per row.

Combo

A count and a rate on the same x, each with its own axis: one bar layer and one line layer.

Goal line

Only when the user states a target: a rule layer with a y datum.

Goal line on the right axis

A target for the line of a combo with resolve.scale.y “independent”: nest the line and its rule in one layer, so the rule uses the right axis. A rule outside the nested layer is on the left (bars) axis.

Funnel

Conversion through 2 to 5 ordered steps (no SQL; save it on a dashboard to see it).

Retention

Share of visitors who come back each period (no SQL).

User paths

How people move from page to page (no SQL).