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
describe_schemareturns theraw_eventsandsessionscolumns, the context keys, the SQL rules, one example spec for each view feature and the custom events of the last 30 days.execute_queryruns your SQL and returns the result columns and up to 200 rows.preview_chartruns 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.create_chartsaves the spec on a dashboard.update_chartreplaces the title and the spec.delete_chartanddelete_dashboardneed"confirm": true.
create_chart arguments
How a spec is checked
- The spec has exactly
version(always1),queryandview. 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
SELECTorWITHstatement overraw_events,sessionsorsession_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 fromraw_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, sopreview_chart does not draw them; save them on a dashboard to see them.