Supabase MCP

The Supabase MCP server lets an AI agent work with your Supabase projects: list tables, run SQL, apply migrations, read logs and advisors, deploy Edge Functions and search the docs. Supabase hosts it at https://mcp.supabase.com/mcp and signs you in with OAuth. Use URL options to limit it to one project and make it read-only. We checked Supabase's docs and repo on 31 October 2026.

Quick facts

What it lets an agent do

The docs organise tools into feature groups. Groups your connection supports are on by default, except Storage.

Account tools are disabled when you scope the server to a project with project_ref.

For a developer, the daily uses are: asking what the schema looks like, writing and applying a migration, generating types, reading logs when something fails, and running the advisors to catch missing row-level security.

The URL is the control panel

Most of the safety controls live in the endpoint URL. Supabase's docs list these parameters:

Combine them with &:

https://mcp.supabase.com/mcp?project_ref=abc123&read_only=true&features=database,docs

The README suggests a configuration panel on Supabase's docs that builds this URL for you, plus an interactive URL builder.

Install it in each agent

Claude Code

Supabase's docs use project scope:

claude mcp add --scope project --transport http supabase "https://mcp.supabase.com/mcp"

Or put it in .mcp.json:

{
  "mcpServers": {
    "supabase": {
      "type": "http",
      "url": "https://mcp.supabase.com/mcp?project_ref=YOUR_REF&read_only=true"
    }
  }
}

Then authenticate. In a regular terminal (not the IDE extension) run claude /mcp, choose the supabase server and Authenticate. The URL contains only a project reference, not a secret, so it is safe to commit. See our Claude Code MCP guide for scopes.

Cursor

Add to .cursor/mcp.json (or ~/.cursor/mcp.json for all projects):

{
  "mcpServers": {
    "supabase": {
      "url": "https://mcp.supabase.com/mcp?project_ref=YOUR_REF&read_only=true"
    }
  }
}

Cursor IDE and the Cursor CLI share the same MCP configuration.

Codex

codex mcp add supabase --url "https://mcp.supabase.com/mcp"
codex mcp login supabase

Or in ~/.codex/config.toml:

[mcp_servers.supabase]
url = "https://mcp.supabase.com/mcp"

Run /mcp inside Codex to check authentication.

Gemini CLI

Supabase warns that you need Gemini CLI version 0.20.2 or higher. The simplest route is the extension, which bundles the server connection and agent skills:

gemini extensions install https://github.com/supabase-community/gemini-extension

Or add only the server:

gemini mcp add -t http supabase "https://mcp.supabase.com/mcp"

Then authenticate with /mcp auth supabase.

VS Code

Add to .vscode/mcp.json:

{
  "servers": {
    "supabase": {
      "type": "http",
      "url": "https://mcp.supabase.com/mcp?project_ref=YOUR_REF&read_only=true"
    }
  }
}

Other clients

Supabase's page also covers Copilot CLI, Grok, OpenCode, Factory, Antigravity and web clients. Any client can use the same URL in its own format.

Compatibility at a glance

Auth and permissions

OAuth by default. The hosted server uses dynamic client registration, so you do not need to create a personal access token or an OAuth app. The browser opens, you log in to Supabase and grant the client access to an organization. Pick the organization that holds the project you want.

A token for CI. If you run in CI where a browser flow is impossible, create a personal access token, scope it to the project, grant only the permissions your enabled tools need, and pass it in an Authorization header with environment variables for the token and project reference. Not every client supports custom headers.

A manual OAuth app. For clients that need a client ID and secret (the docs mention Azure API Center), create an OAuth app in your organization settings. The docs note that for now all scopes need write access, with finer scopes planned.

Elicitations. Some actions ask you to confirm. The docs describe form-based cost confirmation before actions that cost money (create_project, create_branch), confirmation for destructive SQL in execute_sql and apply_migration, and URL-based entry for Edge Function secrets so the secret value never goes through the chat. Supabase says to treat these as guardrails, not guarantees: some clients answer elicitations automatically, and SQL detection may miss destructive operations. You can skip named confirmations with skip_elicitations, which does not bypass authentication, permissions, read-only restrictions or charges. We would not skip them.

Security: the part Supabase itself puts first

