PaperClipAI/doc/connections/SUPABASE.md

Supabase

Reviewed 2026-10-22. Paperclip agents can deploy Supabase Edge Functions and configure application Auth and the Data API through a governed native Management API connection. Hosted MCP supplies project creation, database migrations and other provider tools. These are distinct connection methods and credentials are never forwarded from MCP OAuth into the Management API.

Neither Paperclip ID nor Paperclip Connect participates. OAuth discovery, registration, credentials and callbacks are instance-local. Cloud and self-hosted instances use the same path and the normal connection vault, grants, policies, run gateway and audit.

Methods and capability boundary

Method	Authentication	Capabilities	Scope
mcp-oauth	Supabase browser consent and DCR	Provider MCP project/account, SQL/migration, Edge Function, branching and optional storage tools	Consented organization, optionally pinned project
mcp-api-key	Supabase personal access token	Same hosted MCP tool surface, limited by token permissions	Token authorization, optionally pinned project
management-api	Supabase personal access token	Eleven reviewed project/configuration/function actions below	Required saved project reference

For MCP, Pin to project reference is optional under Advanced. An unpinned connection can create projects. Supplying project_ref disables account tools, including project creation. The read-only option stays under Advanced and defaults off. The optional feature-group list accepts docs, account, database, debugging, development, functions, branching, and storage. Storage requires explicit selection. Existing saved project pins are preserved. See the official MCP configuration and tool list.

Native actions use these fixed paths under https://api.supabase.com/v1:

Action	Request	Risk
supabase_get_project	GET /projects/{savedRef}	Read
supabase_get_auth_config	GET /projects/{savedRef}/config/auth	Read
supabase_update_auth_config	PATCH /projects/{savedRef}/config/auth	Write
supabase_get_api_config	GET /projects/{savedRef}/postgrest	Read
supabase_update_api_config	PATCH /projects/{savedRef}/postgrest	Write
supabase_list_edge_functions	GET /projects/{savedRef}/functions	Read
supabase_get_edge_function	GET /projects/{savedRef}/functions/{slug}	Read
supabase_deploy_edge_function	POST /projects/{savedRef}/functions/deploy?slug={slug}	Write
supabase_delete_edge_function	DELETE /projects/{savedRef}/functions/{slug}	Destructive
supabase_list_edge_function_secrets	GET /projects/{savedRef}/secrets	Read
supabase_upsert_edge_function_secret	POST /projects/{savedRef}/secrets	Write

Auth configuration includes site_url, uri_allow_list, disable_signup, external_email_enabled, mailer_autoconfirm, jwt_exp, and password_min_length. Data API configuration includes db_schema, db_extra_search_path, max_rows, db_pool, and db_pool_acquisition_timeout. Unknown fields and empty updates are rejected. Reads and write responses expose only these non-secret fields. In particular, Auth provider client secrets, SMTP passwords and PostgREST signing secrets are not returned. See the official Auth configuration and Data API configuration contracts.

Deployment sends UTF-8 source files as multipart file parts with a metadata part, matching the deployment endpoint and provider deployment example. The supplied entrypoint and optional import map must exist among unique relative file names. JWT verification defaults on; callers can explicitly disable it for an application that handles authentication itself. The request is bounded to 2 MiB and 50 files. The connector never reads server filesystem paths, runs a shell, or executes source code in Paperclip.

Native REST lists Edge Function secret names and update times and accepts {name, secretValue} to create or replace one environment secret. Secret values are never read back. Gateway argument summaries redact secretValue, and the provider response is discarded on writes. Each value is bounded to 64 KiB. See secret writes and secret inventory. Use the Dashboard when a human needs private entry; this action accepts a value the agent already has authority to use.

Native REST does not expose raw SQL, project creation, database credentials, SMTP passwords or OAuth client secrets. Use MCP for project creation and migrations. MCP Edge Function secret entry depends on provider and client URL elicitation support; this connector change does not claim that flow is qualified. Branching and other paid provider features retain Supabase's entitlements and cost handling.

Connection flow

