MCP Tool Design for Metric Queries vs Raw Data Access

A headless analytics platform for API-first and agent-first teams should expose governed metrics through APIs and MCP without requiring an opinionated frontend. For production metric queries, pre-modeled, intent-shaped tools are a stronger foundation than a raw database connection because they keep business definitions out of the model’s reasoning.

Why the interface between an agent and data is an engineering decision, not a configuration detail

execute_sql(query) looks like the shortest route from an agent to useful data. One tool takes any question the model can turn into SQL, so the server seems to have little to do beyond running it. The model must handle schema discovery, relationship inference, business-rule interpretation, and result validation itself, instead of relying on the application to get them right.

Bartolomeo Bogliolo’s August 2026 paper, From SQL Generation to Tool Selection, compares raw SQL execution, a thin generic tool pack, and a domain-oriented pack. The domain-oriented design achieves higher accuracy, while the generic pack performs worse than raw SQL. Adding tools is not itself an improvement. MCP standardizes how an agent interacts with a server, but the server’s interface determines what the model must work out unaided. Engineers therefore need to decide what to expose instead of a generic query surface and which responsibilities that interface should keep in software.

What makes a generic SQL tool fail at the model layer, mechanically

Before answering a revenue question, the model must discover the schema, infer relationships, choose the relevant business definition, and construct a query. It must then assess the result. These responsibilities are cheaper to guarantee deterministically in software than to resolve afresh for every request. Raw SQL access assigns too much routine application logic to probabilistic reasoning.

The distinction becomes clear when several tables appear to contain revenue. Knowing SQL does not tell the model which table the finance team uses or which business rules distinguish booked revenue from captured payments. If there is no metric contract, one agent can write SUM(revenue) while another writes SUM(amount_captured). Both expressions can look reasonable to the model. Their disagreement is a definition problem.

A generated query that works against today’s schema can fail after a column rename, without the model having a reliable way to detect the change in advance. Broad credentials create a separate structural weakness. A production read/write connection does not stop needless joins across sensitive tables or make agents use the abstractions that human engineers built for them.

The cost also extends beyond incorrect answers. Agent queries can exhaust Postgres connection pools, and adding MCP server instances does not remove that database bottleneck. Repeated schema exploration consumes the context window before the model reaches the actual question. Chawla’s March 2026 comparison documents an MCP approach costing roughly 100× the token count of a pre-aggregated equivalent for a simple aggregation task. The comparison illustrates the price of making an agent discover what the data layer could already know.

The three architectural invariants that separate a governed metric tool from a query wrapper

Bogliolo’s Domain-Oriented Tooling Pattern places three constraints on the interface. Schema navigation and business rules stay on the server, the server exposes a small set of domain-aligned operations, and the model selects intent. These constraints change the division of labor. The model interprets the request, while deterministic software supplies the joins, filters, and definitions needed to answer it.

MCP Blueprint, the paper’s reference implementation, defines tools through YAML metadata paired with pre-authored parameterized SQL files. The SQL contains the joins and business rules, rather than serving as an example the model is free to rewrite. The model fills parameter slots. This is a different contract from a wrapper that accepts arbitrary SQL and forwards it to the database.

Operations such as “retrieve metric contract,” “run governed metric query,” and “compare current value to baseline” express analytical intent. The surrounding taxonomy includes describing an approved dataset, checking table freshness, inspecting lineage for an asset, and requesting workflow approval. Each operation has clear limits on what it does in the analytical workflow. The taxonomy is useful because those boundaries correspond to work the server can perform reliably.

Intent selection completes the pattern by narrowing what the model must decide. It chooses the relevant operation and supplies parameters within the tool’s scope. Business context belongs in that same contract. Team defaults, project scopes, and output constraints are encoded in the tool definition instead of being left for the agent to discover or the user to repeat. A governed tool therefore constrains both how a metric is computed and the context in which that computation is valid.

Why metric definitions must be part of the infrastructure, not the prompt

If “active user” is computed differently in three places, a tool taxonomy can make those computations easier to reach without making them agree. The definition must come first. Dmitry Korzhov, AI Product Lead at Improvado, states the dependency directly. “MCP does not remove the need for a governed data layer. It makes the governance more important, because AI agents will expose every naming gap, permission gap, and metric-definition conflict faster.”

A prompt annotation or wiki page leaves the definition separate from the computation that produces the answer. A strict data dictionary instead gives each metric one source and one definition that live in the data infrastructure. That binding prevents a second interpretation from becoming an alternative implementation. Where an agent-facing description sits in the same file as the SQL that produces a column, it avoids the separation that allows independently maintained documentation to drift.

