Supabase MCP Server 2026: Claude, Cursor & Windsurf Setup

AI coding tools are only as useful as the context they have. An AI assistant that can write SQL but cannot see your schema is guessing. An AI that can suggest database changes but cannot execute them requires you to copy-paste every command. The Supabase MCP Server eliminates both problems.

The supabase mcp server connects AI tools like Claude Desktop, Cursor, and Windsurf directly to your Supabase project through Anthropic's Model Context Protocol. Your AI assistant gets full visibility into your database schema, can run queries, generate migrations, and manage infrastructure without leaving the conversation.

This guide covers everything you need to get started: installation, configuration, available tools, security best practices, and practical use cases that actually save time.

Key Takeaways

If you remember nothing else:

• The Supabase MCP Server exposes 20+ tools that let AI assistants interact with your Supabase PostgreSQL database, Edge Functions, and project settings
• Setup takes under 5 minutes with the hosted endpoint at mcp.supabase.com or via npm with npx supabase-mcp@latest
• Always use read-only mode for production databases by appending ?read_only=true to your connection URL
• Supported AI tools: Claude Desktop, Cursor, Windsurf, VS Code Copilot, Cline
• The server connects with the service role key, which bypasses Row Level Security. Treat access as admin-level
• Use cases: natural language SQL queries, schema design, automated migrations, TypeScript type generation, and database debugging

Table of Contents

1. What Is MCP?
2. What the Supabase MCP Server Does
3. Available Tools
4. Setup: Claude Desktop
5. Setup: Cursor
6. Setup: Windsurf and Other Tools
7. Setup: Local Development
8. Security Best Practices
9. Practical Use Cases
10. Limitations
11. Alternatives
12. Conclusion

What Is MCP?

The Model Context Protocol (MCP) is an open-source standard created by Anthropic in November 2024 that defines how AI models connect to external tools, data sources, and systems. Think of it as a USB-C port for AI: a universal interface that lets any compatible AI tool plug into any compatible data source.

Before MCP, connecting an AI assistant to your database required custom API wrappers, prompt engineering with schema dumps, or manual copy-pasting between tools. MCP standardizes this into a protocol that handles authentication, tool discovery, context streaming, and execution.

The supabase model context protocol implementation means your AI assistant can discover your database schema automatically, understand table relationships, and execute operations with proper context. No schema dumps. No manual setup beyond the initial connection.

MCP has been adopted by major AI providers including OpenAI and Google DeepMind, making it the emerging standard for AI tool integrations.

What the Supabase MCP Server Does

The supabase mcp server is a hosted service that translates between AI assistants and your Supabase project. When you connect an AI tool to the server, it gains access to over 20 tools that cover database management, schema operations, and project administration.

The server runs in two modes:

Hosted mode: Connect to https://mcp.supabase.com/mcp with OAuth authentication. Zero installation. Works immediately with any MCP-compatible AI tool.

Self-hosted mode: Run locally via npx supabase-mcp@latest or from the supabase-community/supabase-mcp GitHub repository. Connects to your local Supabase CLI instance at http://localhost:54321/mcp.

Both modes expose the same tools. Hosted mode is simpler for cloud projects. Self-hosted mode works for local development and air-gapped environments.

Available Tools

The mcp supabase server exposes tools across several categories. Here are the most important ones.

Database Query and Management

These are the tools you will use most. Ask your AI assistant "show me all users who signed up this week" and it translates that into SQL, executes it via query_database, and returns formatted results.

Schema and Migration Tools

The TypeScript type generation is particularly valuable. Instead of running supabase gen types manually, your AI assistant generates types inline while discussing your schema. This pairs well with Prisma or Drizzle ORMs for type-safe database access in your application code.

Project Management Tools

Database branching through MCP is useful for testing schema changes. Ask your AI to create a branch, apply a migration, verify the result, and merge it back to production, all through natural language.

RLS and Security Tools

The server does not have dedicated RLS management tools, but the query_database tool can execute any SQL, including RLS policy creation and modification. Your AI assistant can inspect existing policies through get_schema and generate new ones based on your requirements.

Setup: Claude Desktop

Claude Desktop has the most mature supabase mcp integration with full OAuth support.

Step 1: Open Claude Desktop and navigate to Settings.