sequenceDiagram
    participant User
    participant Paperclip
    participant Vault
    participant Supabase
    User->>Paperclip: Select Supabase method and agent access
    alt Hosted MCP browser sign-in
        Paperclip->>Supabase: Read protected resource and issuer metadata
        Paperclip->>Supabase: Register instance OAuth client
        Paperclip->>User: Open authorization URL
        User->>Supabase: Choose organization and consent
        Supabase->>Paperclip: Instance callback with authorization code
        Paperclip->>Supabase: Exchange code with PKCE
    else Personal access token
        User->>Paperclip: Enter token and optional or required project reference
    end
    Paperclip->>Vault: Store selected grant credential
    Paperclip->>Supabase: MCP discovery or native project probe
    User->>Paperclip: Set action permissions
    Paperclip->>Paperclip: Authorize agent run and selected grant
    Paperclip->>Vault: Resolve selected invocation credential
    Paperclip->>Supabase: Invoke permitted action
    Paperclip->>Paperclip: Record bounded result and audit

The editable diagram is also in supabase-flow.mmd. Public metadata observed on 2026-10-22 advertised:

• MCP: https://mcp.supabase.com/mcp
• Protected resource: https://mcp.supabase.com/.well-known/oauth-protected-resource/mcp
• Issuer metadata: https://api.supabase.com/.well-known/oauth-authorization-server
• Authorization: https://api.supabase.com/v1/oauth/authorize
• Token: https://api.supabase.com/v1/oauth/token
• DCR: https://api.supabase.com/platform/oauth/apps/register
• Paperclip callback: <instance-origin>/api/tools/oauth/callback

The existing thirteen reviewed MCP scopes match the public metadata. Native PAT permissions are separate: project_admin_read, edge_functions_read, edge_functions_write, auth_config_read, auth_config_write, project_admin_write for Auth changes, data_api_config_read, and data_api_config_write, plus edge_functions_secrets_read/write for function secrets. Equivalent endpoint OAuth scopes are projects:read, edge_functions:read/write, secrets:read/write, auth:read/write, and rest:read/write, but the native method uses a PAT. Permissions remain authoritative at Supabase. See project access, function access, Auth access, and Data API access.

Administrator setup and verification

1. Open Apps → Supabase, choose the connection identity and agents, then choose the method. Browser sign-in requires no manually registered OAuth app.
2. For token methods, create a scoped PAT in Supabase access tokens with permissions for the intended actions. A project publishable, anon, service_role, or secret API key cannot replace this PAT. For all native actions, scope it to the selected project and grant Read-write for Project Settings, Auth Config, Data API Config, Edge Functions, and Edge Function Secrets. Auth updates need both Project Settings and Auth Config. Data API JWT Secret access is unnecessary for the non-secret configuration fields. Use a short expiry and revoke the token after temporary verification. See the scoped PAT permission guide.
3. For native deployment/configuration, copy the existing project's reference from Project Settings. The saved reference is the execution boundary and cannot be overridden by tool arguments. For MCP project creation, leave the Advanced project pin empty and retain the account feature group.
4. Complete consent or token setup. For browser consent, honor provider delays and real pointer/keyboard interaction before diagnosing an OAuth problem. A disabled consent button alone is not evidence of callback failure.
5. On Permissions, inspect discovered actions and set Allowed, Ask first or Off. Test project/function inspection, then deploy a disposable function in a development project, read its version, and delete it. To verify Auth changes, preserve the prior site URL and restore it after a test change.
6. Verify an agent read/write through its run gateway, denial under an Off policy, catalog refresh/reconnect, and removal. Confirm the token is absent from responses and audit. Provider errors are mapped to fixed messages; 401/403 require checking token permissions, 402 requires account/billing action, and 429 requires waiting. Writes are never automatically retried after an uncertain transport result.

Evidence and remaining qualification

The provider fixture suite is server/src/services/connectors/supabase/index.test.ts. It covers multipart deployment, configuration, credential/header projection, project containment, malformed paths/files, schema and risk drift, deletion, secret input summary and output redaction, provider failures, bounded reads and uncertain-write behavior. Shared connection tests cover the vault and governed run gateway. Fixtures do not establish provider account authorization.

