Semantic Metric Naming as the Safety Contract Between Agent Query Intent and Supabase Execution

Named metric contracts keep agents from improvising business logic on Supabase.

· 9 min read
Cover illustration for “Semantic Metric Naming as the Safety Contract Between Agent Query Intent and Supabase Execution”
MCP Data Layer · November 19, 2026 · 9 min read · 1,930 words

Governed data access for AI agents on Supabase via MCP requires a semantic layer over pre-modeled, materialized datasets. Semantic metric naming is the safety contract that binds an agent’s intent to approved calculations, grain, filters, and permissions. An MCP server puts that contract to work by giving the agent named metrics and governed query tools while keeping production Supabase out of the agent’s query path.

Why agents writing their own SQL is a governance problem, not a prompt-engineering one

An agent answers “what was revenue last quarter?” with three different numbers across three sessions. Each query runs successfully against Supabase, yet each interprets revenue differently. One uses the wrong join, another ignores the time-zone convention, and another chooses a different calculation. Successful execution does not establish business correctness. The failure is silent because valid SQL can return a plausible but incorrect answer.

Cube’s 2026 semantic layer guide distinguishes two forms of metric hallucination. Metric-definition drift occurs when the agent invents or changes the business calculation. Post-query language-model error happens when it misreads a value that was returned correctly or adds an explanation that the data does not support. These failures require different controls. A semantic layer directly constrains the first, but the second still requires validation.

Fan-out joins, slowly-changing dimensions, and several customer tables that could fit give an agent more than one path to a result that looks right. Access brings a separate governance risk because a query that returns another tenant’s rows can look just as correct to the model. More prompt examples cannot enforce these boundaries. SQL provides access to data, with authoritative understanding of its meaning and permission to disclose it remaining separate requirements.

What a semantic layer actually changes, and what it does not

A semantic layer encodes business meaning before an agent asks a question, so the agent selects governed definitions. It contains two distinct components, a semantic model and metric definitions. The model sets out the entities, relationships, columns, and synonyms. It explains what the data represents. For example, it can establish that a column represents order value without establishing whether revenue is gross, net, recognized, or net-of-refunds.

Metric definitions supply that missing calculation contract through formulas, filters, grain, aggregation, and time behavior. With those definitions enforced, the layer constrains metric-definition drift and join-path errors because the data team has already settled the valid calculation. Access policies must also be enforced in the query path to constrain unauthorized row access. Descriptions alone do not provide that protection. A model that explains the schema but leaves metric construction and permissions to the agent has not closed the governance gap.

An agent can still misread the result even when the definition is correctly enforced. Nor can it stop an unsupported narrative merely by returning the right number. The layer instead preserves named definitions, lineage, and the generated query so those errors become easier to test. The practical goal is bounded execution with traceable answers.

How metric names become the enforcement boundary rather than a documentation label

A metric contract connects a plain-language business definition to the rules required for execution. Its calculation specifies the formula, any numerator and denominator, filters, time logic, and aggregation behavior. Its grain establishes whether the number is valid at customer-day, account-month, or order-line level. Allowed dimensions specify which slices are valid and which would double-count. Access rules, freshness expectations, and lifecycle state complete the contract by defining who may use it, how current it should be, and whether it is draft, certified, deprecated, or restricted.

The name is the resolution key for that contract. When an agent selects net_revenue_recognized, an enforcing layer uses the associated definition rather than allowing the agent to substitute gross revenue, include refunds, or change the time-zone convention. The spelling alone enforces nothing. Enforcement happens when resolution binds the request to the approved calculation and access rules and leaves the agent no other path through which to replace them.

That binding also establishes refusal conditions. A contract can rule out gross revenue for customer-level churn analysis because it includes one-time fees, or disallow campaign slices before a date when attribution becomes reliable. A vague or duplicated name defeats this mechanism because it no longer resolves to a single canonical definition. Naming therefore becomes an execution boundary only when the resolved contract governs what the system will run.

The concrete failure that results when metric names are absent or inconsistent

Consider the startup discrepancy between SUM(revenue) and SUM(amount_captured). One engineer uses the first, another uses the second, and Q2 revenue differs until an investor asks for audited numbers. Both expressions can execute without error. The disagreement arises because the shared business term has no single governed calculation, leaving the team to argue about definitions when it should be discussing decisions.

JSONB creates a similar failure at the extraction step. When a key field has no governed extraction definition, each person maintains a query to unpack it. Five extraction paths that differ a little give five numbers that differ a little. The workaround becomes the unofficial metric system. Separate implementations in a dashboard, notebook, API, and agent prompt then give the same label several competing meanings.

Agents accelerate this duplication because a scheduled scan can re-derive the number on every run. Each execution becomes another opportunity to select a different path, rather than a repeatable use of one approved definition. The drift can be immediate and invisible. A CEO dashboard may then combine ARR from billing, cash from the bank, and usage from a separate export without a consistent contract for explaining the numbers when challenged.

What well-named metrics look like in a Supabase-backed system