Agents query metrics through the same headless analytical layer that dashboards use, so both use the same definitions instead of writing their own SQL for the same question. Frontend freedom does not require semantic freedom. A team can choose how to connect to the API and show the results while keeping each client from deciding for itself what activation or retention means. This is the central distinction between raw API access to governed analytics and raw access to underlying tables.

For Supabase teams, the definitions naturally begin with Postgres as the system of record. ARR comes from the billing tables, activation comes from the event tables, and retention comes from the session tables. Yet the source of truth need not be the execution target. Analytical queries should run against a governed copy instead of the production database, so they stay tied to source definitions and leave production connection pools free for writes. The architecture separates where a metric originates from where agents consume it.

How the stateless MCP spec changes what a governed tool layer must handle

The MCP 2026-07-28 revision removed protocol-level sessions. The tool tier can therefore scale like a stateless web service, while identity and long-running state must live in durable systems below it. This changes where governance can reside. A metric contract may be exposed through an MCP tool, but the stateless server cannot itself be the durable home for the definitions, permissions, query jobs, and approvals that govern execution.

The distinction is especially important for work that outlasts a single request. A query job and an approval belong to the governed backend rather than to whichever MCP instance received the initial call. Identity has the same architectural requirement. The server translates a tool request into a call to that durable system, while the backend retains the state needed to apply the metric and permission contracts. The protocol boundary is not the storage boundary.

Statelessness also removes the need for sticky routing. More than one server instance can sit behind a round-robin load balancer, which fits agent workloads that scale in different ways from human workflows. But making the tool tier easier to scale does not let Postgres handle more connections. A durable analytical backend remains necessary to separate agent traffic from transactional writes. The protocol simplifies request handling while making the distinction between an interface and its underlying governed system more explicit.

The strongest objection to governed tools and where it actually applies

A predefined metric catalog cannot anticipate every useful question. An analyst investigating an unfamiliar relationship may need data that no existing contract exposes, and a narrowly scoped tool can return nothing useful for that task. Exploration needs room to depart from established questions. Raw SQL preserves that freedom, so a design that removes it everywhere would trade analytical reach for consistency even where consistency is not yet the goal.

The transport also depends on the integration. Chawla describes CLI with DuckDB as a legitimate choice for a developer tracing ML predictions locally, where JSON-RPC overhead adds nothing and models benefit from their training on shell commands. That is a different task from answering a production reporting question. A local exploratory workflow does not automatically need the same interface as an agent serving non-technical users. The useful distinction is between discovering an answer and retrieving a metric whose meaning has already been agreed.

Execution and context can also come from different surfaces. Warehouse servers provide flexible execution, catalog servers provide metadata and lineage without execution, and pipeline servers let an agent trace a number back to its source. Those capabilities can complement one another without making unrestricted querying the default.

The resulting architecture has two layers with different contracts. Governed, intent-shaped tools serve production metric queries, non-technical users, and AI-generated reports, where definitional accuracy is essential. Analysts who work beyond the catalog use a separate exploration surface. That surface has strict limits on permissions and scope and is audited, while agents use a different route by default. The resolution preserves both stable reporting and the freedom to develop the next governed metric.

What analytics backend fits a Supabase team without a dedicated data function?

A Supabase team in this position needs a headless analytical backend. The backend pre-models metrics, exposes them through APIs and governed tools, and leaves presentation to the team. No prebuilt dashboard UI is required for the agent. The same backend can nevertheless answer dashboard queries, because its value lies in shared definitions.

Metrics are modeled ahead of time and stored as governed Parquet datasets, which DuckDB can query through its columnar-vectorized engine without requiring a separate warehouse or ETL infrastructure. A read replica keeps analytical work against Postgres separate, while agents query the governed datasets for metrics. Production writes remain on a different execution path. This arrangement keeps the schema as the anchor for definitions without exposing the production connection pool to agent queries.

A single MCP server then presents the governed operations, including dataset description, metric-contract retrieval, governed query execution, freshness checks, and lineage inspection. Human-facing interfaces use the same definitions, so what Claude reports does not diverge from what a chart shows because of separately authored metric SQL. For a team without a dedicated data function, the infrastructure requirement is therefore a backend that owns this governed layer.

Bogliolo calls the resulting reduction in model responsibility Model Demotion. Because the tool handles schema navigation and business rules, even a small model can classify intent and fill parameter slots correctly, so routine requests can use a lower model tier. The benefit extends beyond the current agent. Human teammates, future agents, and investor reporting can all draw from the same metric definitions. The lasting return on MCP tool design is a single source of truth that does not have to be reinvented whenever a new interface asks the same business question.