Whatagraph MCP Server

CALL THIS FIRST — before any other tool — on the first turn of every new conversation, and again when entering a new domain. This discovers the workflow skills for the server: the step-by-step playbooks that carry the correct workflow, field IDs, and gotchas for each Whatagraph task (widgets, blends, filters, reports, automations, sources, and more). Skills are the operating manual — the other tools expose the raw API, and these playbooks tell you how to drive it, so loading the matching one before you build a call is what makes multi-step flows succeed instead of failing on a field name or ID. The index is small, cached, and read-only. Use load-skill to read a skill's full content; skill names follow a predictable whatagraph-<domain> convention, so a known domain can be loaded directly without listing first. A skill is listed even when this agent is missing a tool it needs — those tools are named in missing_required_tools, so you can read the playbook and tell the user which grant to ask the team owner for. Use action to choose the operation:

• list — every skill on the server
• search — find skills matching a query (requires query parameter). Supports natural language queries (e.g. "how to create a report") and keyword searches.

Load a workflow skill — a step-by-step playbook for a Whatagraph task that carries the correct workflow, field IDs, and gotchas. Skill names follow a predictable whatagraph-<domain> convention (e.g. whatagraph-widgets, whatagraph-blends, whatagraph-reports), and each write tool names its own skill in its description, so a known domain can be loaded directly here; use list-skills to discover skills when the name is unknown. A skill loads even when you are missing a tool it needs — the missing tools are named in the response, and you should relay them to the user so the team owner can grant them. Use action to choose the operation:

• show — full skill content (markdown)
• header — description + first 200 characters preview

Browse data sources connected to your team. Data sources are specific accounts/properties connected from integrations (e.g. a specific Google Ads account, a specific GA4 property). Use action to choose the operation:

• list — list all connected data sources (cursor-paginated, pass cursor from page.cursor for next page)
• show — full details for one source (requires source_id)
• list_metadata — list metadata for source management; use scope to fetch only what you need (integrations, accounts, spaces, users, tags, categories, or all)
• list_report_types — list available report types for a source (requires source_id)
• list_dimensions_and_metrics — list available dimensions and metrics (cursor-paginated, requires source_id, optionally report_type, filter, is_universal)
• resolve_fields — semantic search for dimensions and metrics by natural language (requires source_id and query, e.g. "revenue", "how much did we spend"). Returns the best-matching fields ranked by relevance
• list_usage — list usage counts for sources across reports, blends, transfers, source groups, and overviews (requires source_ids)
• health_summary — aggregated counts by status (ok, error) and total — no pagination, one call for the whole account

Each source item carries requires_report_type; when it is true, call list_report_types and pass the result to widget and fetch calls. The playbook lists the returned attributes and the aliases accepted in fields projections.

Start here when you need to understand what data is available before fetching it.

Playbook — required fields, ID shapes, call sequence: load-skill whatagraph-sources-and-data.

Fetch marketing data from a connected source. Returns rows of metric values optionally grouped by dimensions for a date range. Use the list-sources tool first to discover available sources, report types, and field names. Important: when a failure is retryable, wait the retry_after seconds it gives you and call again with the same parameters. A permission_denied failure is not retryable — the source has to be reconnected first.

Field IDs come in three families, and the valid set depends on the source AND report type: native dotted IDs (e.g. metrics.cost_micros on Google Ads), bare IDs (e.g. sessions on GA4), and custom-field IDs (universal_metric_{id} / universal_dimension_{id}). Never guess the family — copy the external_id verbatim from list-sources action=list_dimensions_and_metrics for the same source_id and report_type you pass here.

limit sets the page size; the response is also capped at ~50 KB. When the full result exceeds either bound, rows are paginated — check page.has_more and pass page.cursor in the next call to get the next page. page.estimated_total is the true total row count, not just the rows returned. When comparison data is included, both primary and comparison rows paginate together in lockstep under one shared ~50 KB cap (a single cursor advances both blocks, each tracking its own position).

Playbook — required fields, ID shapes, call sequence: load-skill whatagraph-sources-and-data.

Browse spaces (also known as "client folders"). Spaces are the top-level containers that organize reports and data sources. If a user says "space", "folder", or "client", they mean a space. Use action to choose the operation:

• list — cursor-paginated list of spaces the user can access (pass cursor from page.cursor for next page)
• show — full details for one space (report/measurement counts)
• children — list sub-spaces under one space

Home space: Every team has a default "Home" space that holds reports not assigned to a named space. list returns it alongside named spaces — it is the one with is_home=true.

