MCP Tool Contracts as the Runtime Execution Boundary for Agent Analytics Queries Against Supabase
Governed metrics at the tool boundary protect analytics accuracy without exposing raw data.

Governed data access for AI agents on Supabase via MCP requires a server that exposes pre-modeled metrics. The MCP tool contract must govern which metrics an agent may invoke, whose data it may see, and what results it may receive. When enforced at runtime, that contract is the main boundary for safety and accuracy, while analytical execution stays off production tables that serve application traffic.
Why MCP's design as a connector leaves analytics queries ungoverned by default
MCP can look like governance because it gives tool access a defined structure. An agent discovers named tools and invokes them through a standard interface, rather than reaching into a system without an explicit calling convention. But structure is not permission. The protocol standardizes how a call is made without itself deciding whether that call should touch production data, aggregate sensitive rows, or return a number with an approved business definition.
The distinction is between connection and execution. MCP tells a system which tools exist and how to call them, while runtime controls determine what those calls may actually do. Without other constraints, an agent connected to a Supabase project can read raw tables, issue arbitrary aggregations, and return figures based on its own interpretation of the schema. None of that necessarily produces a protocol-level error. A valid tool invocation can still be an unsuitable analytics operation.
MCP’s roadmap acknowledges that connecting a model to a tool was the easy part. The harder system includes jobs that outlive requests, callers that are not people, authority that must narrow during delegation, and tool catalogs too large for every prompt. Analytics adds a related requirement, namely that permission to call a tool must not become permission to invent a metric. This is a governance responsibility that the connector alone does not fulfill.
What Supabase's MCP server actually exposes to an agent with no contract in place
Supabase’s official MCP server exposes eight tool groups spanning schema inspection, query execution, table management, log reading, and debugging. That is a developer’s project surface. Its connection controls limit access through a read_only flag, project_ref pinning, and feature-group selection. The flag demotes the agent to a read-only Postgres user, while project pinning confines the connection to one project. Feature groups are selected through the connection URL for the hosted server or CLI flags for the local stdio server.
A read-only agent can still issue full-table scans, join raw event tables, and calculate metrics using arithmetic inferred from column names. Read-only does not mean analytically governed or operationally harmless. The flags answer questions about the connection’s reach, but not whether a churn calculation reflects the business’s agreed definition.
The service role key bypasses all Row Level Security policies and provides unrestricted database access, making it appropriate for migrations and administrative tasks but not an agent session interacting with user data. The anon key operates within RLS policies, so an agent using it can reach only rows permitted by the application’s security rules. An agent can follow every rule governing row visibility and still get ARR wrong.
Supabase announced an MCP server for apps on October 22, 2026, distinct from its developer server. It exposes selected product actions to a customer’s agent, with tool calls using that customer’s Supabase client so that RLS determines row access. This is a different interface from a general developer database console. For customer-facing access, selected actions and customer-bound RLS more directly control what the agent can reach, but analytics still needs governed metric definitions and rules for what it can return.
Why running analytics queries against production Postgres is the wrong execution target regardless of MCP
Postgres will execute an agent’s aggregation when permissions allow it. That does not make the production instance serving the application the right execution target. Whether humans or agents run analytics, OLTP and analytical workloads compete for resources, share connection-pool limits set for application sessions, and put analytical compute on the instance whose latency affects end users. Connection scope cannot resolve that workload conflict.
Supabase recommends a read replica to resolve contention. A replica nevertheless runs at the primary’s compute size, bills separately without the plan’s compute credits, and adds disk at a multiple of the primary’s size, roughly doubling database spend for the analytical benefit. It remains only a partial answer. The replica still executes raw queries against raw tables, so an agent without a semantic layer continues to supply its own business logic.
How can governed metrics be exposed without letting an agent touch production Supabase tables?
Instead of exposing tables from which an agent constructs an answer, the server exposes approved metrics whose definitions already exist. The execution target changes from raw data to governed results. That lets the contract control row visibility, which metrics are available, how they are defined, and what the agent may receive.
The semantic layer defines ARR, churn, CAC, LTV, net revenue retention, and other KPIs once. Humans and agents then consume those definitions rather than recreating them inside dashboards, individual tools, or generated queries. An agent’s ability to explain a calculation is no substitute for that calculation matching the definition the business approved.
If a tool exposes the pre-calculated field active_users under a governed definition, the agent cannot replace it with “active users computed my way” through the same tool. The permitted answer is already bounded. This depends on the tool being able to call only named, pre-approved metrics, with arbitrary query access unavailable.
The pre-modeled layer is therefore more than a scoping convenience. It makes the contract enforceable by giving each permitted operation a defined analytical meaning and a constrained result. The agent may choose an approved metric but has no right to rewrite its calculation. That is the architectural shift from a connector to an execution boundary. For the boundary to work, though, the system must check the actual tool invocation before it runs, rather than trust the model to follow the contract on its own.
The Policy Enforcement Point at the tool-call boundary and how it operates
The Policy Enforcement Point sits after the model has committed to a tool name and arguments but before execution. At that moment, the system has a concrete action to evaluate and can still stop it. The model’s explanation has no say in the outcome.
Wang, Zhu, and Li’s peer-reviewed Runtime Policy Enforcement for MCP-Based LLM Agents demonstrates this mechanism through three cooperating components. Its RuleEngine evaluates calls against declarative rules covering path scope, sensitive outbound data, high-risk tool access, cross-server taint, and per-tool rate caps. Its LabelTracker propagates coarse source-integrity (SI) and data-sensitivity (DS) labels across the trace. Its AuditLogger writes every decision into a tamper-evident SHA-256 hash-chained log. Together, these components connect the immediate call decision with information from the wider trace and a record of the outcome.
The critical property is deterministic enforcement independent of the model’s reasoning. Applied to analytics, an agent might justify a raw revenue-table query as necessary to verify ARR. A contract that permits only the governed arr_monthly metric endpoint would block that call despite the plausible explanation. The justification confers no additional authority on the agent. This example illustrates how the research’s enforcement pattern applies to an analytics contract, rather than implying that the research itself supplies a Supabase metric layer.
In the strongest representative variant, delimiters, data-marking, and encoding schemes cut attack success only a little and do not cut user-guided sensitive-data exfiltration or high-frequency tool abuse at all. Those classes use instructions that look legitimate or patterns in how often calls are made, which prompt conventions cannot stop once a call is issued. The mechanism also operates at a real MCP boundary with a sub-millisecond execution-path increment for a local server. Runtime enforcement need not impose a substantial per-call latency penalty.
What the tool contract must specify to function as an analytics execution boundary
A functioning analytics contract specifies four things, namely approved metrics and definitions, identities permitted to invoke tools, permitted return values and their form, and the audit treatment of every call. These are requirements for the execution path. A tool named for ARR is not governed if it still accepts arbitrary logic that changes what ARR means. The contract must bind the callable operation to the approved definition.
The first design decision is tool scope. An analytics agent should see only tools relevant to its task. For ARR, churn, and CAC, that means offering approved metric operations rather than a general query tool that lets the agent work out each number from raw tables. A narrow scope leaves less room for accidental misuse and adversarial prompt injection. It also keeps the tools on offer from quietly turning the analytical task into general database work.
Identity scope then sets whose metrics those operations may return. RLS governs row visibility by user identity, while the analytics contract governs metric visibility by agent role. The two controls must work together. An agent in a customer’s session should have access only to that customer’s metrics, with company-wide ARR out of reach even when the governed layer has both. An approved metric definition does not make every result appropriate for every caller.
Return-value governance constrains the answer as well as the request. The contract must specify the shape and granularity of permitted output, so an approved churn or CAC operation does not become a route to underlying row-level data. When a tool returns only pre-calculated scalars, that output cannot include the dataset’s individual rows. A scalar result can be inappropriate for a caller even when it reveals no individual record.
The tool, arguments, issuing identity, and decision, whether allowed, blocked, or escalated, must enter a tamper-evident log. That record is what lets a team trace an agent-generated figure back to the invocation that produced it when a report informs a business decision. Metric provenance requires more than retaining the final answer. It requires retaining the governed operation and the authority under which it ran.
Why a single governed data layer serving both humans and agents is the coherent end state
The purpose of these restrictions is shared analytical trust. A dashboard reader, an agent that generates reports, and an automated alert should use the same governed definitions rather than each keep their own version of the business’s metrics. Headless analytics provides that structure through a governed backend decoupled from any single front end and accessible through MCP or API. The definition lives in one place, while the contract boundary controls access to its result.
Different dashboards and agents can each calculate their own churn, with no shared way to check the numbers against one another and no audit trail. A weekly review then focuses on arguing about which number is right at the expense of deciding what to do. A shared endpoint removes that particular source of disagreement. It does not require every consumer to have identical permissions, because access rules remain distinct from metric definitions.
For Supabase teams, the coherent architecture treats Postgres as the analytical home rather than a source that must be extracted into a separate warehouse. The planned setup needs no ETL or schema changes and pre-models the metrics humans and agents need, making them available through a single governed MCP server. Even with Postgres as that home, analytical workloads must stay off production tables that serve live traffic. The resulting system combines workload separation, shared definitions, identity-bound access, constrained returns, and auditable execution at the point where the agent acts.


