# Using Atlas with Supabase in 2026

> Supabase's MCP server gives Atlas the real table definitions and RLS policies, so the queries and typed clients it generates match your schema.

Atlas works with Supabase through Supabase's MCP server, which gives Atlas the real table definitions and RLS policies, so the queries and typed clients it generates match your schema. Add the hosted server with atlas mcp add supabase --url 'https://mcp.supabase.com/mcp?project_ref=YOUR_REF&read_only=true', then run atlas mcp auth supabase. Migrations Atlas authors land under supabase/migrations, where you review the SQL before supabase db push.

## What Supabase's MCP server gives Atlas

Supabase's MCP server gives Atlas the real table definitions and RLS policies for your project, so the queries and typed clients Atlas generates in 2026 match your schema rather than a guess, and the migrations it writes land under supabase/migrations where you can review them.

The difference between a coding agent that guesses at a Postgres schema and one that reads it is the difference between a query that runs and a query that throws. Supabase's MCP server closes that gap for Atlas. Because Atlas can pull the actual table definitions, a select it writes references columns that exist. Because it can pull the RLS policies, it knows which rows a given role is actually allowed to see, so a typed client it generates does not quietly assume superuser access. And because Atlas is a terminal-native agent, all of this happens in the same shell where you already run supabase start and supabase db push, with no context switch into a browser.

## Connecting Atlas to a hosted Supabase project

Atlas connects to a hosted Supabase project in 2 commands. Run atlas mcp add supabase --url 'https://mcp.supabase.com/mcp?project_ref=YOUR_REF&read_only=true' to register the server scoped and read-only, then run atlas mcp auth supabase to complete authentication. The project_ref query parameter scopes the server to exactly one Supabase project.

Two query parameters carry most of the safety here. The project_ref parameter pins the server to a single Supabase project, so an agent working in one repo cannot reach across into another project's tables. The read_only=true parameter means the server exposes no write path at all, which is the setting to start with while you are learning how much of your schema Atlas needs. Register the server once with atlas mcp add supabase and it persists for that workspace. The follow-up atlas mcp auth supabase command runs the authentication handshake, after which Atlas can call the server's tools during any session in that repo.

## OAuth replaced the personal access token, but a PAT still works in CI

Supabase now authenticates its MCP server with OAuth using dynamic client registration, which replaced the personal access token as the default path in 2026. A personal access token in the Authorization header still works, and that is the route to use for CI, where no human is present to complete an interactive OAuth flow.

OAuth with dynamic client registration is the right default for a laptop, because atlas mcp auth supabase can open the flow and Supabase can issue credentials without you pre-registering the client. Continuous integration is the exception. A CI runner has no browser and no human to click approve, so pass a personal access token in the Authorization header instead. Supabase kept that path working precisely for this case. Keep the token in your CI secret store and never in atlas.json, and keep read_only=true on the URL for the CI job unless the job genuinely needs to write.

## Pointing Atlas at a local Supabase stack

For a local Supabase stack, run supabase start and point Atlas at http://localhost:54321/mcp instead of the hosted URL. That gives Atlas the same table and RLS visibility against the containers on your machine, so you can iterate on a schema with zero risk to a shared Supabase project.

Local iteration is where an agent earns its keep, because the cost of a wrong query is a restart rather than an incident. Run supabase start to bring up the local containers, then register the local endpoint at http://localhost:54321/mcp. Atlas reads the same table definitions and RLS policies it would read from the hosted server, only now they are the ones in your local Postgres. This is the loop worth building a habit around: change the schema locally, let Atlas read it back, have Atlas write the query and the typed client against it, and only then decide whether the migration is ready to leave your machine.

## The stdio server: @supabase/mcp-server-supabase

The stdio package @supabase/mcp-server-supabase still exists in 2026 and remains a supported way to connect Atlas to Supabase. Run it with SUPABASE_ACCESS_TOKEN set in the environment, plus the --project-ref and --read-only flags, and Atlas talks to it over stdio rather than over HTTP.

Some teams prefer a process they launch themselves over a remote endpoint, and Supabase has not taken that option away. The stdio package @supabase/mcp-server-supabase reads SUPABASE_ACCESS_TOKEN from the environment for authentication. The --project-ref flag does the same scoping job that the project_ref query parameter does on the hosted URL, and --read-only does the same job as read_only=true. The tools Atlas sees are the same either way. Choose stdio when you want the server's lifecycle tied to your own process tree, and choose the hosted URL when you would rather not manage a local process at all.