Browse reports within spaces (client folders). Reports contain pages of data visualization widgets. Use the list-spaces tool first to find the right space, then this tool to explore reports inside it. Use action to choose the operation:

• list — cursor-paginated list of reports. Each item includes space_name, pages_count (tab count), and sources_summary (connected integration names like ["Google Ads", "Meta Ads"]). Filterable by search (name), semantic_search (meaning-based), filter_space_ids, filter_channel_ids (accepts slugs like "google-ads"), or filter_source_ids
• show — full report details: pages with widgets, date range, share settings
• list_sources — flat list of all data sources on a report, each with is_sample_data boolean
• resolve — resolve a live-report URL, share URL, or hash to a report_id. Pass the URL or hash in url_or_hash

Playbook — required fields, ID shapes, call sequence: load-skill whatagraph-reports.

Browse tabs (pages) within a report. Each report has one or more tabs, each containing widgets (data visualizations). Called "tabs" in the UI, stored as "report_pages" in the backend. Use the list-reports tool first to find the report, then this tool to explore its tabs. Use action to choose the operation:

• list — list all tabs in a report (id, name, position, widget count). By default only visible tabs are returned; pass include_hidden: true to also list hidden tabs
• show — full tab details with all widgets and their types

Playbook — required fields, ID shapes, call sequence: load-skill whatagraph-report-tabs.

Browse widgets on report tabs. Widgets are visual data components — charts, tables, single values, funnels, media, goals, etc. — that display marketing data from connected sources. If a user says "chart", "graph", "table", "KPI card", or "visualization", they mean a widget. Use action to choose the operation:

• list — list all widgets in a report (summaries grouped by tab)
• show — full widget details: type, layout, and per-config metrics / dimensions / report_types in the same shape manage-widgets accepts back, plus source and options (display settings only — bindings are not duplicated there). Image widget URLs in options.images[].url are returned as full, directly-usable URLs. Offline widgets (types 125-136) bind no metric, so they return no bindings; each row reports data_summary instead — headers and data_row_count for table and time-series shapes, entry_names and entry_count for the rest
• csv_export — export widget data as CSV rows. Response contains csv_rows: string[][] (first row is headers, rest are data rows), data_status (ready = data loaded, warning = source error or warming up — check warning_message and retry after retry_after_seconds, no_data = no data for the date range), and title (widget display name)
• list_premade — cursor-paginated list of premade/template widgets (no report_id needed, pass cursor from page.cursor for next page). Requires channel_id to scope results to a specific integration
• currency_exchange — list the money metrics on a widget that can be converted to a different currency, with each metric's current external_id, original_currency, exchange_currency, default_currency, and is_converted flag. Feed the external_id into manage-widgets action=convert_currency or restore with action=restore_currency. Requires the Data Transformation premium feature
• conditional_formats — read how a table widget (type 102) colours its cells by value. Each metric reports a mode: manual (threshold rules, returned in position order — first match wins — with operator, value, value_end, text_color, background_color), auto (the whole column shaded in seven tints of auto_color across its own low-to-high range), or none. A metric is in one mode or the other, never both. Narrow with metric_external_id. Write with manage-widgets action=set_conditional_formats / add_conditional_formats / set_auto_colors. action=show also flags which metrics carry rules via has_conditional_format
• list_icons — the icon library available to widget rows (KPI cards, list rows). No report_id needed. Narrow with search (matches name, tags and groups) or icon_set. Write the returned icon value verbatim into rows[].options.icon via manage-widgets; action=show reads it back as rows[].icon

Playbook — required fields, ID shapes, call sequence: load-skill whatagraph-widgets.

Export all widgets in a report (or a single tab) as an Excel file. Returns a temporary download URL (expires in 1 hour) to an .xlsx file where each widget is a separate sheet with its own columns and data.

Use shell tools (head, cut, wc -l) on the downloaded file to inspect specific parts without loading the entire dataset.

Parameters:

• report_id (required) — report to export
• tab_id (optional) — limit to a single tab
• widget_ids (optional) — limit to specific widgets
• from / till (optional, YYYY-MM-DD) — fallback date range for widgets that don't have one configured

Calendar and filter control widgets are skipped.

Requires the widget-csv-export plan feature. Teams without it will get a permission error.

Playbook — required fields, ID shapes, call sequence: load-skill whatagraph-export.

Browse available integrations (channels) and connected accounts. If a user says "channel" or "integration", they mean this tool. Use action to choose the operation:

