How to use GrowthBook's MCP server to search, list, and audit fact metrics and fact tables

A metric catalog is only useful when a team can find the right definition, understand what it measures, and know whether it is safe to reuse.

GrowthBook's MCP server gives an AI client a structured way to inventory, search, and audit the fact metrics and fact tables already configured in your organization. Instead of opening several screens and comparing similar names by eye, a product manager, analyst, or engineer can ask for a scoped catalog, inspect the underlying definition, and carry stable IDs into an experiment or chart workflow.

The latest metric-search skill is intentionally read-only. It does not create a metric, rewrite SQL, or silently repair a definition. It answers three narrower questions: what exists, which object matches the user's intent, and which candidates can be charted. That boundary makes it useful as a discovery and governance layer before any consequential analytics work.

This guide follows the current GrowthBook agent skills and version 2 GrowthBook MCP server, not the older fixed-tool interface.

Understand the objects before you search

A fact table represents a business process at a defined grain: purchases, sessions, subscriptions, support contacts, or another repeatable event. A fact metric turns rows from one of those tables into a reusable calculation such as conversion rate, revenue per user, retention, or a quantile.

That separation matters. A metric called “Revenue” is not enough context on its own. You need to know which fact table supplies its numerator, which column is aggregated, which rows are filtered, how its window and caps work, and whether higher or lower values are desirable. The GrowthBook Product Analytics platform reuses these definitions across analytics and experimentation so teams do not have to maintain separate versions of the same KPI.

The underlying modeling idea is broader than GrowthBook. Microsoft's star-schema guidance emphasizes a consistent grain for fact tables, while dbt's Semantic Layer documentation describes centrally defined metrics that downstream tools can reuse. MCP does not replace that modeling work. It makes the resulting catalog easier for an agent to inspect without guessing.

Before expanding the catalog, GrowthBook's KPI playbook offers a useful way to distinguish decision metrics from guardrails and supporting indicators.

Use a simple request to start:

Use the latest metric-search skill. List fact metrics and fact tables for the Checkout project. Group metrics by fact table, show IDs and metric types, mark Official definitions, and make no changes.

That prompt provides scope, output shape, and a read-only constraint.

List the complete inventory, not the first page

The current workflow calls the fact-metric and fact-table list endpoints with pagination. Both accept limit and offset; the agent should continue while hasMore is true. A polished answer based on only the first 100 objects can be dangerously incomplete in a mature organization.

Useful server-side filters include datasource and project. Fact metrics can also be filtered by fact-table ID. Name search is different: there is no search parameter on these list endpoints, so the skill fetches the appropriate inventory and filters it locally.

Ask for a bounded inventory when you know the scope:

List every fact metric in project prj_checkout on datasource ds_snowflake. Continue through all pages. Group the results by numerator fact-table ID and include name, ID, type, description, and management status.

The current skill translates that request into paginated reads. A concrete first page and continuation look like this:

gb-call GET '/api/v1/fact-metrics?projectId=prj_checkout&datasourceId=ds_snowflake&limit=100&offset=0'
gb-call GET '/api/v1/fact-tables?projectId=prj_checkout&datasourceId=ds_snowflake&limit=100&offset=0'# Only when a response returns hasMore: true
gb-call GET '/api/v1/fact-metrics?projectId=prj_checkout&datasourceId=ds_snowflake&limit=100&offset=100'
gb-call GET '/api/v1/fact-tables?projectId=prj_checkout&datasourceId=ds_snowflake&limit=100&offset=100'

Increase offset by the page size until each endpoint returns hasMore: false. Keep the metric and fact-table pagination independent; one collection can end before the other.

Grouping by fact table exposes duplication and domain boundaries. Five conversion metrics attached to the same checkout-events table may represent legitimate variations, or they may reveal naming drift. A list sorted only alphabetically hides that relationship.

Older organizations may still contain legacy metrics from the separate metrics endpoint. The agent should list those separately. Legacy metrics remain usable in experiment analysis, but they are not accepted by Product Analytics explorations. Calling out that distinction early prevents a team from choosing a familiar metric and discovering the charting limitation later.