Step 2: Go to the MCP section and add a new server.

Step 3: Enter the hosted endpoint URL:

https://mcp.supabase.com/mcp

Step 4: Authenticate via OAuth. Claude Desktop will open a browser window where you log into your Supabase account and authorize the connection.

Step 5: Select your Supabase project. The MCP server discovers your schema and tools automatically.

Step 6: Test the connection by asking Claude: "List all tables in my database."

For read-only access (recommended for production), use:

https://mcp.supabase.com/mcp?read_only=true

The entire setup takes under 3 minutes. Once connected, Claude has full context of your database schema and can execute queries, suggest optimizations, and generate migrations through natural conversation.

Setup: Cursor

Cursor supports MCP connections through its AI settings.

Step 1: Open Cursor Settings and navigate to the MCP configuration section.

Step 2: Add a new MCP server with the Supabase endpoint:

https://mcp.supabase.com/mcp?read_only=true

Step 3: Add your Supabase project reference and API key as authentication credentials.

Step 4: Save and restart Cursor. The MCP connection initializes on startup.

Cursor's MCP integration works well for read-only database exploration and schema inspection. Use it alongside Cursor's AI coding capabilities for a workflow where the AI sees your code and your database simultaneously.

Setup: Windsurf and Other Tools

Windsurf, VS Code with Copilot, and Cline all support MCP through similar configuration:

Step 1: Find the MCP or AI server configuration in your tool's settings.

Step 2: Add the Supabase MCP server URL with your credentials:

https://mcp.supabase.com/mcp

Step 3: Provide authentication (OAuth token or service role API key depending on the tool).

Step 4: Verify the connection by requesting schema information.

Any tool that implements the MCP client specification can connect to the supabase mcp server. The protocol is standardized, so the setup pattern is consistent across tools.

Setup: Local Development

For local development with the Supabase CLI, the MCP server runs alongside your local Supabase instance.

Step 1: Ensure the Supabase CLI is running:

supabase start

Step 2: The local MCP endpoint is available at:

http://localhost:54321/mcp

Step 3: Configure your AI tool to connect to the local endpoint instead of the hosted one.

Alternative: npm package:

npx supabase-mcp@latest --connection-string "postgresql://postgres:postgres@localhost:54321/postgres"

Local mode is ideal for development workflows where you want AI assistance without touching production data. Pair this with Supabase's free tier for a zero-cost development environment with full MCP capabilities.

Security Best Practices

The supabase mcp server connects with elevated permissions. Treat it seriously.

Use Read-Only Mode for Production

Always append ?read_only=true when connecting to production databases. This runs all queries as a restricted PostgreSQL user that cannot execute write operations (INSERT, UPDATE, DELETE, DROP). Read-only mode lets your AI explore schemas, run analytical queries, and inspect data without risk of accidental modifications.

Understand Service Role Access

The MCP server authenticates with your project's service role key. This key bypasses Row Level Security. Your AI assistant has admin-level access to all data regardless of RLS policies. This is necessary for schema management but means you should:

• Never share MCP access with untrusted tools or users
• Use read-only mode as the default
• Switch to write mode only for specific tasks on development branches
• Audit any write operations the AI suggests before approving execution

Use Database Branches for Mutations

When your AI needs to make schema changes, use Supabase database branches:

1. Create a branch via MCP: "Create a new database branch called feature-user-profiles"
2. Apply changes on the branch
3. Review the changes
4. Merge to production only after verification

This isolates AI-generated mutations from production data and gives you a review step before any change goes live.

Rotate Keys After Shared Sessions

If you use the supabase ai integration in a shared environment (pair programming, team demos), rotate your service role key afterward. The key is exposed to the MCP server session and should not persist beyond its intended use.

Practical Use Cases

Here are the workflows where the supabase mcp server saves the most time.

Natural Language Database Queries

Instead of writing SQL manually, describe what you want:

• "Show me the top 10 users by total purchases in the last 30 days"
• "How many signups happened each day this week, grouped by referral source?"
• "Find all orders where the payment status is pending and the order is older than 7 days"

The AI generates the SQL, executes it, and returns formatted results. For analytical queries on production data (with read-only mode), this eliminates the context-switch between your AI tool and a database client.

Schema Design and Review