Supabase's page opens with a caution: connecting an LLM to your projects carries security risks.

Prompt injection. Their example: you build a support ticketing system on Supabase. A customer submits a ticket whose text says to select everything from a sensitive table and insert it as a reply. A developer asks an MCP client to read that ticket with the Supabase MCP. The client may follow the injected instruction. Supabase wraps SQL results with extra instructions to discourage the model from obeying content in the data, and says plainly that this is not foolproof.

Their recommendations, in our words:

1. Do not connect production by default. The docs say production projects can contain sensitive data. If you must, scope to that project, turn on read-only mode, restrict feature groups and review the risks.
2. Keep manual approval on for tool calls in interactive work and read each one.
3. Unattended routines should be project-scoped and read-only, and should stop and report a recommendation rather than run a write.
4. Use a development project or a branch for write work.
5. Limit features with features= to what the task needs.

Keep one more point in view: the server is as powerful as your account. An agent with account tools and write access can create projects (a cost) and change production schemas.

Local development with the Supabase CLI

If you run Supabase locally with the CLI, the MCP server is at http://localhost:54321/mcp. The docs say that with the experimental stack setting turned on, local projects use assigned ports, so read the MCP URL from the output of supabase status. The local server offers a limited subset of tools, which is a fine place to practise: nothing you break there is production. Self-hosted Supabase has its own page for enabling the server and also offers a limited subset.

A safe path from read-only to a real change

A pattern that keeps most of the controls in place:

1. Connect with project_ref and read_only=true. Explore the schema and run the advisors.
2. Ask the agent to draft the migration as SQL and explain it. Read it.
3. Create a development branch or use a dev project (branching is experimental and needs a paid plan), and connect a second, non-read-only server entry to that project only.
4. Apply the migration there. Check the result with list_tables and the advisors again.
5. Apply the same migration to production through your normal pipeline, not through the agent.

Giving the two connections different names, such as supabase-prod-ro and supabase-dev, makes it obvious which one a tool call goes to when you read the approval prompt.

Row level security is the check to run every time

Agents write tables quickly and forget access control just as quickly. In Supabase the browser talks to your database through the project's API, and row level security (RLS) is what decides which rows a user can see. A table created without it, in a schema the API exposes, can be readable or writable by anyone with the public key. That makes it the first thing to check after any agent-written migration.

A minimal pattern for a table where each user owns their rows looks like this. It is our example, so adapt the names to your schema.

create table public.notes (
  id bigint generated always as identity primary key,
  user_id uuid not null references auth.users (id) default auth.uid(),
  body text not null,
  created_at timestamptz not null default now()
);

alter table public.notes enable row level security;

create policy "owners read their notes"
  on public.notes for select
  to authenticated
  using ((select auth.uid()) = user_id);

create policy "owners write their notes"
  on public.notes for insert
  to authenticated
  with check ((select auth.uid()) = user_id);

Enabling RLS with no policy blocks everything for ordinary users, which is the safe default. Each policy then opens one door, for one role and one operation. When you review a migration, ask five questions:

1. Does every new table in an exposed schema run enable row level security?
2. Is there a policy for each operation the app needs, and none it does not?
3. Does each policy name a role, such as authenticated, instead of leaving it open to everyone?
4. Do the policies compare against auth.uid() or another identity, rather than true?
5. Does a test sign in as two different users and confirm that neither sees the other's rows?

The advisors the server can run include checks for missing RLS, and running them after every change is cheap. Do not treat a clean report as proof. Test with two real users, since a policy that is valid SQL can still describe the wrong rule. Keep policies in migration files in the repository, and review them in pull requests like application code.

Review migrations like code, not like chat

The safe path ends with the migration going to production through your normal pipeline. That only works if the migration is a file a person reads. A routine that holds up:

• Name the intent. One migration per change, with a name that says what it does.
• Read for destructive statements. Search for drop, truncate, delete and alter ... type. Each one needs a reason and, for data, a backup or a plan to restore.
• Check for locks. Adding a column with a default, or an index on a large table, can hold locks that stall the app. Test on a copy with realistic row counts.
• Make it reversible, or write the reverse migration alongside it.
• Run it on a branch or dev project first, then compare the schema with what you expected.
• Keep the data model in one place. Do not let the agent change production through the SQL tool while migration files describe something else, because the two will drift.