GrowthBook's Product Analytics GA announcement explains why the catalog now spans more than experiments: the same definitions can power visual exploration, dashboards, and experiment results. The inventory is therefore an operational dependency, not mere documentation.

Search names without pretending they are unique

Because matching happens client-side, a good agent searches beyond one exact string. A request for “orders” may need to consider purchase, checkout, transaction, and revenue. The agent should show plausible candidates instead of selecting the first substring match.

Use:

Find fact metrics related to signup or registration. Search names and descriptions with reasonable synonyms. Return every plausible match with its ID, fact table, datasource, project, type, and Official status. Do not choose one for me if multiple definitions remain credible.

IDs are the reliable handoff. Names are not guaranteed to be unique and can change. Fact metric IDs use the fact__ form. Fact-table IDs commonly use ftb_, but API-created IDs may be custom, so an audit should never discard an object solely because its prefix looks unfamiliar.

This is where MCP's structured calls improve on a general chat answer. The Model Context Protocol server model lets the client invoke a connected service and return typed data. The agent can reason about the response, but the catalog itself still comes from GrowthBook.

Make metric choices defensible

Use a practical KPI framework to separate decision metrics, guardrails, and supporting indicators before the catalog gets crowded.

Read the KPI Playbook

Inspect the definition behind a promising name

Once a candidate is identified, the skill fetches its full definition. For a fact metric, the useful audit fields include:

• metricType: mean, proportion, retention, daily participation, ratio, or quantile
• numerator fact table, column, aggregation, and row filters
• denominator configuration for a ratio metric
• inverse, when lower values indicate a better outcome
• conversion windows, caps, and other settings that change interpretation
• datasource and project scope
• managedBy, which signals governance ownership

For a fact table, inspect its SQL, supported user ID types, and column list. Each column includes a name, datatype, and deletion status. String columns may also expose topValues, which can help an agent suggest filters or dimensions.

Two caveats prevent false confidence. First, a deleted: true column is a soft-deleted remnant and should not be used for values, filters, or dimensions. Second, topValues is populated by a background job. It may be absent or stale and is only a hint, not a complete enumeration of current warehouse values.

A precise definition audit might be:

Inspect fact metric fact__checkout_conversion and its numerator fact table. Explain the calculation in plain English. Show aggregation, row filters, windows, caps, inverse behavior, user ID types, and every active column. Put deleted columns and uncertain top values in a separate watchouts section.

Once the list response identifies the numerator fact-table ID, retrieve both definitions directly:

gb-call GET /api/v1/fact-metrics/fact__checkout_conversion
gb-call GET /api/v1/fact-tables/<NUMERATOR_FACT_TABLE_ID>

The second command is not optional when the metric will be charted. It supplies userIdTypes, active columns, and topValues needed to validate units, dimensions, and filters.

The result should make hidden semantic choices visible. A proportion metric counting completed orders within seven days is not interchangeable with a mean metric summing order value over thirty days, even if both are casually described as “checkout performance.”

Audit governance, duplication, and modeling risk

The familiar Official badge corresponds to managedBy: "admin" in the current API response. managedBy: "api" indicates API-managed automation, while an empty value means the metric can be edited in the application by permitted users. There is no separate official Boolean field, so the agent should translate the API representation rather than invent one.

Official status is a useful preference signal when several candidates appear similar, but it does not prove that a metric fits a particular decision. An audit should still compare formula, grain, filters, window, and project context. It should also flag:

• duplicate or near-duplicate names with different IDs
• multiple metrics that claim to represent the same KPI
• unclear descriptions
• mismatched user ID types between related tables
• deleted columns still implied by human-facing text
• row filters that narrow the population unexpectedly
• legacy metrics that have no fact-metric successor
• API-managed definitions that require a different change process

These checks complement the broader controls in GrowthBook's guide to avoiding false positives in high-velocity experimentation: reliable decisions depend on the metric definition as well as the statistical result.

