Building an Analytics Contract Your AI Agents and Frontend Can Both Consume Without Duplication
One governed metrics layer serves both agents and frontends.

For API-first and agent-first teams, a headless analytics backend should expose one governed layer of pre-calculated metrics through API and MCP, without requiring a prebuilt dashboard UI. An analytics contract defines that layer so frontends and agents share a single implementation of the calculations. Its purpose is to make consistent meaning a property of the architecture.
Why the same metric diverges when different consumers define it themselves
One engineer writes SUM(revenue), while another writes SUM(amount_captured). Both queries have valid syntax and read the right records, yet they give different figures for Q2 revenue. The records are not necessarily the problem. Each engineer has decided what revenue means on their own, so the queries give different answers even when they run correctly. Fixing data quality alone cannot make the calculations agree.
Unless a shared definition constrains it, the agent must decide which records and calculations represent the requested metric. The same fragmentation appears when sales, finance, and product maintain separate versions of ARR, leaving executives to spend decision-making time reconciling numbers. A strict data dictionary gives each metric one agreed definition across departments and agent workflows, but the architecture must also make that definition the one consumers actually use.
What an analytics contract is and what it must contain
An analytics contract is a single layer of pre-modeled, named metrics, entity relationships, and governance metadata that every consumer reads from the same source. Its metric definitions fix each calculation centrally, including calculations such as MRR and LTV. Its entity relationships specify how customers, subscriptions, and events connect, preventing each consumer from re-deriving joins. Governance metadata supplies the owner, certification status, and sensitivity classification. Being able to reach data does not mean it can be trusted.
A centrally corrected calculation propagates to the dashboards and agents that consume it, rather than requiring independent corrections in each application. MCP performs a different job by exposing that governed information to agents through a standard protocol. Resources provide governed datasets and schemas, Tools expose sanctioned operations, and Prompts provide reusable templates for analytical workflows. These primitives make the contract accessible, but they do not define its calculations or establish its access policy.
The contract therefore extends beyond a dictionary or a saved query. Its consumable unit is a modeled, pre-calculated dataset. The definition governs how the answer is produced, while the dataset gives consumers an answer they do not have to reconstruct.
Why pre-calculated datasets are the right unit, not shared queries
A shared query leaves room for callers to change filters, date ranges, and join conditions. The query string may be common while the resulting metric is not governed. Pre-calculation fixes the metric before a consumer requests it, so the frontend and agent retrieve a result whose interpretation is already defined in the model. This changes where analytical work happens. Materialized datasets can serve requests without running the calculation against the transactional database while someone waits.
For Supabase and Postgres teams, that separation resolves a specific workload conflict. Transactional row-level reads and writes share I/O with analytical aggregations and multi-table joins when both run on the same instance. Agents intensify this competition because they can issue enough queries to exhaust connection pools and crowd out transactional traffic. A separate analytical copy removes consumer requests from that production path.
Governed Parquet datasets queryable through DuckDB provide a concrete implementation of this pattern. They are inexpensive to query, separate from the production connection pool, and readable by agents and human-facing tools. Pre-calculation still requires a relationship with the source data, but answering a consumer no longer requires a fresh production aggregation. That separation makes the dataset, rather than a reusable SQL statement, the appropriate contract boundary.
How MCP exposes the contract to agents without giving them raw database access
The semantic layer makes metric meaning trustworthy, while MCP makes the contract accessible to agents. Without a standard protocol, teams must build a separate integration for each pairing of an agent framework and a data source. MCP replaces that pairing-by-pairing approach with a common interface. A Host, such as Claude or a custom agent, interacts with a Client that negotiates the protocol. The Server exposes discoverable capabilities and is the layer data teams own and govern.
That server must make the contract available to agents rather than just pass along a raw database credential. Atlan’s governed MCP pattern distinguishes protocol delivery from authorization, because faithfully returning everything a credential can reach does not create a security boundary. A governed server returns only what the requesting identity is entitled to see, together with ownership, certification, and sensitivity metadata. The access decision belongs between the agent and raw data. When multiple agents or model providers need the same sources, that boundary avoids rebuilding access logic for every pairing.
The July 2026 MCP specification adds a stateless protocol core, so remote servers can run behind a plain load balancer without sticky sessions or a shared session store. Separately, Mcp-Method headers support per-operation routing without inspecting request bodies. Clients can also cache tools/list responses to reduce repeated discovery overhead. These features support concurrent agent traffic, but scaling transport does not replace governing the data behind it.
Defining access policy before wiring a connection, not after
Atlan describes a recurring access pattern in which a pilot receives a broad credential to unblock work, then retains that scope because nobody revisits it. Temporary convenience becomes the permanent permission boundary. Once the connection works, authorization is treated as unfinished cleanup, with access already granted. That sequence gives the agent whatever the credential can reach, potentially exceeding what the person requesting the analysis may see.
The appropriate sequence begins before any connection exists. A specific identity with a defined scope should replace a generic service account as the basis for permissions. Agents should not have direct write access to production databases, where faulty logic, unexpected input, or prompt injection can corrupt data at machine speed. Infrastructure should also collect structured, tamper-proof transcripts of agent-data interactions instead of relying on the agent to report its own activity.
The Open Agent Passport paper describes the gap as a pre-action authorization problem. Model alignment is probabilistic, while post-hoc evaluation occurs after execution, so neither provides deterministic policy enforcement at each tool call. Authorization must precede the action it constrains. The same infrastructure can enforce capability scopes, spending limits, operational contracts, and quality gates, connecting security policy with the analytics contract.
What breaks when agents query production Postgres directly instead of the governed layer
Direct agent access to production Postgres exposes three distinct failure modes, namely workload interference, permission boundary risk, and definitional drift. Workload interference begins when full-table scans and large aggregations consume shared I/O and hold locks on the instance serving transactional requests. An agent issuing many such queries can exhaust the connection pool. Transactional reads and writes then slow down or get blocked, even when the agent is doing valid analytical work.
A broad credential can let an agent past the intended boundary, and even row-level security with the right scope can make queries cost more than expected. For example, per-row evaluation of auth.uid() repeats work across the result set, whereas expressing it as a scalar subquery allows the planner to evaluate it once. An agent querying raw tables may not use that optimization every time.
Definitional drift occurs when the agent reconstructs each metric from raw records, repeating the independent interpretation that produced conflicting revenue figures. A pre-calculated dataset fixes the calculation in the consumed data rather than leaving it as documentation beside the query. A separate governed copy also keeps analytical requests away from the transactional instance, addressing a bottleneck that protocol scaling cannot fix. Cold data and reporting queries belong outside the hot path, in the analytical contract.
What analytics backend gives frontend and agent consumers the same API-first contract
Headless analytics describes data infrastructure decoupled from any single frontend and accessible through MCP or API. It suits teams that need full API control without an opinionated dashboard interface because it keeps presentation separate from metric definition. The frontend and agent can differ in how they interact with users without differing in what they consume. Their shared boundary is the governed materialized layer.
In practice, the dashboard must read the same pre-calculated dataset as the agent. The API and MCP server must expose the same named metrics rather than parallel implementations that usually agree. Each response should include ownership, sensitivity, and certification metadata so consumers can judge whether to trust it. Transport can differ without duplicating the contract. A central MRR correction then propagates through the shared source rather than demanding a frontend deployment, an agent re-prompt, and a dashboard republish.
For Supabase builders, the intended arrangement extends the existing Postgres project with pre-modeled analytical datasets while leaving production schemas unchanged. Those datasets read from the transactional source and serve consumers separately, without requiring the team to maintain an ETL pipeline or new infrastructure. The relevant design criterion is whether API and MCP access converge on that same governed layer. Raw API access is useful only if obtaining it does not require rebuilding metric semantics in the client.
Pushing metrics to where people work rather than waiting for someone to pull them
Pre-calculated metrics exist before anyone requests them, which makes proactive delivery a natural extension of the contract. Email, Slack, and phone notifications can send results that already exist without computing the metrics when they are sent. Recipients do not need to navigate to a dashboard. Founders, operators, and agents running scheduled workflows can receive the governed data where their work already happens.
A nightly revenue summary, a weekly churn signal, or an alert on a threshold crossing can read from the same pre-calculated datasets used for dashboard review. An ARR figure in a Slack digest does not need a separate calculation from the ARR figure in an agent summary.
What early-stage teams actually need to stand this up without a dedicated data function
Small teams have little time to make competing metric definitions agree or to keep separate analytical systems running for agents and humans. A governed contract addresses that constraint through a modeling decision that requires no large engineering program. Most seed-stage startups do not need a dedicated data person to begin with a small set of well-defined metrics. Scope is the practical starting point. A limited, coherent catalog is more useful than a broad collection whose definitions vary by consumer.
The alternative patchwork includes a BI tool for dashboards, a separate prompt-engineering layer for agents, and ad-hoc queries for individual analyses. Each introduces another place where meaning can diverge and corrections must be repeated. For a Supabase team, pre-modeled datasets drawn from the existing source of truth and served through a single MCP server reduce that fragmentation without requiring production schema changes or an ETL pipeline to maintain. The work is to establish definitions, relationships, ownership, and access policy in the shared layer.
Data that agents cannot reliably interpret or trust poses a greater risk than insufficient data. A contract addresses that risk only when it becomes the ordinary route to an answer, rather than optional documentation bypassed under deadline pressure. Governed access must be the easier default path. That is how one analytics layer replaces recurring reconciliation with a structure in which neither the frontend nor the agent needs to define revenue again.


