Supabase MCP: Setup + Use Cases (2026)

A bug shows up in production. You open the Supabase dashboard, click into the table editor, write a SQL query to find the bad rows, scroll the logs to see what the edge function did, then copy all of it into Claude to ask what went wrong. Half your debugging time is spent being the courier between the dashboard and the AI, moving query results back and forth by hand.

Supabase MCP closes that loop. Instead of you shuttling data between the dashboard and the chat, the AI reads your database itself. You ask “which users signed up this week but never verified their email?” and Claude writes the SQL, runs it against your Postgres, and reads the answer back, without you touching the table editor.

Supabase ships an official MCP server, hosted at mcp.supabase.com, and it reaches the whole platform. Postgres, auth, storage, edge functions, logs, and project management, all callable in plain language from Claude, Cursor, and the rest. This guide covers what it actually does, the setup for each client, the use cases worth the slot, and the one security rule that separates a useful setup from a scary one.

What Supabase MCP actually does

The Model Context Protocol is an open standard Anthropic released in late 2024. It defines how an AI client talks to an external tool. A server exposes a set of tools, the client calls them mid-conversation, and the results flow straight back into the model’s reasoning. No copy-paste, no export, no leaving the chat.

Supabase is an open-source backend platform built on Postgres. It gives you a database, authentication, file storage, and edge functions behind one project. The MCP server wires all of that to an AI client. When Supabase shipped the server, it framed the point plainly. Your assistant can query and manage your Supabase projects on your behalf.

The tool set is wide. You get SQL execution against your database, table and schema listing, migration apply and list, edge function deploy and list, log retrieval, security and performance advisors, TypeScript type generation from your schema, documentation search, and branch management for safe testing. The full list lives in the Supabase MCP docs and the open-source repo. In practice you never memorize it. You ask a question and the agent picks the tool.

That reach is the whole appeal and the whole risk. A server that can read your data, change your schema, and ship code is far more powerful than one that only reads deploy logs. Powerful cuts both ways, which is why the security section below is not optional reading.

”Supabase MCP” means two things

Here is the confusion nobody clears up first, and it sends half the people searching “supabase mcp” down the wrong path.

There are two separate things with almost the same name.

Using Supabase MCP: Connecting your AI client to your Supabase account so it can query and manage your project. This is what this guide is about, and it is what almost everyone wants.

Deploying an MCP server on Supabase: Hosting your own MCP server on Supabase Edge Functions so other people’s agents can call it. That is a build task, covered in the deploy MCP servers docs, and it has nothing to do with letting Claude read your own database.

If you are a founder or a developer who runs on Supabase and wants Claude to help you query and debug, you want the first one. If you are building an MCP product and want a place to host it, you want the second one. The rest of this post is the first one.

How to connect Supabase MCP to your AI client

The connection is the same underneath for every client. It is the hosted server at mcp.supabase.com/mcp, authenticated with OAuth. A personal access token used to be required, and as of 2026 it no longer is, so no long-lived secret sits in a config file. What changes per client is the front door.

Scope it to one project: This is the step to do before anything else. Add your project reference to the URL as a query parameter, so the URL becomes https://mcp.supabase.com/mcp?project_ref=your-project-ref. You find the project ref in your Supabase project settings. Scoping stops the agent from ever seeing another project’s data, and it is the cheapest safety win on the list.

The fast path for Claude Code: In your project, run claude mcp add --transport http supabase "https://mcp.supabase.com/mcp?project_ref=your-ref&read_only=true". Start Claude Code with claude, type /mcp, and finish the OAuth sign-in in the browser. Ask “list the tables in my database” to confirm the tools loaded.

The fast path for Claude Desktop: Go to Settings, then Connectors, then Add custom connector. Paste the scoped URL, name it “Supabase,” and save. Claude sends you to Supabase to sign in and approve access. Then fully quit and reopen Claude Desktop. A window reload does not pick up a new connector, and that single missed step is behind most “my server is not working” complaints.

Cursor: Add the server to .cursor/mcp.json with the same URL, then click the “Needs login” prompt to authorize. Cursor also honors the read-only and project scoping you set in the URL, so set them there once and every client inherits them.

What you can actually do with it once connected

A connected database feels abstract until you have used it for a week. Here is the short list people actually reach for.

Query your data in plain English: “How many active subscriptions do we have, broken down by plan?” The agent writes the SQL, runs it, and reads the numbers back. You skip the table editor and the query you would have half-remembered the syntax for.

Debug a live issue against real rows: “Find users who hit the payment error in the last hour and show me their last event.” The agent joins the tables, reads the logs, and hands you the shortlist. The production round trip from the intro collapses into one prompt.

Design a schema without hand-writing migrations: “Add a referral_code column to the users table and a unique index on it.” With write access on a dev branch, the agent drafts the migration, applies it, and you review the change. On a read-only connection it writes the migration for you to run yourself.

Catch problems before they ship: Supabase exposes security and performance advisors as tools. “Run the advisors and tell me what is unsafe” surfaces missing row-level security policies and slow-query risks in a sentence, instead of you clicking through the dashboard.

“Write the SQL to find every order stuck in ‘pending’ for more than an hour, run it read-only, and summarize what they have in common.”