Describe your requirements in plain language:

• "Design a normalized schema for a multi-tenant SaaS with organizations, team members, and role-based permissions"
• "Review my current schema and suggest indexes for the queries in my API routes"
• "Add a subscriptions table that references users and integrates with Stripe webhook events"

The AI inspects your existing schema, understands relationships, and generates DDL that fits your current structure. This is faster than manual schema design and catches issues like missing indexes and incorrect foreign keys.

Automated Migration Generation

Ask the AI to generate migration files:

• "Create a migration that adds an email_verified column to the profiles table with a default of false"
• "Generate a migration that creates a notifications table with a foreign key to users and a jsonb payload column"

The AI generates SQL migration files that you can review and apply through Supabase's migration system. Pair this with database branching for a safe workflow.

TypeScript Type Generation

The generate_types tool creates TypeScript interfaces from your database schema. Ask:

• "Generate TypeScript types for my entire database"
• "Create a type for the orders table including related product data"

This feeds directly into type-safe database access with Prisma or Drizzle, keeping your application types synchronized with your schema without manual updates.

Database Debugging

When something breaks, the MCP server gives your AI full diagnostic context:

• "Why is this query slow? Here is the SQL: [paste query]"
• "Check if there are any missing indexes on the orders table"
• "Show me the RLS policies on the profiles table and explain what they allow"

The AI inspects the schema, runs EXPLAIN ANALYZE, checks indexes, and provides actionable recommendations.

Limitations

The mcp supabase integration has real constraints you should know about.

Connection reliability. GitHub issues report intermittent "Project Ref Not Found" errors and connection drops, especially during OAuth token refresh. The hosted endpoint is more stable than self-hosted setups, but expect occasional reconnections.

No dedicated RLS tooling. Managing RLS policies requires raw SQL through the query tool rather than purpose-built MCP tools. The AI can generate policy SQL, but there is no structured interface for viewing and modifying policies.

Service role bypass. The MCP server connects as a service role user, bypassing all RLS. This is by design for schema management but means the AI sees all data regardless of your security policies. Read-only mode mitigates write risk but does not restrict read access.

Edge Function limitations. The server can invoke Edge Functions and manage them during branch operations, but full Edge Function deployment and editing through MCP is still maturing.

No real-time subscriptions. The MCP server handles request-response patterns. It cannot subscribe to real-time database changes or manage Supabase Realtime channels.

Alternatives

If the MCP server does not fit your setup, consider these alternatives:

The Supabase MCP Server is the best choice for teams already on Supabase because it includes ecosystem-specific tools (branching, Edge Functions, type generation) that generic Postgres MCP servers lack. For a deeper comparison of Supabase against other Postgres platforms, see our Neon vs Supabase comparison.

Conclusion

The supabase mcp server turns your AI coding assistant into a database-aware partner that can query, design, migrate, and debug your Supabase project through natural conversation. Setup takes under 5 minutes. The security model (read-only mode, database branching) keeps production data safe when used correctly.

The practical impact is real: schema design that took an hour of manual SQL now takes a 5-minute conversation. Migration files generate automatically. Debugging queries with EXPLAIN ANALYZE happens inline instead of requiring a separate database client.

Start with read-only mode on your production project. Get comfortable with schema inspection and analytical queries. Then move to write operations on development branches. The supabase ai integration through MCP is the most significant developer experience improvement Supabase has shipped since real-time subscriptions.

For teams evaluating Supabase, our Supabase pricing guide covers the free tier limits and paid plan costs, and our auth provider comparison covers how Supabase Auth stacks up against Clerk, Auth0, and Firebase.

Related Resources

• Supabase Pricing 2026: Free Tier Limits & Real Costs
• Neon vs Supabase 2026: Benchmarks, Pricing & Verdict
• Firebase vs Supabase 2026: Pricing, Real-Time & Verdict
• Supabase Row Level Security: Policies That Actually Work
• Auth Providers Compared: Clerk vs Auth0 vs Supabase vs Firebase
• Prisma vs Drizzle: Which ORM for Your Next.js Project?
• Best AI for Coding: 15 Tools Compared
• Vercel vs Railway: Deployment Platform Comparison
• How to Start a SaaS Business: The $0-to-$10K MRR Playbook