Public metadata preflight passed on 2026-10-22. Live source verification then used an isolated worktree init --empty instance on macOS arm64, Node 26.4.0, with synthetic company DEP at http://127.0.0.1:4391. The normal CLI started the instance with its own embedded PostgreSQL. Its supported worktree run setting was explicitly enabled for the proof; no default or production database was used.

The Apps UI showed all three methods, optional Advanced project pinning for MCP, and the required project pin for native REST. Real browser OAuth consent completed and discovery returned 29 MCP actions (18 read and 11 write). A real process-agent run through the governed gateway created one disposable project after the provider quoted $0/month. The project reached ACTIVE_HEALTHY; successful run ID: 560aa4eb-237d-4b52-8d44-d23d9aab3f57.

The first live harness run misread the provider's wrapped organization result; normalizing that result resolved the harness failure. A duplicate queued wake later attempted the same project creation and was rejected by the provider. The harness gained a one-shot guard, and the Dashboard confirmed exactly one new proof project. These earlier failures remain part of the verification evidence.

Native setup then vaulted a 24-hour scoped PAT limited to that project and the five documented permission groups. Discovery exposed eleven actions. Real process-agent run 9eede77a-2360-4710-b473-4688242062e3 changed and read back Auth and Data API settings, wrote an environment secret without returning its value, deployed an Edge Function, and read its ACTIVE status. Its public HTTP response was 200 with the expected hello marker and secretConfigured: true.

That run remained failed because its configuration cleanup received a provider server error and an immediate stale read. Subsequent read-only connector calls confirmed the original site_url and max_rows were restored, without another write. The connector now marks provider server errors after writes as uncertain outcomes and tells callers to inspect state before retrying. The regression test also covers an applied configuration change followed by a server error; the provider suite passes all 30 tests. A subsequent actual process-agent cleanup run, ba60f6a7-bade-42d6-9a82-1cc12144589b, succeeded: it confirmed both original settings, deleted the function, and verified its absence from the function list. The original failed run and successful reconciliation are retained separately.

The operator deleted the disposable project in the Dashboard, removing its database and proof secret, and confirmed its absence from the organization list. The temporary scoped PAT was deleted; the provider showed no remaining PATs. Both local connections and the unconnected setup draft were removed. Fresh process agents received no tools and prior tool names returned 404 for both connections. A final MCP list confirmed the proof project was absent. Forced refresh and reconnect with fresh provider credentials were not live-tested. No paid upgrade or existing production resource was created or modified.

A subsequent browser-only walkthrough on 2026-10-23 used a real native Codex agent rather than the process gateway harness. It exposed a delivery gap: connection readiness, native assignments, and runtime preparation accepted only their existing transports and omitted reviewed REST connections. The saved credential passed a project-read test as the same agent, but the task could not discover its actions and rejected the offered identity as conflicting. The three filters now recognize the reviewed REST registry while retaining existing installation, identity, health, and action-policy checks. Four database-backed regressions failed before the fix; all 33 deployment lifecycle cases passed after.

After a separate source repair and isolated-instance restart, the same Codex task deployed a JWT-protected function, set a synthetic environment marker, changed the Auth site URL and Data API row limit, and read all four back. The Dashboard independently showed JWT verification enabled and the saved Auth URL. Its built-in function tester returned HTTP 200 with the exact synthetic marker. The earlier failed browser runs remain separate evidence; this retry does not retroactively qualify their missing agent path.

Sensitive tool arguments such as secretValue are encrypted in newly created approval payloads with the instance tool-action signing secret. Approval summaries and audit still use redacted values. Existing signed approval records remain readable and are not rewritten. Sensitive request identities also use this key to distinguish secret replacements without storing guessable secret hashes. The configured PAPERCLIP_TOOL_ACTION_SIGNING_SECRET takes precedence. When unset, Paperclip derives a separate signing key from its persisted secrets master key, using the configured master-key environment value or durable key file. Key rotation can invalidate retry matching; back up the configured signing key or master key with the database, and share that key across processes serving the same instance.

New default retry keys are versioned and actor-scoped. Older completed requests replay only when their arguments can be verified exactly. An unverifiable legacy request returns HTTP 409; inspect its previous effect before intentionally using a new explicit idempotency key.