• list — all implemented integrations
• list_grouped — integrations grouped by category with source counts
• list_accounts — connected accounts for a specific integration (requires channel_id)
• list_available_sources — available sources for an account (requires account_id). For sub-source integrations (Google Sheets, BigQuery, Snowflake), returns parent sources with has_sub_sources=true
• list_available_sub_sources — available sub-sources (e.g. sheet tabs, BQ tables) for a parent source (requires account_id and source_external_id)

Browse report visual themes and color palettes. Control branding, colors, and visual appearance of reports. Use action to choose the operation:

• list_themes — cursor-paginated list of available themes. Pass report_id to see both report-level and team-level themes with active status; omit report_id for team-level themes only. Response includes applied_theme_id, applied_theme_source ("team", "report", "system", or null), and team_has_themes
• list_colors — cursor-paginated list of color palettes. Pass report_id to see both report-level and team-level palettes with active status; omit report_id for team-level palettes only. Response includes applied_color_id, applied_color_source ("team", "report", "system", or null), and team_has_colors. Names and IDs only — read a palette's actual colors with show_color
• show_theme — single theme details: name, header, footer, and style options (requires report_id and theme_id)
• show_color — a single palette's actual colors: widget_colors, chart_colors, additional_colors (requires color_id). list_colors returns names and IDs only, so this is the only way to read what a palette looks like. Works on built-in premade palettes too — pass the applied_color_id a report reports as "system" to read it, or to copy it as the base for a new palette.

When applied_theme_source is "system", the active theme is a built-in premade theme not included in the list — team_has_themes: false with a non-null applied_theme_id is expected in this case.

Email (whitelabel) themes control report-delivery email branding (separate from report visual themes). These require the whitelabel feature.

• list_email_themes — the team's email themes with their web/email domains and options
• list_web_domains — web domains available for email themes (team + premade) — pick an id for web_domain_id
• list_email_domains — email domains available for email themes (team + premade) — pick an id for email_domain_id

Browse report templates — reusable report blueprints. Templates can be applied to create new reports. Linked reports auto-update when their template changes. Use action to choose the operation:

• list — cursor-paginated list of team templates with tags and linked report counts (pass cursor from page.cursor for next page)
• show — template details: pages with widget counts, theme settings
• linked_reports — reports created from this template (auto-sync with template changes)

Browse report snapshots — saved versions of a report's structure. Use action to choose the operation:

• list — cursor-paginated snapshots for a report with timestamps and creator (pass cursor from page.cursor for next page)
• show — snapshot details including tab/widget/source counts and creator

View report and overview sharing settings and public share URLs. If a user says "share link", they mean this tool. Target a report with report_id or an overview with overview_id — one or the other, never both. Use action to choose the operation:

• show — current sharing settings and share URL. Returns is_shared (bool), and when shared: share_settings.id, share_settings.share_url, share_settings.require_password (bool) and share_settings.disable_date_changing (bool). A report share also returns share_settings.hash, share_settings.options and share_settings.date_range (from/till/period/compare_type); an overview share has none of those.

