Supabase User MCP

Give every human and agent its own bounded application-data identity path.

Supabase User MCP is an independent, security-first data-plane MCP server for applications built on Supabase. It is designed to let AI clients work with application data as a specific user or agent while PostgreSQL Row Level Security (RLS) remains the final authorization authority.

Why this exists

Supabase's hosted MCP server is a developer control-plane tool. Supabase User MCP explores the complementary application data-plane problem:

The goal is not to make prompt injection impossible. The goal is to make the blast radius of a compromised model no larger than the mechanically enforced authority of its verified principal/client capability.

Related MCP server: PostgreSQL MCP Server

Relationship to the Sovereign Memory program

This repository owns authenticated application data-plane capability, not the protocol and not a deployment.

• Sovereign Memory Protocol (SMP) defines implementation-neutral provenance, custody, authority, verification, portability, and claim semantics.

• Sovereign Memory Core is the PostgreSQL reference runtime for SMP semantics.

• Supabase User MCP provides a bounded user/agent capability seam into Supabase-backed application data while preserving caller identity into RLS.

• Deployments decide which principals, clients, tools, and data surfaces are actually enabled.

The dependency direction is one way: this project may implement SMP-compatible semantics, but it must not redefine SMP through Supabase-specific mechanisms.

A related proposed protocol lane is the Agent Access Integrity Boundary: establish a forward evidence boundary before agents are introduced to existing systems in situ. This repository can eventually provide one identity/capability mechanism for such deployments, but it does not itself establish the protocol claim.

Target security thesis

This is the required end-state boundary. It is not a claim that every hop is accepted on main today.

MCP client
    │ verified request context
    ▼
Supabase User MCP
    ├── exposes a small, allowlisted tool surface
    ├── preserves verified principal/client context
    ├── enforces validation, byte/time/rate bounds
    ▼
Supabase Data API / fixed RPC surface
    ▼
PostgreSQL + RLS
    ├── principal/client policy
    ├── tenant/capability policy
    └── row/operation policy

Non-negotiable principles:

1. No master key in the user request path. service_role, privileged database credentials, and admin Storage credentials do not prove user authorization.

2. The database makes the final authorization decision. Application checks improve usability; RLS/constraints enforce access.

3. Tools are capabilities, not a generic REST console. Public tools do not accept arbitrary SQL, tables, schemas, RPC names, URLs, buckets, or HTTP methods.

4. Caller-supplied actor/principal labels are not identity proof. Identity is derived from the verified request/session context.

5. Reads and writes are different authorities. Canonical or irreversible changes require separate governed proposal/approval semantics.

6. Untrusted content stays data. Tool results are bounded and explicitly rendered as untrusted model-visible content.

7. Claims require evidence. Positive, negative, cross-identity, broken-control, and adversarial tests are part of the boundary.

Current state

Current main contains the reviewed local foundation and merged principal-bound read path:

• strict TypeScript/MCP contracts and exact dependency lock;

• synthetic local Supabase Auth/JWT + RLS policy laboratory;

• cross-schema catalog lint for dangerous grants and SECURITY DEFINER review conditions;

• revocation/audit policy evidence;

• protected local credential loader and fixed Supabase client seam;

• bounded memory_search, memory_get, and memory_list_recent factories;

• verified Auth identity before read-only server registration;

• exact principal-scoped limiter and operational-event attribution;

• complete dual-representation JSON-RPC frame and request-ID ceilings;

• real MCP client -> fixed Data API -> PostgreSQL RLS acceptance;

• environment-only verified read-only stdio startup plus operator, revoke, and rollback guidance;

• a synthetic Storage/RLS artifact registry laboratory;

• the accepted Governed Artifact Inspection S0 capability, receipt, and integrity contracts; and

• deterministic S1b source-manifest, chunk, and Merkle-proof calibration; and

• an S2 synthetic/local fixed inspector library for artifact_stat, bounded byte ranges, and bounded UTF-8 line reads through injected authorization and immutable-version dependencies; and

• optional S3–S5a synthetic/local MCP registration for five fixed artifact operations (artifact_stat, bounded byte ranges, bounded UTF-8 lines, deterministic Markdown heading reads, and deterministic exact UTF-8 search), a deeply frozen executable Supabase Storage containment manifest, an acknowledged append-only inspection-receipt journal seam, and one fixed synthetic Markdown real-SDK adoption demo.

The consolidated read path merged through PR #38 at dd5ba98a00a3b37003554a14200f789fcb233cac. PR #40's base-binding and E2E-skip repairs are absorbed in that tree. Read-only server construction verifies the protected user credential through the fixed Supabase Auth user endpoint before registering tools, then supplies the verified principal and exact SDK request ID to every governor call. One contracts-owned renderer defines both the emitted dual-representation result and complete JSON-RPC byte estimator. The MCP tools specification says structured results SHOULD also provide serialized JSON text for compatibility; it is not a MUST. This implementation retains full dual representation and measures the selected complete frame. Unit and transport tests cover exact/one-over byte boundaries, request-ID escaping, hostile-content escaping, and bounded denial instead of oversized success. A read-only transport guard closes oversized inbound or outbound frames before dispatch/send, including denial paths with hostile request IDs. Serialized request IDs are separately capped at 1,024 bytes so bounded errors can echo them safely. Exact-head and post-merge Build/M2/Markdown/Links workflows passed.

