How to use GrowthBook's MCP server to build and run charts

“Chart signups by country for the last 30 days” sounds simple. The hard part is choosing the governed data, building a valid exploration, paying for one intentional warehouse query, and reading the result correctly.

GrowthBook's MCP server can turn that request into a Product Analytics exploration from a compatible AI client. The latest analytics-explore skill selects one SQL datasource, chooses an existing fact metric or an underlying table, constructs the chart configuration, runs the warehouse query, and returns both the numbers and a deep link to the interactive chart.

It does not create a dashboard or modify metric definitions. A chart run is still consequential because it uses warehouse compute and may expose a wrong conclusion if the unit, date grain, or partial-day bucket is misread. The workflow therefore favors curated metrics, uses the result cache, and validates the exploration status rather than treating an HTTP response as proof of success.

This guide follows the current GrowthBook agent skills and version 2 GrowthBook MCP server.

Start with a decision-ready question

A useful chart request names the measure, time range, grain, optional breakdown, and desired view. Compare:

Show me activation.

with:

Use the latest analytics-explore skill. Chart the official Activation fact metric as a daily line for the last 30 days on the Product Warehouse datasource. Break it down by country with at most five values. Prefer cached results, state whether today's bucket is partial, return the numbers and exploration link, and do not create a dashboard.

The second prompt reduces several ambiguities without dictating the API payload. It also makes the cost boundary visible. GrowthBook's warehouse-native Product Analytics queries the data where it lives; a natural-language request is not a free local visualization.

This is one reason a governed metric layer matters. The dbt Semantic Layer makes a similar case for defining metrics once for downstream use. With GrowthBook, the same fact-metric definition can support both experimentation and product analytics, which reduces the chance that a dashboard and an experiment use subtly different KPI logic.

Before charting an unfamiliar catalog, use metric-search to list and audit candidates. Pass exact IDs into analytics-explore; names can be duplicated or changed.

The discovery sequence is read-only and should finish before the warehouse query begins:

gb-call GET /api/v1/data-sources
gb-call GET '/api/v1/fact-metrics?datasourceId=<DATASOURCE_ID>&limit=100'
gb-call GET /api/v1/fact-tables/<NUMERATOR_FACT_TABLE_ID>

The first response selects the datasource, the second supplies the exact fact-metric ID and type, and the third supplies userIdTypes for the required unit. If the metric list returns hasMore: true, paginate it before concluding that a named metric is absent.

Choose one datasource before choosing the chart

Every exploration belongs to one datasource. The skill lists configured datasources and follows a simple decision:

• none: stop because there is nothing to query
• one: use it and tell the user which one was selected
• more than one: use the datasource named by the user or ask for a choice

Only SQL warehouses work with these exploration endpoints. A Mixpanel or Google Analytics connection will be rejected. Metrics, fact tables, and raw tables in one exploration must all belong to the selected datasource.

This restriction is useful, not merely technical. It stops an agent from combining objects that happen to have similar labels but live in different systems. It also makes query ownership and cost easier to trace. BigQuery, for example, documents query pricing based on processed data or capacity, while Snowflake explains how warehouse usage consumes credits. The exact cost model differs, but the operational lesson is the same: run the smallest query that answers the question.

GrowthBook's Product Analytics GA overview lists the supported visual exploration modes and warehouse integrations. The MCP workflow is a programmatic route into that exploration surface.

Prefer a defined fact metric

Path A uses an existing fact metric. This is the default when the user names a KPI such as revenue, signups, daily active users, or retention and a suitable definition exists.

The skill lists fact metrics on the selected datasource, paginates the results, and filters names client-side. It captures the metric ID, metric type, numerator fact-table ID, and unit information. Legacy met_... metrics are not chartable here; Product Analytics accepts fact__... metrics.

The unit rule is easy to miss and capable of producing silently wrong numbers:

• mean, proportion, retention, and daily-participation metrics use the fact table's first userIdTypes value
• ratio and quantile metrics use a null unit
• denominator unit remains null

If a unit is omitted from the first group, the server can switch to event-level aggregation without returning an error. A careful agent sets it explicitly.