URL types: The share_url is the public viewer URL (e.g. https://reports.live/shared/<hash> for a report, .../shared/o/<ulid> for an overview). This is NOT the signed-in editor URL (https://live.whatagraph.com/client/<space_id>/live-report/<report_id>).

View team settings, subscription details, available roles, and perform global search across the entire platform. Use the search action when you don't know which domain (reports, spaces, overviews) to look in. Use action to choose the operation:

• show — team info: name, settings, enabled features
• search — global cross-domain search: finds reports, overviews, spaces, blends, and source groups matching a term. Returns a bounded set of top matches per domain (not paginated; cursor is not accepted)
• roles — available team roles for this team (admin, manager, editor)
• members — seated team members with their member_id, name, email, and current role (use member_id to change a member's role via manage-members)
• invites — pending invitations with invite_id, email, and role (use invite_id with manage-members for update_invite, resend_invite, or remove-members for cancel_invite)
• show_subscription — current subscription plan and usage limits
• list_plans — available subscription plans

Playbook — required fields, ID shapes, call sequence: load-skill whatagraph-team-and-members.

Browse scheduled report delivery configurations. If a user says "schedule", "automated report", or "email delivery", they mean automation. Use action to choose the operation:

• list — automation schedules for a specific report (requires report_id)
• list_all — all automations across the account (no report_id needed), with cursor pagination. Supports search (by report name) and frequency filters
• show — full automation details: schedule, timezone, compare type, PDF settings

Browse custom dimensions (universal dimensions). These are user-created dimensions that combine or transform data from connected sources. Use action to choose the operation:

• list — cursor-paginated team custom dimensions with optional type/search filter (pass cursor from page.cursor for next page)
• list_with_premades — cursor-paginated list including premade (system) dimensions alongside team ones
• show — dimension details including rules: field mappings, condition maps (data), tag/source counts (tag), or AI prompt (ai)
• list_tags — paginated tag values with assigned source IDs for a tag-type dimension (pass cursor from page.cursor for next page)
• usage — how many widgets/reports use specific dimensions (bulk check)

Playbook — required fields, ID shapes, call sequence: load-skill whatagraph-custom-dimensions.

Browse custom metrics (universal metrics). These are user-created metrics that combine or transform data from connected sources using formulas or aggregations. Use action to choose the operation:

• list — cursor-paginated team custom metrics with optional type/search filter (pass cursor from page.cursor for next page)
• list_with_premades — cursor-paginated list including premade (system) metrics alongside team ones
• show — full metric details
• usage — how many widgets/reports use specific metrics (bulk check)

Playbook — required fields, ID shapes, call sequence: load-skill whatagraph-custom-metrics.

Browse data blends. Blends combine data from multiple sources into a single virtual data source for cross-channel reporting. Use action to choose the operation:

• list — cursor-paginated list of blends with optional search/filter (pass cursor from page.cursor for next page)
• show — full blend details with sub-sources, join configuration, and usage stats

Each sub-source in show reports its own filter, which narrows that channel's rows before the join runs. Use manage-filters with blend_sub_source_id to change one.

Playbook — required fields, ID shapes, call sequence: load-skill whatagraph-blends.

Browse source groups. Source groups combine multiple data sources into a single aggregated source with unified report type configurations. Use action to choose the operation:

• list — cursor-paginated list of source groups, supports search (pass cursor from page.cursor for next page)
• show — full source group details: sources, plus each config's id, output_name (read-only, computed from the config's structure — not a create/update parameter), name, and etl_config_ids (the per-channel ETL config ids to re-pass when updating)
• source_issues — list sources with disabled ETL configs (sync issues). Pass group_id to check a specific group, or omit it to check all groups at once
• list_output_names — list valid output_name values for creating a source group (requires source_ids)

Playbook — required fields, ID shapes, call sequence: load-skill whatagraph-source-groups.

Browse unified filters. Filters are saved filter configurations that can be applied to data sources and widget configs to narrow down displayed data. Use action to choose the operation:

• list — cursor-paginated list of team filters, filterable by name and channel (pass cursor from page.cursor for next page)
• show — full filter details with options and values
• list_parameters — list available filter parameters for a channel (e.g. attribution windows, granularity). These are channel-specific settings that affect how filtered data is queried from the provider API. Requires channel_id

Playbook — required fields, ID shapes, call sequence: load-skill whatagraph-filters.

Browse overviews (called 'measurements' in the backend) — KPI tracking dashboards that monitor specific metrics over time with visualizations. If a user says 'overview', they mean this tool. Use action to choose the operation:

• list — cursor-paginated list of team overviews, supports search (pass cursor from page.cursor for next page)
• show — full overview details with configs, applied filters, and share settings

View data goals (called 'data goals' in the backend, 'goals' in the UI) — targets set on specific metrics to track progress toward KPIs. Use action to choose the operation:

• list — paginated list of goals with optional search/filter by source
• show — show details for a specific goal by ID
• status — measure named goals against freshly fetched data and report whether each is on track

list and show return a goal's configuration only — no progress and no verdict. active there means the goal is still running, NOT that it is being met. Never infer from list or show that a goal is on track, healthy, or within its limit: only status fetches actual data and decides.

status takes an explicit goal_ids array (max 20 per call) and returns, per goal: status (on_track / off_track / unknown), current_value, goal_value, percentage, projected_value (where the metric lands at the current run-rate) and days_remaining. A goal is off_track when it is projected to miss a target or breach a limit — not merely behind an even pace. unknown means the goal could not be measured (broken source, missing metric); treat it as a blind spot, never as a pass. To check many goals, call list first, then status in batches of 20.

Pagination: list uses page-number pagination (page + per_page), not cursor-based. Response includes page, per_page, last_page, and total_count.

View data transfers and destination types. Use action to choose the operation:

• list — paginated list of transfers with optional filters by name, status, issue, or destination
• show — full details for a specific transfer by ID, including its configs
• list_jobs — paginated list of ETL jobs for a specific transfer, optionally filtered by config_id and state
• list_destination_types — available destination types (BigQuery, Looker Studio, Whatagraph Storage) with their required components and locations