This makes the MCP output useful in a review meeting. It turns “Which revenue metric do we use?” into a compact comparison grounded in actual definitions.

An independent catalog practice helps too. The OpenLineage specification models lineage as structured metadata about datasets and jobs. GrowthBook's metric-search workflow is not a lineage engine, but the same principle applies: identifiers, ownership, and definition provenance are safer than relying on display names and tribal knowledge.

Check chartability before handing off

The skill runs three checks before promising that a candidate can become a Product Analytics chart.

First, it must be a fact metric. A fact__... object can be passed to Product Analytics; a legacy met_... object cannot. Second, the datasource must be a supported SQL warehouse. Mixpanel and Google Analytics datasources cannot run these explorations. Third, the requested metric combination must be valid: ratio metrics cannot share one chart with non-ratio metrics, and quantile metrics cannot mix with other metrics.

Ask:

Audit all Activation project metrics for chartability. Separate chartable fact metrics, legacy metrics, and datasource-incompatible metrics. Identify ratio and quantile combinations that require separate charts. Pass stable IDs to the next step, but do not run a chart.

The datasource check uses the GrowthBook data-source inventory rather than inferring support from a name. That matters when an organization has several similarly named connections or has migrated warehouses.

The GrowthBook open-source repository describes the platform's SQL-backed metric definitions and supported warehouse model. For a deeper experiment-specific metric review, the open guide to A/B testing covers goal and guardrail roles. Catalog discovery should feed those decisions, not replace them.

Turn an audit into a safe handoff

End the inventory with a structured handoff instead of a vague recommendation. Include:

1. the chosen fact metric IDs and fact-table IDs
2. datasource and project IDs
3. plain-English definitions
4. Official or management status
5. chartability result and combination constraints
6. unresolved ambiguities or deleted-column warnings
7. the next workflow and whether it is read-only or mutating

A machine-readable receipt makes the next step less likely to fall back to display-name matching:

{
  "selectedMetric": {
    "id": "fact__checkout_conversion",
    "name": "Checkout conversion",
    "metricType": "proportion",
    "factTableId": "<FACT_TABLE_ID>",
    "datasourceId": "ds_snowflake",
    "projectId": "prj_checkout",
    "managedBy": "admin",
    "chartable": true
  },
  "warnings": [],
  "nextSkill": "analytics-explore",
  "nextActionMutatesConfiguration": false
}

Preserve the implementation value managedBy: "admin" in the receipt and label it Official in the human summary. That keeps the downstream record faithful to the API while remaining understandable to readers.

For a chart, route to analytics-explore. For experiment design, route stable metric IDs to experiment-design. If the request concerns the observed results of a running test, use experiment-analyze. If a definition must be created or repaired, stop and route that change through GrowthBook rather than turning a discovery request into an undocumented write.

A strong closing prompt is:

From this read-only audit, recommend one primary and two guardrail candidates for a checkout experiment. Explain the tradeoffs and cite exact IDs. Do not edit metrics or create an experiment. Provide a separate prompt I can review for the experiment-design skill.

That preserves a visible decision boundary between understanding the catalog and acting on it.

Make metric discovery repeatable

The most valuable audit is not a one-time dump. Teams can reuse a small set of prompts before experiment planning, quarterly KPI reviews, dashboard work, or a data-model migration:

• inventory every page within an explicit project and datasource
• group fact metrics by their numerator fact table
• label Official, API-managed, editable, legacy, and unchartable objects
• compare similar candidates by definition, not name
• ignore deleted columns and qualify topValues
• carry IDs, not labels, into downstream workflows

This is a practical role for an MCP server: bring the governed objects into the product or engineering conversation while leaving their source of truth intact. The agent reduces lookup work and exposes inconsistencies. Humans still decide which definition represents the business and authorize any repair.

Protect decisions from bad metrics

Review the statistical and organizational checks that keep a familiar metric name from becoming a false sense of certainty.

Learn to Avoid False Positives