Metric combinations have constraints. Ratio metrics cannot share a chart with non-ratio metrics, and quantile metrics cannot mix with anything else. When the requested combination is invalid, separate it into multiple explorations rather than forcing one confusing view.

A good prompt is:

Find the official Revenue per Account fact metric on ds_prod. Show a weekly line for the last 90 days. Use its exact ID and valid unit, prefer cache, and include the compiled SQL if the result looks surprising.

For a user-level fact metric, the resulting exploration configuration has this shape:

{
  "type": "metric",
  "datasource": "ds_prod",
  "chartType": "line",
  "dateRange": { "predefined": "last90Days" },
  "dimensions": [
    { "dimensionType": "date", "column": null, "dateGranularity": "week" }
  ],
  "dataset": {
    "type": "metric",
    "values": [
      {
        "type": "metric",
        "name": "Revenue per Account",
        "metricId": "fact__revenue_per_account",
        "unit": "account_id",
        "denominatorUnit": null,
        "rowFilters": []
      }
    ]
  }
}

Run it through the bundled helper with cache preference so an identical recent exploration can be reused:

echo '<CONFIG_JSON>' \
  | gb-call POST '/api/v1/product-analytics/metric-exploration?cache=preferred' -

Do not copy account_id blindly. It must come from the numerator fact table's userIdTypes; ratio and quantile metrics instead require unit: null.

The GrowthBook KPI playbook can help decide whether the named measure is a true decision metric or merely a supporting signal before you spend time polishing the visualization.

Chart metrics that drive decisions

Use a practical KPI framework to choose measures that clarify a product decision instead of adding another decorative trend line.

Read the KPI Playbook

Aggregate a fact table when no metric fits

Path B queries a GrowthBook fact table directly. It is useful for questions such as orders by country, unique users by plan, or total revenue from a numeric column when no curated fact metric expresses the request.

The skill inspects the table's user ID types and active columns, then chooses one aggregation:

• unit_count for distinct users or another registered unit
• count for rows
• sum for a numeric column

That choice should be explicit in the response. “Orders” could mean order rows, customers with an order, or summed order value. The agent should not decide silently.

Fact-table string columns may expose topValues. Check those before applying a filter, but treat them as a potentially stale hint because a background job populates them. There is no REST endpoint to look up every live value. If the requested value is absent, ask for the exact warehouse value or use a qualified contains filter and say so. Ignore columns marked deleted.

Use:

On fact table ftb_orders, count distinct user_id values for the last seven days and break down by country, top five. Verify that country is active and show the filter values you relied on. Do not substitute row count.

That prompt preserves the difference between people and events.

Use a raw warehouse table only as a fallback

Path C works when no GrowthBook fact table covers the source. The agent browses the datasource information schema, selects the fully qualified table path exactly, fetches its columns, classifies the raw warehouse types, and identifies a timestamp column.

The information schema must already have been generated in GrowthBook. If it does not exist, the skill stops and sends the user to the Product Analytics datasource explorer; there is no API action in this workflow that generates it.

Raw-table exploration needs more review because it lacks the curated filters, aggregation, caps, and naming of a fact metric. Ambiguous timestamp columns require a human choice. For a distinct-unit count, the unit must be a registered datasource identifier type and must also appear as a column.

The raw table path is interpolated into server-side SQL, so copy the path from the information schema rather than constructing it from memory. The broader OpenLineage specification illustrates why exact dataset identities and structured provenance matter when data moves through analytical systems.

Use this path to investigate and prototype. When a question becomes recurring or decision-critical, promote the logic into a reviewed fact table or fact metric through the GrowthBook application.

Configure time, dimensions, filters, and chart type

The skill supports line, area, timeseries table, table, bar, stacked bar, horizontal bar, stacked horizontal bar, and big-number views.

Timeseries charts always include a date dimension. Cumulative charts do not. When the user gives no preference, choose a line for a trend and a bar for totals or breakdowns. Use a big number only when the user explicitly asks for a single-stat display.

Valid fixed date presets are today, last 7 days, last 30 days, and last 90 days. A request for 14 days must use a custom lookback object; last14Days is not a valid shortcut. Explicit start and end dates use a custom date range.

Dimensions are intentionally bounded:

