Supabase MCP

Use the supabase twin to test an agent through the Supabase MCP endpoint or Management API. It is API-only, with a separate Supabase PostgreSQL 17.11 cluster for each project and branch. Tables, constraints, transactions, roles, and row-level security execute in PostgreSQL.

Provision and connect

arga twin-runs create --twins supabase --ttl 60 --wait

Wait until the Twin Run is ready. Use the Supabase environment variables returned by the run:

Variable	Purpose
`SUPABASE_MCP_URL`	Project-scoped MCP URL, including `/mcp?project_ref=...`.
`SUPABASE_API_URL`	Management API base URL.
`SUPABASE_ACCESS_TOKEN`	Bearer token for the twin’s MCP and Management API.
`SUPABASE_PROJECT_REF`	Project reference for Management API paths.
`SUPABASE_PROJECT_ID`	Alias for the same project reference.

Add a separate server entry to your agent’s MCP configuration. Replace both placeholders with the returned values; this example does not assume your client expands environment variables:

{
  "mcpServers": {
    "supabase-twin": {
      "url": "<SUPABASE_MCP_URL>",
      "headers": {
        "Authorization": "Bearer <SUPABASE_ACCESS_TOKEN>"
      }
    }
  }
}

Arga MCP provisions and manages Twin Runs. The Supabase twin’s MCP endpoint exposes provider tools such as execute_sql and apply_migration. Use the returned twin token for those calls; your Arga API key authenticates the Arga control plane.

Scope and confirmations

Discover tools through your MCP client after connecting. The catalog depends on URL options and client capabilities:

Option	Behavior
`project_ref`	Scopes tools to one project. Omit it for account-level tools that accept explicit project IDs.
`read_only=true`	Restricts writes and removes tools such as `apply_migration`. SQL uses a restricted database login.
`features=database,debugging`	Selects tool groups. Other supported groups include `development`, `functions`, `docs`, `branching`, and `storage`.
`skip_elicitations=execute_sql,apply_migration`	Skips SQL confirmation prompts for those tools. Use this only when your evaluation intentionally requires unattended writes.

For example, append &read_only=true&features=database to the returned project-scoped URL for a read-only SQL session. Preserve its existing project_ref. Form-capable clients on the current protocol receive destructive-SQL and cost confirmations. Accept, decline, and cancel are supported. skip_elicitations also accepts create_project and create_branch; these retain the legacy cost-confirmation flow when skipped. Invalid names and repeated skip_elicitations parameters are rejected. Legacy Streamable HTTP clients initialize first, retain the returned Mcp-Session-Id, and send it on subsequent requests. Legacy responses use JSON; current-protocol responses can stream through SSE. The endpoint supports POST; GET and DELETE return 405. Official MCP clients handle the connection protocol for you.

Provider tools and state

Area	Tools and behavior
Database	`list_tables`, `list_extensions`, `list_migrations`, `execute_sql`, and `apply_migration`. Table metadata comes from the live database catalog.
Debugging	`query_logs` runs ClickHouse SQL over actual twin activity and function events. `get_advisors` runs database security and performance checks.
Development	`get_project_url`, `get_publishable_keys`, and `generate_typescript_types`. Generated types include tables, relationships, RPCs, and PostgREST compatibility metadata.
Functions	`list_edge_functions`, `get_edge_function`, and `deploy_edge_function`. Deployed code executes in the Supabase Edge Runtime, including imports, secrets, JWT checks, and console logs.
Documentation	`search_docs` queries Supabase’s public documentation endpoint and requires outbound access to that endpoint.

You can also call the Management API directly after exporting the returned variables:

curl "$SUPABASE_API_URL/v1/projects/$SUPABASE_PROJECT_REF/database/query" \
  -H "Authorization: Bearer $SUPABASE_ACCESS_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{"query":"SELECT current_user, auth.uid(), current_database()"}'

Successful SQL requests return HTTP 201. Errors preserve PostgreSQL SQLSTATEs and applicable detail, hint, context, and statement-position text. MCP wraps these results in the provider’s tool response format, including untrusted-data boundaries. SQL execution failures use HttpException in MCP. Query errors start with Failed to run sql query:; migration errors start with Failed to apply database migration:. Fetching a missing Edge Function returns NotFoundException with Function not found. Use apply_migration when the change needs migration history. execute_sql changes database state without adding a migration entry. Migrations normally execute transactionally; explicit COMMIT and ROLLBACK statements retain PostgreSQL semantics. Branches replay tracked migrations, so later untracked DDL is not copied once migration history exists. Role and JWT settings do not carry across SQL requests. Apply the role and request claims in the same call as the query when testing RLS. Numeric values and unsafe bigints remain strings, timestamps retain database text, and byte arrays use Buffer JSON. Log SQL uses ClickHouse server semantics: SELECT 1 AS probe returns one row regardless of how many log records exist. The tested TypeScript output includes __InternalSupabase.PostgrestVersion set to 14.18; this is compatibility metadata, not a PostgREST endpoint.

