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. Use action to choose the operation:

• list — all available skills
• 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. 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)

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

This tool has a workflow playbook: run list-skills (or load-skill by the matching whatagraph-<domain> name) for its required fields, valid ID shapes, call sequence, and known gotchas before composing a call. Whatagraph's data model is specific, so a call assembled without the playbook often fails on a field name or ID.

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: if the response indicates data is not yet ready (rate-limited or processing), wait the indicated retry_after seconds and call again with the same parameters.

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).

This tool has a workflow playbook: run list-skills (or load-skill by the matching whatagraph-<domain> name) for its required fields, valid ID shapes, call sequence, and known gotchas before composing a call. Whatagraph's data model is specific, so a call assembled without the playbook often fails on a field name or ID.

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

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, filterable by name, space, integration, or source (pass cursor from page.cursor for next page)
• show — full report details: pages with widgets, date range, share settings
• list_sources — list data sources and sample integrations used in a report
• resolve — resolve a live-report URL, share URL, or hash to a report_id. Pass the URL or hash in url_or_hash

This tool has a workflow playbook: run list-skills (or load-skill by the matching whatagraph-<domain> name) for its required fields, valid ID shapes, call sequence, and known gotchas before composing a call. Whatagraph's data model is specific, so a call assembled without the playbook often fails on a field name or ID.

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)
• show — full tab details with all widgets and their types

This tool has a workflow playbook: run list-skills (or load-skill by the matching whatagraph-<domain> name) for its required fields, valid ID shapes, call sequence, and known gotchas before composing a call. Whatagraph's data model is specific, so a call assembled without the playbook often fails on a field name or ID.

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, configs with metrics/dimensions/source, layout. Image widget URLs in options.images[].url are returned as full, directly-usable URLs
• csv_export — export widget data as CSV rows. Check data_status in the response: ready (data loaded), warning (data source error or still warming up — check warning_message for details, retry later), no_data (no data for the date range)
• 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

This tool has a workflow playbook: run list-skills (or load-skill by the matching whatagraph-<domain> name) for its required fields, valid ID shapes, call sequence, and known gotchas before composing a call. Whatagraph's data model is specific, so a call assembled without the playbook often fails on a field name or ID.

Export all widgets in a report (or a single tab) as CSV. Returns a flat list of widget envelopes, each with CSV data, metadata (title, source, date range, type), and a tab_id indicating which tab the widget belongs to. A separate tabs array maps tab IDs to names.

Widgets are ordered by tab position, then by widget position within each tab.

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
• cursor (optional) — pagination cursor from a previous response

Responses are capped at ~50 KB. If the report has more widgets than fit in one response, page.has_more is true — pass page.cursor in the next call to get the next batch. There is no widget count limit.

Comment widgets (including AI summaries) have no tabular data, so instead of a csv field their envelope carries the plain-text text content and an is_ai_generated flag. Image widgets likewise have no CSV — their envelope carries an image_url instead. Calendar and filter control widgets are skipped.

Media widgets (compact and expanded) additionally include an image_urls array — the deduplicated ad-creative image URLs from their rows — so an agent can analyse creative performance without parsing the CSV.

This tool has a workflow playbook: run list-skills (or load-skill by the matching whatagraph-<domain> name) for its required fields, valid ID shapes, call sequence, and known gotchas before composing a call. Whatagraph's data model is specific, so a call assembled without the playbook often fails on a field name or ID.

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)

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 (pass cursor from page.cursor for next page)
• 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 (pass cursor from page.cursor for next page)
• show_theme — single theme details: name, header, footer, and style options (requires report_id and theme_id)

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)

View report sharing settings and public share URLs. If a user says "share link", they mean this tool. Use action to choose the operation:

• show — current sharing settings and share URL for a report

URL types: The share_url is the public viewer URL (e.g. https://reports.live/shared/<hash>). 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)
• show_subscription — current subscription plan and usage limits
• list_plans — available subscription plans

This tool has a workflow playbook: run list-skills (or load-skill by the matching whatagraph-<domain> name) for its required fields, valid ID shapes, call sequence, and known gotchas before composing a call. Whatagraph's data model is specific, so a call assembled without the playbook often fails on a field name or ID.

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 — full dimension details including the rules needed to reproduce it: field mappings, plus condition maps (data), tag values + assigned sources (tag), or the AI prompt (ai)
• usage — how many widgets/reports use specific dimensions (bulk check)

This tool has a workflow playbook: run list-skills (or load-skill by the matching whatagraph-<domain> name) for its required fields, valid ID shapes, call sequence, and known gotchas before composing a call. Whatagraph's data model is specific, so a call assembled without the playbook often fails on a field name or ID.

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)

This tool has a workflow playbook: run list-skills (or load-skill by the matching whatagraph-<domain> name) for its required fields, valid ID shapes, call sequence, and known gotchas before composing a call. Whatagraph's data model is specific, so a call assembled without the playbook often fails on a field name or ID.

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

This tool has a workflow playbook: run list-skills (or load-skill by the matching whatagraph-<domain> name) for its required fields, valid ID shapes, call sequence, and known gotchas before composing a call. Whatagraph's data model is specific, so a call assembled without the playbook often fails on a field name or ID.

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 output_name and name (the report-type granularity needed to reproduce the group)
• source_issues — list sources with disabled ETL configs (sync issues)
• list_output_names — list valid output_name values for creating a source group (requires source_ids)

This tool has a workflow playbook: run list-skills (or load-skill by the matching whatagraph-<domain> name) for its required fields, valid ID shapes, call sequence, and known gotchas before composing a call. Whatagraph's data model is specific, so a call assembled without the playbook often fails on a field name or ID.

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

This tool has a workflow playbook: run list-skills (or load-skill by the matching whatagraph-<domain> name) for its required fields, valid ID shapes, call sequence, and known gotchas before composing a call. Whatagraph's data model is specific, so a call assembled without the playbook often fails on a field name or ID.

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 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

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