Your data lives in Postgres. Your questions live in English. Learn how the Supabase MCP integration bridges that gap — live schema inspection, real SQL execution, and natural-language database exploration, all from a single conversation with Claude.
mcp.supabase.com/mcp that exposes database, documentation, debugging, and management tools to AI clients.read_only=true) enforces SELECT-only SQL and disables every mutating tool — critical for safe production connections.project_ref) restricts Claude to one specific Supabase project, hiding account-level tools like create_project or list_organizations.Model Context Protocol (MCP) is an open communication standard, created by Anthropic, that defines how AI models like Claude connect to external data sources and tools. Think of it as a universal plug — instead of building a custom integration every time you want Claude to talk to a new service, MCP provides a shared language both sides already speak.
Before MCP existed, connecting an AI assistant to your Postgres database meant writing custom API wrappers, managing connection pools, and hoping the schema you documented still matched production. MCP changes that by standardizing the handshake between Claude and any tool that implements the protocol.
An MCP server is a lightweight service that sits between Claude and your data source. It exposes specific tools — like execute_sql or list_tables — that Claude can call during a conversation. Claude doesn't need to know how Postgres wire protocol works; it just needs to know what tools are available and what arguments they accept. The server handles the rest.
Supabase is an open-source backend platform built on Postgres. It gives you a full Postgres database with automatic REST and realtime APIs, plus built-in authentication, storage, and Edge Functions. Because Supabase maintains its own officially hosted MCP server, you don't have to run any infrastructure yourself — you point Claude at mcp.supabase.com/mcp, pass a token, and you're connected.
The Supabase MCP integration works by running requests through Supabase's hosted MCP server, which translates Claude's tool calls into real database operations against your project. You authenticate with a Personal Access Token (PAT) generated from your Supabase account settings, and the server enforces the token's permissions on every query.
Here's the flow in plain terms: you ask Claude something like "how many customers signed up in each country last month." Claude identifies that this needs a database query, calls the execute_sql tool on the Supabase MCP server with your project_ref, and the server runs the SQL against your Postgres instance. Results come back as structured JSON; Claude presents them in natural language. The whole round-trip takes a couple of seconds.
The Supabase MCP server organizes capabilities into feature groups. You choose which groups are enabled via the features URL parameter. The most commonly used tools:
| Tool Name | What It Does | Example Claude Prompt |
|---|---|---|
list_tables | Returns every table in the project with column names and types | "What tables exist in this database?" |
execute_sql | Runs arbitrary SQL — SELECT only when read_only=true is set | "Show me the 10 most recent orders with customer names" |
apply_migration | Runs DDL (CREATE TABLE, ALTER, etc.) inside a tracked migration | "Add an archived_at column to the posts table" |
list_extensions | Lists installed Postgres extensions like pgvector or PostGIS | "Does this project have pgvector enabled?" |
search_docs | Semantic search against Supabase's current documentation | "How do Row Level Security policies work?" |
Getting Claude talking to a Supabase project takes under ten minutes. You don't need to host anything yourself — Supabase's hosted MCP server is the endpoint.
In your Supabase dashboard, click your avatar and go to Account → Access Tokens. Generate a new token with a descriptive name like "Claude MCP access." Copy the value immediately; you won't see it again. Store it somewhere secure — a password manager or your system keychain — not a plaintext config file in version control.
Open your project and go to Project Settings → General. Your project_ref is the 20-character alphanumeric string under Project ID. You'll also see it as the subdomain of your project URL (the part before .supabase.co). Keep it handy for step 3.
The Anthropic Messages API supports remote MCP servers directly via the mcp_servers parameter. Pass the server URL with your query parameters, and the authorization token. Claude automatically discovers the available tools:
const response = await fetch("https://api.anthropic.com/v1/messages", {
method: "POST",
headers: {
"Content-Type": "application/json",
"x-api-key": YOUR_ANTHROPIC_API_KEY,
"anthropic-version": "2023-06-01",
"anthropic-beta": "mcp-client-2025-04-04"
},
body: JSON.stringify({
model: "claude-haiku-4-5-20251001",
max_tokens: 1024,
messages: [{ role: "user", content: "List all tables in the demo schema" }],
mcp_servers: [{
type: "url",
url: "https://mcp.supabase.com/mcp?project_ref=YOUR_REF&read_only=true&features=database",
name: "supabase",
authorization_token: YOUR_SUPABASE_PAT
}]
})
});Two URL parameters make this connection safe enough for real projects. read_only=true forces execute_sql to run inside a read-only Postgres transaction, which rejects any INSERT, UPDATE, DELETE, or DDL statement at the database level. Mutating tools like apply_migration and create_project are disabled entirely when this flag is set.
The features parameter lets you expose only the tool groups you need. Passing features=database,docs hides storage, functions, branching, debugging, and account-level tools from the session. Less surface area means fewer ways for a prompt injection inside your data to convince Claude to do something you didn't want.
Analysts often know what question they want answered but not the exact SQL to get there. With Claude connected via Supabase MCP, you can ask "which product categories had the highest growth in orders from Q1 to Q2" in plain English. Claude calls list_tables to understand the schema, writes the right JOIN and GROUP BY, runs it, and explains the results. The time from question to answer drops from twenty minutes to twenty seconds.
New engineers joining a team usually have to map out an unfamiliar production database before they can contribute anything useful. Claude with the Supabase MCP connection can do that work in minutes. "What tables handle user authentication? What foreign keys connect orders to payments? What indexes are missing on the events table?" The answers come from the live database, not a stale ERD diagram that someone drew three years ago.
Supabase's branching feature creates an isolated database branch for testing schema changes. Connect Claude to the branch's project_ref instead of production, and you can ask it to design and apply migrations without risking your main data. Review what Claude did in the branch, run tests against it, then promote the migration when you're satisfied.
When a customer reports a bug, support engineers often need to query production to see what actually happened — which user, which timestamp, which related records. A read-only Supabase MCP connection lets Claude help triage these tickets: "find all events for user ID 48291 in the last two hours, grouped by type." No admin panel, no custom tool, no risk of accidental writes.
| Access Method | Setup Time | Real-Time Data | Natural Language | Write Safety |
|---|---|---|---|---|
| Supabase MCP + Claude | 10 minutes | Yes | Yes | read_only=true enforces at DB level |
| Custom BI Dashboard | Days to weeks | Yes | Limited | Varies per tool |
| psql / Direct SQL Client | Minutes | Yes | No | Depends on role permissions |
| Zapier / Make Middleware | Hours | Lag | No | Often full-access API keys |
Supabase is explicit about the security posture of its MCP server: the documentation recommends using it for development, not production. The PAT you generate inherits your account's permissions, which means anyone holding the token can see whatever you can see. Rotate PATs on a schedule and revoke them the moment they're no longer needed.
For any connection touching real data, read_only=true should be your default, not an afterthought. Pair it with project_ref scoping so a stray prompt can't enumerate other projects in your organization. And keep feature groups minimal — this demo only exposes the database group, which is all it needs.
Try a real Supabase query powered by Claude and MCP — live Postgres data, real results, read-only and scoped to a public bookstore schema.
Open the Live Demo →