Semantic layer MCP tools
Contents
The PostHog MCP server 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 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 (npx @posthog/wizard mcp add) – see the MCP server docs for full setup instructions.
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 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:
- Searches
system.information_schema.metricsfor a matching governed metric - If exactly one
approved, non-drifted match exists, runs it withdata-catalog-metric-run - If several materially different approved matches exist, asks you which one and stops
- 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.
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, 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.