# Semantic layer MCP tools - Docs

The [PostHog MCP server](/docs/model-context-protocol.md) is how agents work with the semantic layer. This page is the reference for the semantic layer's tools – they're alpha-only, so they don't appear in the [general MCP tools list](/docs/model-context-protocol/tools.md) yet, and they only show up in your client when the alpha is enabled for your organization.

This works in any MCP client – Claude Code, Claude Desktop, Cursor, Codex, Windsurf, VS Code, and others. Install with the [AI wizard](/docs/ai-engineering/ai-wizard.md) (`npx @posthog/wizard mcp add`) – see the [MCP server docs](/docs/model-context-protocol.md) for full setup instructions.

**The semantic layer is in alpha**

The semantic layer is in alpha, enabled per organization for a small group of customers. There's no dedicated UI yet – you work with it through MCP tools and SQL. Tool names and behavior may change between releases. Found a bug, or want access? [Contact support](https://app.posthog.com/home#supportModal) and mention the semantic layer alpha.

## Catalog-first routing

With the semantic layer enabled, the MCP server changes how agents answer metric questions. For any named business measure or KPI – revenue, MRR, activation, retention, conversion, including breakdowns and comparisons of them – the agent:

1.  Searches `system.information_schema.metrics` for a matching governed metric
2.  If exactly one `approved`, non-drifted match exists, runs it with `data-catalog-metric-run`
3.  If several materially different approved matches exist, asks you which one and stops
4.  Otherwise falls back to raw queries – and labels the result **noncanonical**

This routing takes precedence over the agent's generic query-writing behavior. The effect: governed definitions win by default, and you always know when a number is a one-off derivation instead.

## Metric tools

| Tool | What it does | Confirmation | Scopes |
| --- | --- | --- | --- |
| data-catalog-metric-run | Runs a governed metric. Executable metrics return results, the compiled query, and a posthog_url deep link; markdown metrics return calculation steps in instructions. Accepts date_from/date_to/interval overrides (rejected for HogQLQuery metrics) and a refresh cache option. | – | data_catalog:read, query:read |
| data-catalog-metric-create | Creates a metric, or refines the one already holding that name (upserts on name). Always lands proposed. The definition is an executable query or a MarkdownDefinition. | – | data_catalog:write |
| data-catalog-metric-update | Updates a metric's fields. Editing an approved metric's definition resets it to proposed. | – | data_catalog:write |
| data-catalog-metric-approve | Blesses a metric as canonical. Blocked while the metric is drifted from its source insight. | Typed "confirm" | data_catalog_approval:write, data_catalog:read |

There's deliberately no "list metrics" tool: agents discover metrics with `execute-sql` over `system.information_schema.metrics` – see the [SQL reference](/docs/semantic-layer/query.md).

## Certification tools

| Tool | What it does | Confirmation | Scopes |
| --- | --- | --- | --- |
| data-catalog-certification-propose | Proposes a trust mark on a warehouse table or view. Address the target by id or by name – an ambiguous name returns the candidate ids to pick from. | – | data_catalog:write |
| data-catalog-certification-certify | Marks a table or view as certified (prefer this source). | Typed "confirm" | data_catalog_approval:write, data_catalog:read |
| data-catalog-certification-deprecate | Marks a table or view as deprecated (avoid this source). | Typed "confirm" | data_catalog_approval:write, data_catalog:read |

## Relationship tools

| Tool | What it does | Confirmation | Scopes |
| --- | --- | --- | --- |
| data-catalog-relationship-propose | Proposes a reviewed join between two warehouse tables, with confidence and sampling evidence (match rates, sample values). Proposals are deduped regardless of direction. | – | data_catalog:write |
| data-catalog-relationship-accept | Promotes a proposal to a real [warehouse join](/docs/data-warehouse/join.md), after re-validating and probing it. | Typed "confirm" | data_catalog_approval:write, data_catalog:read, query:read, warehouse_view:write |
| data-catalog-relationship-reject | Rejects a proposal. Permanent – the pair is never re-proposed. | Typed "confirm" | data_catalog_approval:write, data_catalog:read |

## Example prompts

Try these with your MCP-enabled agent:

-   `What governed metrics do we have around revenue?`
-   `Run the mrr metric for the last 6 months, monthly.`
-   `Create a semantic layer metric named weekly_active_teams from the "Active teams" insight.`
-   `Show me the compiled query for weekly_active_teams, then approve it.`
-   `Certify stripe_charges as the source of truth for payments, and deprecate payments_backup with a note that it's stale.`
-   `Propose a relationship between orders and stripe_customers on customer_id, with sampling evidence.`
-   `List every proposed metric waiting for review.`

### Community questions

Ask a question

### Was this page useful?

HelpfulCould be better