Supabase

Supabase

This connector works with your Supabase projects through the Management API (https://api.supabase.com, v1): projects and their health, the database (read-only SQL, schemas, tables with columns, constraints, indexes and policies, extensions, migrations, backups, TypeScript types), logs, security and performance advisors, Edge Functions, API keys (without secrets), preview branches and Storage buckets. It is the view of a project owner, not of an app user: it does not go through your project's REST API or row level security.

Setup (about 2 minutes)

1. Open https://supabase.com/dashboard/account/tokens (account menu → Account preferences → Access Tokens) and click Generate new token.
2. Prefer a scoped token: pick the organization and projects the AI may see and give each capability Read (or Read-write where it should change something). For the tools here: Projects, Project Settings, Database, Migrations, Backups, Edge Functions, API Keys (not API Key Secrets), Logs, Usage Analytics, Advisors, Storage, Development Branches and Organizations. A legacy token has your full access to every organization instead.
3. Set an expiry (at most one year), copy the token (it starts with sbp_; Supabase shows it only once) and paste it into SUPABASE_ACCESS_TOKEN.
4. A token's access cannot be changed later: to widen or narrow it, create a new one and delete the old.

Read-only setup: give a scoped token Read on every capability. supabase_execute_sql is installed switched off; with Database Read only, even that tool runs its SQL read-only. Nothing else here changes data.

Projects: every tool takes project_ref, the 20 lowercase letters in https://<ref>.supabase.co and in supabase_list_projects. Free projects pause after a week without activity and then show status INACTIVE: database tools fail until the project is restored in the dashboard. Check supabase_get_project_health when an app reports errors.

SQL

• supabase_run_read_only_sql runs one statement as a read-only database user. Qualify every table with its schema (public.orders, not orders), pass values as $1, $2 with parameters, and add a LIMIT: results over 200 KB are cut and marked _truncated.
• Start with supabase_list_schemas, supabase_list_tables (row level security on or off, estimated rows, size) and supabase_describe_table (columns, keys, indexes, policies).
• supabase_execute_sql (switched off at install) runs as postgres with full rights: DDL, writes and grants apply immediately and cannot be undone. Turn it on only for a user who wants the AI to change the database, and have every statement confirmed. For schema changes that should live in version control, the user's own migration workflow is the better place.
• The database query endpoints are marked beta by Supabase. A failing statement comes back with Postgres' message, e.g. "Failed to run sql query: relation "orders" does not exist".

Logs: supabase_query_logs takes SQL in the ClickHouse dialect over one logs table. Filter on source (edge_logs for API requests, postgres_logs, auth_logs, function_logs and function_edge_logs for Edge Functions, storage_logs, realtime_logs) and read nested fields with log_attributes['request.path'] or log_attributes['response.status_code']. Without iso_timestamp_start and iso_timestamp_end only the last minute is searched; a range may span at most 24 hours and must lie within the plan's retention (1 day on Free, 7 on Pro, 28 on Team). Example: select timestamp, event_message from logs where source = 'postgres_logs' order by timestamp desc limit 50.

Advisors: supabase_get_security_advisors and supabase_get_performance_advisors run Supabase's database linter, the same checks as the dashboard's Advisors page. Each finding has a level (ERROR, WARN, INFO), the affected object and a remediation link; fix ERROR ones first, especially tables exposed without row level security.

API keys: supabase_list_api_keys names every key but returns the value only of public ones (publishable keys and the legacy anon key). Secret keys and the legacy service_role key are listed without their value on purpose: they bypass row level security and must never travel through a chat. There is no tool to reveal them.

Edge Functions: supabase_list_edge_functions and supabase_get_edge_function give status, version and settings. Function code is not downloaded; read it from the user's repository. For errors, query function_logs with supabase_query_logs.

Branches: preview branches need a paid plan. supabase_list_branches lists them; each branch has its own project_ref, which the other tools accept.

Rate limits: 120 requests per minute per user and endpoint (all of a user's tokens share it), 30 per minute for logs and usage. Over it Supabase answers 429 for the rest of the minute.

Errors: 401 "Invalid access token" means the token is wrong, expired or deleted. 403 means the token may not do this: scoped tokens list what is missing in missing_permissions. 404 is an unknown project ref, or a project outside the token's organizations. 402 on logs means the organization's usage quota is exhausted. 410 Gone would mean an endpoint Supabase has retired.

Out of scope here: creating, pausing, restoring or deleting projects, deploying Edge Functions, secrets and auth configuration, custom domains, network restrictions, billing, and data in your app's tables through PostgREST.