• a date dimension with automatic or requested hour, day, week, month, or year grain
• a dynamic breakdown column with a top-N value from 1 through 20
• at most two dimensions total
• at most one dimension when the chart contains multiple measures

Filters are ANDed and support comparisons, set membership, text matching, null tests, and Boolean tests. Never invent the spelling or capitalization of a filter value.

Follow-up requests should modify the prior configuration, not rebuild it. “Make it a bar chart” changes only the presentation and should hit the cache. “Use the last 90 days” changes the data and runs a new query.

Validate the payload, not the HTTP status

The exploration endpoints run synchronously, but an HTTP 200 can contain exploration.status: "error" or "running". Always branch on the payload:

• success: read the result rows and return the exploration URL
• error: surface the error, correct the configuration, and retry within the budget
• running: wait ten seconds and re-post the identical cached configuration once
• still running: stop and return the URL, which the GrowthBook application can poll

The version 2 server's generic REST bridge returns API response bodies to the client. The protocol itself does not guarantee that application-level success follows from transport success; MCP's tool concept leaves application semantics to the tool and server. This is why the GrowthBook skill inspects exploration.status explicitly.

Successful result rows can arrive unordered. Sort them by the date dimension before describing a trend. Today and any low-volume trailing bucket may be partial, so label them instead of presenting the apparent drop as real.

Inspect the response structurally before summarizing it. A successful payload contains the status, rows, compiled query, and a shareable URL:

{
  "exploration": {
    "status": "success",
    "result": {
      "rows": [
        {
          "dimensions": ["2026-08-03"],
          "values": [
            {
              "metricId": "fact__revenue_per_account",
              "numerator": 18420,
              "denominator": 612
            }
          ]
        }
      ]
    },
    "query": { "query": "<COMPILED_SQL>" }
  },
  "explorationUrl": "<GROWTHBOOK_EXPLORATION_URL>"
}

For this mean metric, the per-account value is numerator / denominator. Preserve the raw numerator and denominator in the receipt, sort all rows by date, and mark the trailing bucket partial when it is still accumulating.

When a result looks wrong, inspect the returned compiled SQL. It is the fastest way to find an unexpected filter, unit, or aggregation. If the query returns no rows, widen the date range, relax a filter, or reconsider the dataset once before concluding there is no data.

Interpret numerator and denominator correctly

For total values, use the numerator. For a genuine per-unit mean, divide numerator by denominator. Proportion, retention, and daily-participation fact metrics behave differently in a standalone exploration: they emit qualifying distinct units, and numerator and denominator can be equal. Do not label that ratio as a 100% conversion or retention rate. Report the numerator as the count of units that performed the action.

This is the clearest example of why “plain English” still needs a product-specific skill. A general agent might see equal fields, calculate one, and tell a plausible but false story.

Keep experiment readouts separate. A general chart does not include an experiment's exposure population, sample ratio mismatch check, phases, decision framework, or statistical intervals. Route A/B-test questions to experiment-analyze and apply the review practices in GrowthBook's trustworthy experiments guide.

Return numbers, provenance, and a next step

A good final response contains:

1. one or two sentences with the key numbers
2. datasource, dataset type, metric or table ID, date range, and grain
3. breakdown and filter choices
4. cache or freshness status
5. partial-bucket and interpretation warnings
6. a direct explorationUrl for the interactive chart
7. the compiled SQL when it explains an anomaly

The deep link is part of the deliverable. GrowthBook encodes the exploration configuration so another user can inspect the rendered chart. The skill does not silently save it to a dashboard. If the result should become a durable shared asset, that is a separate, explicit workflow.

The sequence is deliberately compact: discover the governed object, run one bounded query, validate the application status, sort and interpret the rows, then share the chart. If the pattern reveals an opportunity, hand the exact context to experiment-design. If it reveals an experiment effect, switch to experiment-analyze. If it becomes a recurring KPI, ask a data owner to review the reusable metric definition.

That handoff keeps exploratory evidence distinct from the controlled measurement available through GrowthBook experimentation.

Turn chart signals into tests

Learn how strong experiment design converts an observed pattern into a hypothesis, decision metric, and trustworthy validation plan.

Review the Experiment Guide