## The daily workflow: read the schema, then write the query

The Atlas and Supabase daily loop has 1 rule: ask Atlas to read the real table and RLS policy definitions before it writes a query, then generate typed clients from them. Reading first is what turns a plausible query into a correct one against your actual Supabase schema.

State it explicitly in the prompt. Tell Atlas to read the table definitions and the RLS policies first, and only then write the query. Once Atlas has the real schema in context, generating a typed client from it is mechanical rather than speculative, and the types it emits describe columns that exist with the nullability Postgres actually declared. The same instruction pays off on the review side. When Atlas can quote the RLS policy that governs a table, you can check its reasoning about which rows a role can see instead of taking the generated code on faith.

## Migrations: supabase/migrations, then supabase db push

Have Atlas author the migration under supabase/migrations, then review the SQL yourself before running supabase db push. Atlas writes the migration file into the directory Supabase already expects, so the change flows through the same review and deploy path as any migration a human wrote in 2026.

A schema change is a production action, and the workflow here is built to keep a human in front of it. Atlas writes the migration to supabase/migrations, which is exactly where the Supabase CLI looks. That means the migration is a file in your repo, visible in a diff, reviewable in a pull request, and applied only when you run supabase db push. Read the SQL before you push it. An agent that has read your real table definitions writes better DDL than one that has not, but better is not the same as approved, and supabase db push is the line where your judgment is the gate.

## Setup

1. Add Supabase's hosted MCP server scoped and read-only: atlas mcp add supabase --url 'https://mcp.supabase.com/mcp?project_ref=YOUR_REF&read_only=true'
2. Authenticate the server with atlas mcp auth supabase, which uses OAuth with dynamic client registration.
3. For CI, pass a personal access token in the Authorization header, since a PAT still works even though OAuth replaced it as the default.
4. For a local stack, run supabase start and point Atlas at http://localhost:54321/mcp instead of the hosted URL.
5. If you prefer stdio, run the @supabase/mcp-server-supabase package with SUPABASE_ACCESS_TOKEN plus the --project-ref and --read-only flags.
6. Ask Atlas to read the real table and RLS policy definitions before it writes a query, then generate typed clients from them.
7. Have Atlas author the migration under supabase/migrations and review the SQL before you run supabase db push.

## FAQ

### how to connect Atlas to Supabase MCP server

Run atlas mcp add supabase --url 'https://mcp.supabase.com/mcp?project_ref=YOUR_REF&read_only=true', then run atlas mcp auth supabase to authenticate. The project_ref parameter scopes the server to one project and read_only=true keeps it read-only.

### does Supabase MCP still use a personal access token

OAuth with dynamic client registration replaced the personal access token as the default, but a PAT in the Authorization header still works. Use the PAT path for CI, where no interactive OAuth flow is possible.

### how do I use Atlas with a local Supabase stack

Run supabase start to bring up the local stack, then point Atlas at http://localhost:54321/mcp instead of the hosted URL. Atlas reads the same table definitions and RLS policies from your local Postgres.

### is the @supabase/mcp-server-supabase stdio package still supported

Yes. The stdio package @supabase/mcp-server-supabase still exists. Run it with SUPABASE_ACCESS_TOKEN set, plus the --project-ref and --read-only flags, and Atlas will talk to it over stdio.

### can Atlas read my Supabase RLS policies

Yes. Supabase's MCP server gives Atlas the real table definitions and RLS policies. Ask Atlas to read them before it writes a query so the query and any typed client it generates match your schema.

### where does Atlas put Supabase migrations

Atlas authors the migration under supabase/migrations, the directory the Supabase CLI already reads. Review the SQL in that file before you run supabase db push.

### how do I stop Atlas from writing to my Supabase database

Keep read_only=true in the hosted MCP URL, or pass the --read-only flag when running the @supabase/mcp-server-supabase stdio package. Atlas then has no write path through the server.

### can Atlas generate typed Supabase clients

Yes. Ask Atlas to read the real table definitions through Supabase's MCP server first, then generate the typed clients from them, so the types describe columns that actually exist in your schema.

---

Canonical HTML: https://runatlas.sh/resources/integrations/supabase
Source of truth: aeo_pages row `/resources/integrations/supabase` (segment: Integrations) (this file is generated from it, never hand-edited).
Licence: Atlas is proprietary with a free core. It is not open source and there is no public source repository.