Seed an evaluation

Save a Scenario with twins: ["supabase"] and provider state under seed_config.supabase. For example:

{
  "name": "Supabase unique-email evaluation",
  "twins": ["supabase"],
  "seed_config": {
    "supabase": {
      "projects": [{
        "id": "argatwinprojectaaaaa",
        "name": "Connector evaluation",
        "migrations": [{
          "name": "create_accounts",
          "query": "CREATE TABLE public.accounts(id integer PRIMARY KEY, email text NOT NULL UNIQUE);"
        }],
        "sql": [
          "INSERT INTO public.accounts VALUES (1, 'ada@example.test');"
        ]
      }]
    }
  }
}

Then provision with the saved Scenario ID:

arga twin-runs create --twins supabase --scenario-id <scenario-id> --ttl 60 --wait

You can seed enums, views, functions, triggers, grants, and RLS policies with SQL. Standard auth and storage schemas, auth.uid(), auth.jwt(), and Supabase roles already exist. Include the grants and policies your evaluation needs. Use projects[].migrations for tracked schema changes and projects[].sql for additional state; top-level sql is convenient for a single project. Without base_time, the twin uses the actual clock. An explicit base_time fixes supported SQL clock functions for repeatable scenarios. Explicit resource dates stay unchanged. PostgreSQL’s special 'now'::timestamptz input literal and maintenance clocks retain native time.

Verified fidelity

The hosted comparison on 9 October 2026 (UTC) matched 124/124 checks across Management API status codes and bodies, MCP initialization/session behavior, 14 scoped tool definitions, SQL errors/results, table metadata, extensions, log queries, generated types, missing-function errors, and migration results plus committed state/history. It included explicit COMMIT and ROLLBACK cases. An additional 5/5 checks matched using the official MCP client pinned to protocol 2026-07-28, including read-only discovery and declining a destructive-SQL confirmation. Native PostgreSQL comparisons matched 47/47 checks. The runtime suite passed 57 tests locally and in Linux CI, covering both legacy and current MCP clients alongside database, function, CLI, and log behavior. The hosted comparison normalizes random untrusted-data boundary UUIDs and sorts the unordered extension catalog by name while comparing every extension field. Session IDs are checked for presence rather than random value. Test schemas and migration records were cleaned up after the comparison. These results establish parity for the tested paths. They do not imply exhaustive equivalence across every Supabase operation or future hosted release. The tested baseline uses @supabase/mcp-server-supabase 0.13.0; provider releases can change tool schemas and behavior.

Boundaries

The twin exposes the Management API and MCP. It does not provide the Supabase dashboard, OAuth login, Auth HTTP API, PostgREST Data API, or hosted connection pooler. A returned project URL or publishable key does not enable those excluded surfaces.
Storage SQL and MCP configuration tools are supported. Storage object transfer and S3 HTTP services are outside this surface.
create_edge_function_secret requires an interactive hosted dashboard flow and is not advertised. Set secrets through the twin’s Management API instead. SQL and cost form confirmations work without a dashboard.
The public gateway exposes HTTP. Native Supabase CLI database commands require a private PostgreSQL connection; they do not work by replacing the database URL with SUPABASE_API_URL. Management API CLI commands require a custom Supabase CLI profile pointing api_url at the twin; the CLI does not use SUPABASE_API_URL as an override.
Logs represent services executed by the twin. Exact hosted infrastructure traffic, rate limits, cloud scaling, billing, scheduling, and timeouts are not simulated. Advisor output and control-plane lifecycle errors have not been exhaustively compared against hosted Supabase.

Get started

Digital twins

Tests

Setup

Integrations

Resources

Supabase MCP

Provision and connect

Scope and confirmations

Provider tools and state

Seed an evaluation

Verified fidelity

Boundaries

​Provision and connect

​Scope and confirmations

​Provider tools and state

​Seed an evaluation

​Verified fidelity

​Boundaries

Provision and connect

Scope and confirmations

Provider tools and state

Seed an evaluation

Verified fidelity

Boundaries