Catalog My learning Blog
MCP Setup Guides: Cursor, Codex, Gemini CLI and Top Servers · Phase 2 · Lesson 9 · 4 min read

Supabase MCP Server Setup: Read-Only and Project Scope

On this page
  1. What it's good for, and the risk
  2. Step 1: build your URL
  3. Step 2: add it to your tool
  4. What the agent can do
  5. Rules for using it safely
  6. Check it works
  7. Check yourself

What it's good for, and the risk

Connected to Supabase, an agent can create a table, write the migration, generate TypeScript types and check the advisors for missing indexes or row level security gaps. That's a big speed-up when you're building.

It's also a database connection driven by a language model. Supabase's own docs warn that production projects can contain sensitive data and that prompt injection is a risk. So this guide sets up the safe version first, and shows how to open it up when you need more.

Step 1: build your URL

The hosted server lives at https://mcp.supabase.com/mcp. Query parameters control what it can do:

ParameterEffect
project_ref=<id>Limits the server to one project and hides account-wide tools
read_only=trueRuns every query as a read-only Postgres user
features=database,docsTurns on only the listed tool groups

Find your project ref in the project's URL in the Supabase dashboard. A safe starting point for a project with real data looks like this:

Code
https://mcp.supabase.com/mcp?project_ref=abcdefghijklmnop&read_only=true

For a throwaway development project, you can drop read_only so the agent can apply migrations.

Step 2: add it to your tool

The hosted server signs you in with OAuth, so you don't need a personal access token. The first time the server is used, a browser window asks you to log in and pick the organization that holds your project.

Claude Code (project scope, so the team shares it):

Code
claude mcp add --scope project --transport http supabase \
  "https://mcp.supabase.com/mcp?project_ref=abcdefghijklmnop&read_only=true"

Then start Claude Code, run /mcp, select supabase and choose Authenticate. Keep the quotes around the URL: without them, your shell treats & as "run in the background".

Cursor (.cursor/mcp.json):

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

VS Code (.vscode/mcp.json):

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

Codex CLI starts the OAuth sign-in as soon as you add it:

Code
codex mcp add supabase --url "https://mcp.supabase.com/mcp?project_ref=abcdefghijklmnop&read_only=true"

What the agent can do

Tools come in groups. The ones you'll use most:

  • Database: list_tables, list_extensions, list_migrations, apply_migration, execute_sql
  • Debugging: query_logs, get_advisors (security and performance advice)
  • Development: get_project_url, get_publishable_keys, generate_typescript_types
  • Docs: search_docs, for questions about Supabase itself

There are also groups for Edge Functions, branching (experimental, paid plans) and storage, which is off by default. Account management tools disappear when you set project_ref, which is one more reason to set it.

Rules for using it safely

Supabase's documentation is direct about this, and the advice is good:

  • Use it as a developer tool. Don't connect it to an app your customers use.
  • Prefer a development project. Connect to production only when the task needs production evidence, and then with project_ref and read_only=true.
  • Keep manual approval on. Read each execute_sql and apply_migration call before you approve it. Data in your tables can contain text that tries to instruct the agent, and approval is your chance to catch it.
  • For unattended runs, such as a CI job, pre-approve only the project-scoped, read-only tools that job needs. CI can't do the browser sign-in, so it uses a personal access token in an Authorization: Bearer header instead.
TipRunning Supabase locally with the CLI? The local stack serves MCP at http://localhost:54321/mcp. It has fewer tools and no OAuth, which is fine for local experiments.

Check it works

Ask: "List the tables in my Supabase project and how many rows each has." You should see list_tables, maybe followed by execute_sql with a count query. If you set read_only=true, try "drop the todos table" in a test project. The call should fail, which proves the guard is working.

Check yourself

project_ref for that one project and read_only=true. Optionally add features= with only the tool groups you need.

The URL contains &, which the shell would otherwise treat as an operator and cut the URL short.

Don't. Supabase recommends it only as an internal developer tool, because of the data access and prompt injection risk.