If you let the agent write directly to a dev project, export the resulting schema back into migration files before moving on. Otherwise the next environment you create will not match the one you tested.

What a project costs while you experiment

Experimenting with an agent tends to create projects, branches and test data. Check what each one costs before you let the agent create them. From the pricing facts we have, Supabase's free tier has a 500 MB database and pauses projects after a week of inactivity, and Pro starts at $25 a month, with Team from $599. The server's cost confirmations for actions such as creating a project exist for this reason. Branching is not included on Free, and on Pro and Team the pricing page lists $0.01344 per branch per hour, so a branch left running adds up.

Some habits keep the bill predictable. Tell the agent in your rules not to create projects or branches without asking, and leave the elicitation prompts on for those tools rather than skipping them. Delete branches when a change merges. Keep one development project for experiments, and drop test tables you no longer need. If you are on the free tier, remember that a paused project looks like an outage to a demo, so wake it before you show it.

A note on agent-written application code

The server helps with the database, and the same agent probably writes the application that uses it. Two mistakes recur in code that talks to Supabase. The first is using the service key in a place the browser can reach. That key bypasses RLS, so it belongs only on a server you control, never in front-end code or a public repository. The second is trusting a user id sent from the client. Take identity from the authenticated session on the server, and let policies use it, instead of reading a user_id field from the request body. Ask the agent to list every place the service key is used and every place user identity is read, and check both lists yourself. For related setup of other servers, see best MCP servers and the Claude Code MCP servers guide.

Real tasks with copy-ready prompts

Understand a schema

List the tables in the public schema and describe each one in a
sentence. Then tell me which tables have no row level security.

Write a migration, carefully

Draft a migration that adds a nullable "archived_at" column to
"projects" and an index on it. Show me the SQL. Do not apply it.

Debug a failing request

Query the API logs for 500 responses from the last hour and group them
by path. Show the first example of each.

Check security and performance

Run the advisors and list the security warnings, with the table each
one applies to and the fix Supabase suggests.

Types

Generate TypeScript types for the current schema and write them to
src/types/database.ts.

Pair with Context7 MCP for client library docs and GitHub MCP to open the migration as a pull request.

Limits and known issues

• Local and self-hosted versions offer a limited subset of tools, per the docs.
• Branching is experimental and needs a paid plan.
• Account tools disappear in project-scoped mode, by design.
• Elicitation support varies by client, and guardrails are not guarantees.
• Granular scopes are not available yet for manual OAuth apps; all scopes need write access.
• Custom headers are not supported by every client, which matters for CI.
• Gemini CLI version. Needs 0.20.2 or higher.
• Production caution is Supabase's own message.

Alternatives

Our take

We read Supabase's docs and repo; we did not run the server against a project.

This is one of the better-documented servers we looked at for safety. The URL options give you the three controls that matter, project scope, read-only and feature groups, and the docs lead with the prompt injection risk instead of burying it.

Our recommended setup is boring on purpose: a development project, project_ref set, read_only=true until you need a migration, and manual approval on. When you do need to apply a migration, use a branch or a dev project, review the SQL, and apply it by hand or in a session where read-only is off for that one step.

The tools that worry us are the ones that spend money or change shared state. Cost confirmation and destructive-SQL checks are good, and Supabase says not to rely on them alone.

Setup checklist

1. Create or pick a development project. Note its reference ID.
2. Build the URL with project_ref and read_only=true.
3. Add the server to your agent with the command above.
4. Authenticate in the browser and choose the right organization.
5. Ask for list_tables to confirm the scope.
6. Run the advisors.
7. Turn off read-only only for a deliberate change, and turn it back on.

Frequently asked questions

What is the Supabase MCP server URL? https://mcp.supabase.com/mcp.

How do I make it read-only? Add ?read_only=true.

Do I need a personal access token? Not normally; OAuth handles it.

Is it safe to connect to production? Supabase advises scoping, read-only and restricted groups, and a careful review of risks.

Which tools does it offer? Database, debugging, development, Edge Functions, account, docs, branching, feedback and storage groups.

*Product names are used descriptively. We are not affiliated with Supabase.*