That single prompt replaces a table-editor session, a query you would have googled, and a copy-paste into chat. That is the shape of the win. Not magic, just the database work you were going to do anyway, asked in one line.

The security rule you should never skip

Most MCP wedge posts put limits at the end as a footnote. For Supabase, the security section is the main event, because this is a server that can write to a database and deploy code. Get this wrong and the failure is not a slow answer, it is a leaked table.

In July 2025, security researchers showed a real attack. An agent connected to Supabase with the powerful service_role was reading customer support tickets. One ticket contained hidden instructions written to look like normal text. The agent read them as commands and ran SQL it was never meant to run, exposing data behind row-level security. Simon Willison wrote it up as a textbook “lethal trifecta”, an agent that has private data, sees untrusted text, and can act on it. All three legs present, and the door is open.

Supabase responded with a defense-in-depth guide and a set of defaults. You should treat them as rules, not suggestions.

Turn on read-only: Add read_only=true to the server URL. It runs every query as a read-only Postgres user and disables migrations, project creation, and edge function deploys. Read-only removes the “can act” leg of the trifecta. For any connection touching real user data, this is the default posture, not an optional flag.

Scope to one project: The project_ref parameter walls the agent off from every other project in your account. No reason to give it a whole account when it needs one database.

Never connect production with write access: Point the server at a development branch. Supabase branching spins up an isolated copy of your database so an agent can experiment, apply migrations, and break things without touching live data. Merge to production yourself, after you have read the diff.

Keep manual tool approval on: Every serious client can prompt you before it runs a tool. Leave that on for a database server. The one time it asks before running a DELETE you did not expect is the day it pays for itself. The broader checklist is in is MCP safe.

The mistakes that break Supabase MCP setups

The same handful of issues come up over and over.

Running it write-enabled on production: The most dangerous default. If you skip read_only=true and point at your live project, one bad prompt or one poisoned input can change real data. Read-only plus a dev branch is the safe shape.

Forgetting to scope the project: Without project_ref, the agent can reach every project your login owns. Scope it, every time, even for a quick test.

Reloading instead of restarting: Claude Desktop reads its connector list at full startup only. Reload Window does nothing. Quit fully, reopen, then check.

Expecting a token prompt: People search for where to paste a personal access token and get stuck when there is no field. The 2026 server uses OAuth. You sign in through a browser, you do not paste a secret.

Confusing the two “supabase mcp” things: Someone lands on the deploy-your-own-server docs, gets lost in Edge Functions and the mcp-lite adapter, and concludes the setup is hard. It is not. If you only want Claude to read your database, ignore everything about hosting.

Running too many servers at once: Each MCP server is a subprocess with startup and memory cost. Past ten, you feel it. Three to six is the sweet spot, and a database server is a high-value slot for anyone shipping on Supabase daily. For more picks, see the best MCP servers for knowledge workers.

Why your saved research belongs next to your database

Here is the gap nobody setting up Supabase MCP talks about. Your database is only half of what you know about your own project.

The other half is everything you saved and never filed. The X thread that explained the exact row-level security policy pattern you keep getting wrong. The Reddit post about a Supabase connection-pool limit with a workaround in the comments. The LinkedIn post from an engineer about Postgres index bloat. That context shapes how you build, and none of it is in Supabase. It is trapped in a bookmarks tab across three platforms.

Supabase MCP gives Claude your live schema and your data. It does not give Claude the scattered fixes and gotchas you collected getting to this point. So you get an assistant that can read the error but has never seen the thread that solved it last time.

This is where a bookmarks MCP earns its slot next to the Supabase one. ContextBolt is a Chrome extension that captures what you save on X, Reddit, and LinkedIn, tags each save by topic automatically, and exposes the whole collection through a personal MCP endpoint. The free Basic tier covers 150 bookmarks. Pro at $6 a month adds unlimited saves, encrypted cloud sync, and the MCP endpoint any client can call.

Wire it in the same way you wired Supabase. Add the custom connector, paste your endpoint, restart. Now Claude reads both halves in one prompt. “This query is slow, and pull anything I saved about Postgres indexing” returns the query plan and the three threads you bookmarked about that exact problem. The database tells you what is happening. Your bookmarks tell you how you fixed it before. For the bigger picture of feeding an agent your own context, see the personal AI context stack.

The one opinion worth holding

Supabase MCP is the most powerful server in the wedge and the one most people set up wrong. Both of those come from the same fact. It can write.

Vercel MCP is read-only, so you can be careless with it and the worst case is a slow answer. Supabase MCP hands an agent a live database, so the worst case is real. That is not a reason to avoid it. It is a reason to use it the way Supabase spells out. Read-only for anything touching real data, scoped to one project, pointed at a dev branch, with tool approval on. Do that, and you get the best half of the workflow, which is an assistant that reads and reasons about your data instantly, with the dangerous half fenced off.

The other thing worth saying plainly. The server you connect matters more than the client you connect it to. Claude Code, Claude Desktop, and Cursor all read the same Supabase server, so wiring it up once pays off everywhere. The same is true for the second half of your context. Connect your database, connect your bookmarks, and the assistant finally knows both what your data says and how you learned to work with it. That is the whole setup. Everything else is detail.