Translating Agent Intent Into Parameterized Metric Calls Without Granting Supabase Schema Visibility
AI agents query Supabase metrics through parameterized contracts, not schema access.

Governed data access for AI agents on Supabase requires an MCP server that exposes named, parameterized metric functions. A translation layer resolves agent intent to versioned metric contracts, authorizes each call before execution, and runs approved queries against an isolated analytical copy. This makes schema invisibility a structural guarantee.
Why letting an agent see your Supabase schema is an architectural mistake, not a permissions gap
Schema visibility gives an agent the information needed to compose database queries. That is the wrong starting point for governed analytics. A database role can limit which records a query reaches, but it does not establish whether the agent chose the correct calculation or an authorized business operation. Runtime SQL remains outside the predefined metric contract, regardless of which role issues it.
The Open Agent Passport pre-action authorization paper frames the gap between what an agent can do and what it should do as an authorization problem. Model alignment cannot guarantee an individual output. The paper reports that social engineering succeeded against permissive-policy agents in the overwhelming majority of adversarial attempts, while a restrictive pre-action policy reduced success to zero across hundreds of attempts. RLS and RBAC filter access to an exposed surface, while schema invisibility removes that surface from the agent’s interface.
What goes wrong when agents query production Postgres directly
CData identifies credential exposure as the most common pilot-stalling pattern in its 2026 governance guidance. When an agent uses a shared service account, the real user’s permissions drop out of the authorization decision, and an over-scoped credential reaches everything that account can see. Analytical queries also keep connections open and compete with traffic from users. Supabase connection pools are finite, so exhaustion is a structural risk.
RLS was designed for per-user authorization policies. Teams either grant a role that bypasses RLS or retrofit analytics-shaped policies into the production authorization model. Meanwhile, agent-authored SQL can return “silent wrong answers,” where the query succeeds but the calculation is incorrect. Without attribution to a specific, scoped action, those queries also leave an audit gap, making the security, operational, and metric-integrity failures harder to reconstruct together.
How the authorization gap at the tool call boundary makes schema restrictions unreliable
The decision about whether a proposed tool call is part of an authorized task belongs before execution, at the tool call boundary. The OAP paper describes existing authorization as either model-driven and probabilistic or dependent on ad hoc application validation, neither of which supplies security-grade enforcement of a declarative policy. It also documents researchers finding hundreds of MCP servers exposed without authentication or encryption. Restricting a database role therefore addresses only part of the access path.
Persistent grants add risk as tasks grow. Individually modest additions can accumulate into access beyond the agent’s intended purpose. The Coalition for Secure AI’s Agentic IAM guidance says that agent credentials should follow Zero Standing Privilege principles and that agent identities must have their own baseline permissions, separate from those of the identities they represent. Short-lived, task-scoped access is incompatible with treating persistent schema access as the default. The architectural alternative is one access-controlled interface through which every agent reaches approved data operations, rather than a separate, progressively broader connector for each agent.
How do AI agents query Supabase data without direct database access?
A parameterized metric surface exposes business operations. The agent supplies a metric name, version, dimensions, filters, and grain. For example, it can request total_revenue at a declared version, grouped by an allowed dimension and constrained by an allowed filter. It does not choose tables, infer joins, or write a revenue calculation. The governed layer resolves the request to predefined SQL against an analytical copy that the agent cannot directly access.
MCP makes that restricted surface discoverable to agents. Its primitives are Tools for executable functions, Resources for contextual data, and Prompts for reusable templates. In this architecture, Tools expose metric discovery and execution through operations such as list_metrics, list_dimensions, and run_query. run_query accepts a metric request. CData describes the governed MCP layer as one access-controlled interface regardless of the model behind the agent. With no schema-inspection or SQL-authoring operation exposed, the agent’s choices remain within an enumerable catalog.
Translating agent intent into metric calls: the semantic resolution step
The translation layer resolves meaning. An agent first uses list_metrics to find the available metrics and reads the contract whose description matches the request. That contract gives the agent the version, valid dimensions, prohibited combinations, and temporal semantics it needs to build a call. The agent then selects parameters from that declared surface. Invalid dimension combinations are rejected before reaching the database.
This resembles a compiler pipeline with a deliberately narrow handoff. Natural language becomes a valid metric call made by the agent, and the governed layer compiles that call into SQL. Because the contract already defines tables, joins, and business rules, the agent does not make those choices again for each request. If five consumers independently extract a field buried in JSONB, their calculations can diverge, whereas consumers calling the same metric definition with the same parameters use the same calculation. Semantic resolution prevents that particular form of drift without requiring schema disclosure.
Why the analytical copy, not production Postgres, is where metric SQL runs
A governed call surface controls what can be requested, but it does not by itself isolate execution. Even perfectly parameterized queries consume production connections and compute if their SQL runs against the Supabase Postgres instance. The workload still competes with user-facing traffic. Running the queries on a governed analytical copy keeps agent demand from using up production query capacity. Authorization and workload isolation solve different problems.
Pre-modeled Parquet datasets queried through DuckDB provide one concrete form of that copy. Metric SQL runs against a snapshot that agents cannot change or explore beyond the surface declared in the contract. Production traffic does not contend with those analytical queries. The agent has no route to production Postgres and no direct access to the analytical files, so it cannot use metric calls to explore the database. This completes the structural argument for schema invisibility by separating both the exposed interface and its execution destination from production tables.
What metric contracts must specify to be queryable by an agent without ambiguity
A metric contract needs a name and version, a human-readable description, valid dimensions, invalid dimension combinations, temporal semantics, and the SQL or model to which it resolves. Each field removes a different ambiguity. The name tells the agent which operation it is, while the description lets intent resolution tell it apart from similar definitions. Valid dimensions set out how data may be filtered and grouped, and prohibited combinations let the governed layer reject requests before they run. Temporal semantics identify the date field defining the grain and the time zones that apply.
Versioning is essential when business definitions change. If revenue begins excluding refunds, calls pinned to v1 and v2 can legitimately return different numbers. Without explicit versions, the governed layer reintroduces metric drift. A description such as net revenue after refunds, excluding internal test accounts, calculated at event timestamp tells the agent what total_revenue means and how it differs from gross_revenue. The description works as an interface without showing the details of the physical schema.
The contract also provides the operational terms against which authorization evaluates a call. Attribute-based controls can determine which identities may call a metric, which dimension combinations they may request, and which response fields require masking. These are not simply session-level schema permissions. They bind access to a particular metric operation and caller context. The OAP paper establishes that pre-action infrastructure can enforce quality gates and operational contracts as well as security constraints, making a precise metric definition useful to both translation and enforcement.
Implementing the translation layer on a Supabase-backed stack
Implementation begins with the governed analytical copy. Pre-modeled Parquet datasets derived from the Supabase Postgres project provide the query surface, with DuckDB executing metric SQL against them. The datasets are stored and refreshed on a set schedule, while queries from agents stay off production. Isolation is the purpose of this component. Its existence allows the remaining layers to expose analytics without exposing the transactional database.
The next component is a versioned registry of metric contracts. It contains the specification fields described above and is the only surface the MCP server may expose. The catalog must precede the server. Otherwise, there is no defined set of business operations to constrain discovery and execution. The agent-facing interface leaves out the tables behind the metrics, schema details, and Parquet file paths.
The MCP server then exposes list_metrics, list_dimensions, and run_query as Tools. Its execution tool accepts metric name, version, dimensions, filters, and grain, rejecting requests that do not resolve to valid catalog entries before touching the analytical copy. Every model uses this same governed interface. The agent receives no table names, column names, foreign key relationships, raw SQL, file paths, or connection strings. Production Supabase is outside its reachable network, so the design does not depend on the agent choosing to avoid an available database connection.
How pre-action authorization at the metric call boundary completes the security model
A valid metric request is not necessarily an authorized request. The final enforcement layer must decide whether this agent may call this metric with these dimensions at this grain. Pre-action authorization intercepts the call synchronously and evaluates a declarative policy before the governed layer resolves it to SQL. A request outside policy is rejected with a cryptographically signed audit record.
CData identifies per-query attribution logging as the control that closes the audit gap. Every metric call must identify the agent, the user context on whose behalf it acted, and the parameters it supplied. Row-level filtering then limits returned records to those authorized for that context, while column-level masking redacts sensitive response fields. A raw schema grant alone cannot set out all these rules for each call.
The completed model has four complementary layers. Schema invisibility removes database exploration, the governed call surface bounds available operations, pre-action authorization enforces caller-specific policy, and the cryptographic audit trail establishes accountability. None substitutes for the others. Together, they connect what the agent can request, what it is permitted to execute, and what a reviewer can prove happened.
What teams running on Supabase should put in place before adding an agent to the data path
Set up the governed analytical copy, define the versioned metric catalog, and add pre-action authorization before letting an agent into the data path. Build the MCP server only after the catalog exists. Choose a server that can expose catalog-only Tools, reject invalid calls, keep caller context, and support row-level filtering and response masking at the metric boundary. A database connection alone cannot do all of this.
Source governance must also precede agent connectivity. CData places governance and RBAC before connection in its prerequisite sequence, with agents treated as distinct, scoped identities. Active connection counts, analytical query latency, and metric-call attribution logs should be available before production use. These controls make resource pressure and access decisions inspectable without waiting for a user-facing incident.
Every dashboard metric and agent response should reconcile to a single governed definition at its declared version. When sales, finance, and product each maintain a separate calculation, adding an agent can automate a fourth disagreement. A shared metric contract gives each consumer the same defined operation, while authorization sets how much that consumer may see.


