> ## Documentation Index > Fetch the complete documentation index at: https://docs.argalabs.com/llms.txt > Use this file to discover all available pages before exploring further. # Supabase MCP > Connect agents to a Supabase twin for SQL, migrations, and connector evaluations 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 ```bash theme={null} 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: ```json theme={null} { "mcpServers": { "supabase-twin": { "url": "", "headers": { "Authorization": "Bearer " } } } } ``` [Arga MCP](/mcp-tools) 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: ```bash theme={null} 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](/features/custom-scenarios) with `twins: ["supabase"]` and provider state under `seed_config.supabase`. For example: ```json theme={null} { "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: ```bash theme={null} arga twin-runs create --twins supabase --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. This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.