For a Supabase team, the corrective discipline is to make each metric name and definition unambiguous to both human reviewers and agents. Grain belongs in the name or its associated definition. mrr_per_account_monthly establishes context that revenue does not. With the latter, it is unclear whether the calculation belongs at the order, account, or cohort level. That uncertainty affects which joins and slices are valid, so it cannot remain an inference made at query time.

Calculation variants need distinct contracts. revenue_gross, revenue_net_of_refunds, and revenue_recognized identify distinct business numbers. Time behavior must be just as precise because a calculation that uses the contract start date differs from one that uses the invoice date. Lifecycle state must guide resolution as well. A deprecated or restricted metric should not remain an apparently valid choice simply because its name resembles the user’s request.

Postgres-specific definitions must extend through JSONB extraction to the tested source. Rich state in JSONB lacks schema-enforced field names, so a contract must explicitly identify the extraction path rather than leaving analysts and agents to reconstruct it. Schema hygiene and metric naming are inseparable here. A precise metric name pointing to an ambiguous column still leaves the calculation unsettled. For a B2B SaaS team, the recommended starting point is five fully contracted metrics, such as ARR, churn, CAC, LTV, and gross margin.

Why pre-modeled, governed datasets are the only safe surface for agent queries against Supabase

A named contract cannot govern execution if the agent can bypass it and query raw production tables. In this architecture, names must resolve to pre-modeled, materialized datasets. That separation protects more than calculation consistency. Transactional Postgres favors fast, random, row-level reads and writes, while analytical workloads favor sequential scans, large aggregations, and multi-table joins that consume shared I/O and can hold locks for seconds or minutes.

Agent workloads make the conflict harder to ignore. A founder who checks revenue now and then and an agent that runs an event-table scan again and again may both send ordinary queries, but the load they add over time differs. Direct production access risks connection-pool exhaustion as well as row-level security bypass. Naming cannot prevent those failures by itself. The workload boundary and the permission boundary must hold whether or not the agent chooses a sensible metric.

Supabase’s documentation provides a related, specifically scoped warning for its analytics server, Logflare. The server supports Postgres or BigQuery as a backend, but the documentation states that the Postgres backend is not yet optimized for high-volume inserts or heavy query use. Supabase recommends BigQuery for production self-hosting of that server. This scoped warning reinforces the need to separate demanding analytics from transactional work.

For agent analytics, the recommended surface is governed Parquet datasets queryable through DuckDB, with metrics calculated and materialized ahead of time. Analytical requests then avoid the transactional database at query time. Freshness remains part of the contract. The served number must have a defined expectation for currency, just as it has a defined calculation and access policy.

How can AI agents query Supabase data through MCP without direct database access?

MCP makes the governed metric store available to agents through a standard interface. Its resources provide context such as schemas, governed datasets, and metric definitions without executing live queries. Its tools allow queries against the pre-modeled layer. Its prompts provide reusable templates for repeatable analytical workflows. These primitives deliver approved meaning and bounded execution without requiring agents to connect to production Supabase.

The order of construction is decisive. Data must be modeled and governed before the MCP server exposes it, because the protocol does not create metric definitions or repair ambiguous tables. A server over raw data simply offers another route to the same definition-drift problem. Protocol access is not semantic governance. Likewise, row-level restrictions must be enforced below the semantic model rather than entrusted to an agent’s interpretation of tool descriptions.

For server selection, the decisive criteria are access to certified metrics, enforcement of tenant and row-level policies, and query execution against governed datasets. A generic database connection is not equivalent to that arrangement. dbt Summit 2026, formerly Coalesce, presented the dbt Semantic Layer with MetricFlow and an MCP server together as governed context for agents. The presentation positioned the semantic layer as both AI infrastructure and a BI feature.

Six controls that make semantic metric naming an operational safety practice

The first control is to define metrics outside the prompt in a versioned semantic model owned by the data team. Measures, dimensions, joins, grains, and time behavior belong there. The second is to require selection of certified objects. Agents should discover approved metrics and dimensions by name instead of generating free-form SQL against raw tables.

The third control is to compile permissions into every query, with tenant, row-level, column-level, and role-level policies applied below the semantic model. The fourth is to return evidence with every result, preserving the metric definition, filters, dimensions, time range, model version, and query identifier. That evidence allows a person or another agent to reconstruct the numerical claim.

The fifth control is known-answer evaluation against values verified by the data team. Tests should include ambiguous wording, subtle joins, empty results, and denied-access cases alongside straightforward successful requests. The sixth is to require support for narrative claims. When an agent explains why a metric moved, it must query the dimensions that bear on the change or label its explanation as a hypothesis to guard against the post-query error that semantic enforcement alone cannot stop.

These controls work as a combined system. For a team starting from scratch, the recommended sequence is to lock five canonical metric contracts, expose them through a governed layer and a single MCP server, and run known-answer evaluations before expanding. That disciplined start enables recurring analytical work, including scheduled reports, investor-ready KPI packs, and usage summaries, without a data engineer reviewing each query. The contract makes useful autonomy possible because the agent can choose an approved question without also inventing what its answer means.

Filed underMCP Data Layer

More in MCP Data Layer