MCP Resource Registration as the Runtime Contract Between Agent Query Intent and Postgres Execution on Supabase
Registration sets the boundary, but only database-side controls enforce it.

Governed data access for AI agents on Supabase requires an MCP server that exposes scoped operations and pre-modeled datasets. Resource registration sets the runtime contract between what an agent intends and what Postgres executes, but server-side constraints, row-level access controls, and audit logs must enforce it. For analytics, that contract must govern both which records an agent can retrieve and what the returned metrics mean.
What MCP resource registration actually does at runtime on Supabase
The server starts, the host’s MCP clients connect, and the server advertises its capabilities. Its available tools, resources, and prompts give the host a menu from which the agent can form requests. Registration establishes the declared boundary at that moment. A data surface absent from that menu is not addressable through the registered resource interface, regardless of the agent’s request. Whether that boundary holds across the whole server also depends on what its tools permit.
Tools are functions the model invokes, resources are read-only data it reads, and prompts are predefined workflow templates. Resources work more like GET endpoints than function calls. Because resources are passive and side-effect-free, they can expose a defined data surface without also declaring a mutation capability. A broad SQL tool, however, creates a separate route to the database, so resource registration cannot be assessed in isolation from tool registration.
How the runtime contract translates agent intent into a bounded Postgres operation
Within a scoped tool design, the model analyzes the request and selects a registered operation such as database_query. It then generates a structured JSON-RPC request with parameters such as a report name and date range. The MCP client sends that request to the Postgres MCP server, which translates it into SQL, executes it, and returns a structured JSON result. The client feeds the result back to the model. The agent holds neither a raw connection string nor, in this design, the SQL that reaches Postgres.
The translation step is the enforcement point. A named tool such as get_customer_order_summary(customer_id, start_date, end_date) narrows the operation before the server constructs a query. Similarly, list_overdue_invoices(account_id, limit) declares a particular business operation. This is a stronger boundary than a generic execution surface because the registered interface limits what the request can mean.
Arbitrary parameters could still turn a narrowly described operation into a wide read. The safer design therefore combines a parameter schema that narrows the input space with a server-side SQL template that fixes the query’s shape. Registration describes the allowed operation, while validation and translation make that description effective at execution.
What URI templates and capability declarations actually constrain
URI templates define which addresses exist within the resource interface. For example, postgres://mydb/users/{id} declares access to a user through a single ID parameter. Lookup by name, role, or bulk selection requires separate registered interfaces. This address-space constraint operates alongside the authorization checks that permit or deny retrieval of the addressed record.
Capability declarations establish a different part of the boundary. Resources are read-only by contract, while tools may permit writes. Return shape is a further distinction, because a pre-aggregated analytics result and a raw table expose different choices to the agent. A governed analytics layer can register only the former, with the URI identifying the defined dataset.
CoSAI’s Model Context Protocol (MCP) Security paper identifies missing or improper access control, MCP-T2, and trust boundary and privilege design failures, MCP-T9, as distinct threat classes. These threats must be addressed when capabilities are designed, before any query runs. Declarations must describe authorization and privilege boundaries that the server and database actually uphold. Otherwise, the advertised interface gives the agent a promise that the execution path does not keep.
Where Supabase’s MCP implementation enforces the contract and where it does not
Supabase’s documentation states that enabling read_only=true runs queries as the dedicated supabase_read_only_user PostgreSQL role. That is a database-level restriction. Read-only execution is therefore a substantive control. It does not, however, determine which tenant’s records a query can read.
The key used for execution determines the RLS boundary. The supabase_query tool can enforce Row Level Security when configured with an anon or user-scoped key, while the default service_role key bypasses RLS. This is the critical distinction for tenant isolation. A read-only query running with the service key can still bypass the policies intended to separate users’ data. Supabase’s SOC 2 Type II certification and database audit logs do not change that execution behavior.
A documented issue once left mutating tools visible in tools/list under read-only stdio mode, even though they were blocked from running. That issue has since been fixed. The issue shows why the capabilities a server advertises must match the restrictions it enforces. Supabase also exposes tools across eight feature groups, including migrations, TypeScript type generation, Edge Functions, Storage, and Branching, so selective loading reduces both unnecessary discovery breadth and the default tool set’s token footprint.
The five production controls that complete the contract Supabase does not close for you
Builders should enable read_only=true for read-only workloads and use an anon or user-scoped key where RLS enforcement is required. The role limits changes to data, while row policies constrain visibility when the key is anon or user-scoped. Neither setting should be treated as proof that the other is correct.
The second control is a connection-level statement timeout. Builders should set it to 5s or 10s so that a runaway query from a confused model cannot run indefinitely. The notes identify no native duration limit in Supabase’s beta endpoint. Even with a bounded input schema, a query can be expensive to run. The timeout caps how long a query can run even when the registered interface allows it.
The third control is a query audit log. Every query should record its timestamp, caller identity, query text, and row count. These fields connect execution to a caller and document what the database returned. Without them, a retrospective question about an agent’s activity lacks the necessary evidence. CoSAI’s paper classifies insufficient logging and monitoring as MCP-T12, making this an explicit security concern.
The fourth control links the identity from the protocol to native RLS. The MCP server should execute queries within a transaction block that sets local session variables, such as SET LOCAL app.current_user_id = '...', for the applicable policies. The identity must reach the enforcement layer. This bridge serves policies that use those variables, but it does not make a service key subject to RLS. Execution identity and session context must therefore agree.
The fifth control is filtering the registered tool surface. For a read-only deployment, builders should explicitly exclude mutating tools from the advertised capability set. Even where execution rejects a write, advertising that operation creates a mismatch between permitted intent and permitted execution. These five controls are additive because each closes a different gap at the MCP-to-Postgres boundary.
Why raw-table resource registration creates metric drift and agent hallucination
Structural safety does not establish the meaning of a result. A server can enforce read-only access, tenant scope, and timeouts while exposing records that leave business definitions unresolved. One engineer calculates Q2 revenue with SUM(revenue), while another uses SUM(amount_captured). Both may read the intended records. The disagreement comes from a definition that the system has not encoded.
An agent inherits that ambiguity when it receives raw tables. It must choose fields and calculation logic without a governed definition that tells it what the requested metric means. The query can succeed and still answer incorrectly. This is metric hallucination, where a plausible calculation is presented as the business metric despite the absence of a semantic contract. Resolving this metric hallucination requires governing the interpretation of records in addition to database permissions governing access.
ContextNest describes the context governance gap directly: access to information does not ensure that it is approved, current, attributable, and auditable. Applied to analytics, the distinction explains why finding the relevant table is insufficient. When analysts and agents derive separate definitions from the same Postgres records, their outputs cannot be traced to one canonical business definition. The contract therefore needs a semantic boundary as well as an access boundary.
How do governed MCP datasets expose metrics without touching production Supabase tables?
For analytics, the appropriate registration unit is a pre-calculated, semantically defined dataset. Its shape stays the same whether a human or an agent uses it, and its resource address names the defined business output. The agent retrieves a metric. This moves calculation logic behind the governed interface instead of leaving each caller to reconstruct that logic from the substrate.
The architecture separates four layers with distinct responsibilities. The Data Substrate contains verified, permissioned, refreshable data with documented provenance, including the underlying Postgres tables. The Reasoning Layer supplies semantic schemas, metric definitions, and business logic. The Delivery Layer exposes governed outputs through MCP. The Decision Layer then connects the resulting human or agent action to an owner and an outcome, without making the underlying tables the agent’s interface.
A resource such as analytics://metrics/revenue/monthly/{team_id} makes the delivery boundary concrete. Its address identifies revenue, monthly grain, and a team-scoping parameter. The grain is part of the interface. An alternative definition or aggregation is not available through that resource unless another interface registers it. Authorization must still govern the supplied team scope, because an addressable parameter does not itself confer permission.
Enterprise implementations show this move toward headless business capabilities, but they do not show which Supabase servers are best. Informatica announced fully headless data management through native MCP support at Informatica World 2026, held May 19–21, 2026. Its announced scope included metadata search, data quality checks, and MDM/governance capabilities exposed through MCP endpoints as well as the GUI. Salesforce Headless 360, announced at TrailblazerDX on April 15, 2026, shipped more than 60 new MCP tools and 30+ preconfigured coding skills. The Supabase-specific access controls described above remain necessary with these headless business capabilities.
The observability layer the contract requires but resource registration cannot provide
Registration says what is allowed to run, but it cannot report what ran. Supabase’s Metrics API exposes Postgres performance and health series in a format compatible with monitoring systems, while Logflare processes billions of log events daily across the API gateway, Postgres, Storage, and Edge Functions. Those signals describe the infrastructure’s operation. They do not by themselves correlate a slow query with the agent intent that caused it or explain an Edge Function timeout through a downstream cascade.
The MCP server therefore needs structured tool-call logs keyed to agent identity. Query audit fields establish who executed what and how many rows came back, while tool-call context connects that execution to the agent’s request. Operational logs show how well the service is running. Both are necessary, and neither replaces the other. CoSAI’s logging threat class applies here because a declared boundary without attributable execution evidence cannot support a reliable retrospective audit.
Governed datasets make that evidence easier to interpret. When an analytics layer pre-calculates and caches results, the same question produces the same SQL. That stability supports anomaly detection and audit replay, although it does not replace caller attribution. The practical requirement is to add tool-call-level logging to the MCP server rather than rely on operational logs alone. The runtime contract is only as strong as its audit trail.