The experimental local v0.1 pilot is complete. Official Auth test reuse and the authenticated PostgREST OpenAPI census merged through PR #45, and the executable environment-only stdio/operator package merged through PR #46. npm start launches the verified read-only stdio server; npm run start:compatibility retains the no-data M0 probe. Exact-head and post-merge Build, M2, Markdown, and Links checks passed. This is an experimental local-development profile, not a production or hosted deployment claim.

The intended local path is:

local Auth/JWT
  -> strict MCP tool
  -> fixed Data API/RPC
  -> RLS
  -> authorized intersection

Passing CI on a draft head is reproducible test evidence for that coordinate. It is not merge, deployment, production-readiness, or security acceptance.

Planned product surface

Initial read capabilities:

• memory_search

• memory_get

• memory_list_recent

Later governed write capabilities are planned separately, including append-only observations and proposal/approval workflows. See feature catalog.

Current scope limits

• The first profile is local stdio with one protected Supabase user access token. Remote HTTP/OAuth remains blocked on a standards-compliant downstream-token and audience design.

• The v0.1 tools expose one fixed allowlisted field projection. They do not provide per-principal column entitlements; RLS remains a row boundary.

• The current database search candidate is lexical. semantic mode does not establish an approximate-nearest-neighbor implementation or semantic quality, recall, latency, or multitenant isolation.

• The 65,536-byte response ceiling is a project-defined safety budget, not an MCP protocol limit. It must cover the complete serialized outbound frame, including the selected compatibility representations and protocol overhead.

• Production data, deployment credentials, and project-wide privileged keys remain outside this repository's accepted test profile.

Governed Artifact Inspection

Issue #34 tracks a related Storage/Edge capability: agents inspect durable artifacts through opaque IDs, caller-context RLS, bounded reads, integrity/provenance receipts, and a small supported-profile registry rather than receiving generic Storage access.

The current design keeps:

• MCP as the agent capability surface;

• Edge as a bounded inspection/execution surface;

• Postgres/RLS as authorization;

• Storage as byte custody.

Current repository evidence includes:

• S0: strict capability, complete-wire, integrity, derivation, and receipt contracts;

• synthetic S1: immutable artifact registry, derivation tables, approved-client policy, and Storage RLS laboratory; and

• S1b: deterministic raw/source hashes, domain-separated Merkle leaves, bounded proofs, full-source verification, and mutation-sensitive calibration; and

• S2: a pure TypeScript synthetic/local fixed inspector library with strict runtime adapter validation, distinct client/capability-grant custody, exact-version disappearance handling, redacted dependency failures, and schema-valid immutable receipts; and

• S3: optional fixed MCP registration for stat/range/lines plus executable Storage authorization, byte-read, immutable-version, integrity, retry, listing, credential, and write closure accounting; and

• S4 bounded integration/demo: the deterministic text-index primitive is exported and built in memory after each complete-source S1b verification; S2 line reads consume its canonical geometry, artifact_read_heading is registered as the fourth fixed artifact tool, and one fixed synthetic Markdown artifact passes the real MCP Client + StreamTransport SDK seam; and

• S5a deterministic search/receipt closure: artifact_search_exact performs case-sensitive raw UTF-8 byte matching over one fully verified source, optional registration exposes exactly five artifact tools, and every configured source-bound receipt is acknowledged through the injected append-only journal seam before MCP return.

S5a is complete only for synthetic/local exact search and the required receipt-journal interface. The repository provides no persistent journal backend and no live Storage/network adapter. Default CLI/stdio startup remains exactly the three memory tools. Live S5 operational adoption remains gated on selecting and approving a real caller-context adapter and durable evidence backend; S6 semantic summaries do not start here. No semantic/vector search, ingest, publication, Edge/hosted deployment, Storage/database mutation, signed URL, service_role, caller-selected coordinate, listing, canonical write, private-data access, or production-readiness claim is accepted.

Roadmap

The active extension has completed the bounded synthetic/local S5a exact-search and acknowledged receipt-journal seam. Live S5 operational adoption is next and remains gated on approving a real caller-context Storage adapter and durable evidence backend; S6 semantic summaries have not started. Detailed sequencing and claim limits live in docs/ROADMAP.md; the completed v0.1 execution baseline remains archived in epic #19.

Local development

Prerequisites and exact versions are documented in docs/DEVELOPMENT.md.

npm ci
npm run check
npm run build

Local Supabase policy tests use synthetic fixtures only. Do not point the harness at a private, restricted, customer, or production project.

Documentation

• Product definition

• Architecture

• Feature catalog

• Security model

• Threat model

• Roadmap

• Implementation plan

• Development guide

• Experimental local stdio operator guide

• Governed Artifact Inspection S0 contract

• S1b chunk/Merkle calibration

• S2 synthetic/local fixed inspector

• S3 optional MCP registration and Storage closure

• S4 bounded Markdown integration and SDK demo

• S5a deterministic exact search and acknowledged receipt journal

• Architecture decisions

• Program context and plane ownership

• Evidence index

Contributing

Please read CONTRIBUTING.md and GOVERNANCE.md. Security reports belong in the private process described in SECURITY.md, not in a public issue.

Project status and independence

Supabase User MCP is an independent open-source project. It is not an official Supabase product and is not endorsed by Supabase, Inc. "Supabase" identifies compatibility with the Supabase platform.

Licensed under the Apache License 2.0.