Letting an AI agent touch your Supabase project: scoped tokens, read-only MCP and other guardrails

AI coding agents got a lot more capable this year, and most of them can now talk straight to your backend. Connect Cursor, Claude Code, Codex or Grok to the Supabase MCP server and the agent can list tables, run SQL, apply migrations and deploy Edge Functions. That is a huge speed-up while you build. It is also the fastest way to turn one bad prompt into a production incident.

On October 6, 2026, Supabase made scoped personal access tokens generally available. Together with the MCP server's own scoping options, founders now have real controls for how much an agent can touch. This guide covers how to use them on an app that already has users.

Why agent access is a different risk

A human developer with database access makes a few deliberate changes a day. An agent makes many changes quickly, and it acts on whatever text lands in its context. Supabase's own MCP documentation names the main risk directly: prompt injection. Their example is a support ticket whose description tells the model to run a query and paste the results back into a reply. When a developer later asks the agent to read that ticket, the agent may try to follow the hidden instruction using the developer's permissions.

The other risk is plainer. The agent is wrong, sounds confident, and runs a migration against the wrong project. Neither risk goes away with a better model. Both get smaller when the agent simply has less access.

The Supabase docs also say something founders should take literally. The MCP server runs with your developer permissions, so it is a tool for your team. Do not give it to your customers or end users.

Three layers of control you now have

1. Scoped personal access tokens

Before October, a personal access token was effectively your whole account. Scoped tokens change that. When you create one, you choose:

• Resources: selected projects in one organization, or all projects in selected organizations.
• Permissions: read or read-write for each capability, such as projects, database, auth or storage.
• Expiry: a preset or a custom date up to one year out.

A few details matter in practice. You can't change a token's access after you create it, so to widen or narrow access you delete it and make a new one. A token never has more access than you do, and it loses access when you do. SQL runs read-only unless the token has Database read-write. Revealing secret API keys needs its own permission, called API Key Secrets.

Existing account-level tokens keep working until they expire or you delete them. Supabase recommends swapping each one for a scoped token that has only the access its integration needs.

2. MCP server scoping

The hosted server at https://mcp.supabase.com/mcp accepts query parameters that limit what the agent can do:

• project_ref= limits the server to one project and turns off account-level tools such as creating or pausing projects.
• read_only=true runs every query as a read-only Postgres user.
• features=database,docs enables only the tool groups you list.

You can combine them, for example https://mcp.supabase.com/mcp?project_ref=abc123&read_only=true. Storage tools are already off by default.

3. Confirmations, and their limits

When your MCP client supports it, the server can pause a call and ask you to confirm. That covers the cost of creating a project or branch, and SQL it detects as destructive. Supabase describes these confirmations as a guardrail, not a promise that a person reviewed every action. Some clients can answer them automatically, and a skip_elicitations parameter turns them off for named tools. Treat a confirmation dialog as a seatbelt, not as your only control.

A sensible setup for a live app

Here is the arrangement we recommend once real customers depend on the product.

Keep a development project the agent can break

Give agents full read-write access to a development project or a branch, never to production by default. Supabase branching, on paid plans, gives each change its own database to test in before you merge. If you don't use branching, a separate development project with seed data works too. The agent should do its creative work there.

Make production read-only for agents

When you need an agent to look at production, for example to investigate a slow query or check the advisors, connect with both project_ref and read_only=true. Limit the features to what the job needs. database and debugging cover most investigations. The agent can still read data, so ask the narrowest question that answers the problem and keep personal data out of prompts.

Use a scoped token for every non-interactive use

Interactive clients normally sign in through OAuth in the browser, so you don't need a token at all. For CI jobs and scheduled scripts, Supabase documents passing a token in an Authorization header. Make that token:

1. Scoped to the one project the job touches. 2. Granted only the permissions its tools need. The docs map each MCP tool to the permission it requires. 3. Named after its purpose, such as "Staging migrations CI". 4. Set to expire, so a forgotten token dies on its own.

Store it in your CI's secret store, never in the repository. GitHub secret scanning detects both scoped and legacy Supabase tokens, but finding a leak is no substitute for never committing one.

Keep manual approval on for anything that writes

Most MCP clients ask before each tool call. Leave that on when the agent can write. For unattended monitoring, Supabase's guidance is to approve in advance only project-scoped, read-only tools, and have the routine stop and report a recommendation instead of running a write.

Ship schema changes as migrations

Even when an agent writes the SQL, the change should land as a migration file in your repository, reviewed in a pull request and applied through your normal deploy. That gives you history, review and a way back. An agent running ALTER TABLE directly on production leaves none of those.

What this does not protect

Agent guardrails protect your Supabase account. They don't fix the app itself. If Row Level Security is missing on a table, any visitor with your publishable key can read it, whatever your agent setup looks like. Run the security and performance advisors, which the MCP server exposes as get_advisors, and work through our production checks for AI-built apps before you invite users.

Secrets need the same care. The MCP server can request an Edge Function secret, but the value is typed into the Supabase dashboard and never into chat or tool arguments. Follow that rule for every secret you handle with an agent.

A ten-minute checklist

• List every personal access token on your account and note what uses each one.
• Replace each account-level token with a scoped token that names its project, its permissions and an expiry date.
• Delete tokens nobody can explain.
• Add project_ref to every MCP config in your repositories, and read_only=true to any that point at production.
• Restrict features to the tool groups each workflow needs.
• Confirm your client still asks before tool calls that write.
• Check that the agent's write access points at a development project or branch.
• Make sure schema changes reach production only through reviewed migrations.

Getting help

Most AI-built apps we see grew fast, and access grew with them. One token does everything, the agent points at production, and nobody is sure which keys are live. Untangling that is usually a short job, and it pays off the first time a prompt goes wrong. Our vibe-coded app rescue work starts with exactly this kind of review.

If you would like a second pair of eyes on how your agents, tokens and Supabase projects are wired, book a free technical assessment. We'll tell you what we find and what we would change first.