Supascale
Sign Up

Setting Up MCP for Self-Hosted Supabase: AI Coding Integration Guide

Connect Claude Code, Cursor, or Windsurf to your self-hosted Supabase using MCP. Complete setup guide with security best practices.

Cover Image for Setting Up MCP for Self-Hosted Supabase: AI Coding Integration Guide

If you're running a self-hosted Supabase instance, you've likely noticed the explosion of AI coding tools that integrate with Supabase Cloud. Claude Code, Cursor, Windsurf—they all work seamlessly with managed Supabase through the Model Context Protocol (MCP). But what about self-hosted users?

The community has been vocal about this gap. As one developer put it in a GitHub discussion: "While Supabase onboards many users via AI/vibe coding, self-hosted users feel left behind with no MCP server on the market supporting the same set of commands."

This guide shows you how to bridge that gap.

What Is MCP and Why Does It Matter?

The Model Context Protocol (MCP) standardizes how Large Language Models communicate with platforms like Supabase. Instead of copy-pasting schema definitions or manually explaining your database structure to AI assistants, MCP lets them directly inspect your tables, run queries, manage migrations, and even interact with authentication—all through natural language commands.

For Supabase Cloud users, setting up MCP takes about 30 seconds. For self-hosted users, it's more involved but absolutely achievable.

The payoff is significant: once connected, you can say things like "create a table for user preferences with RLS policies" and your AI assistant will understand your existing schema and generate contextually appropriate SQL.

Your Options for Self-Hosted MCP

There are three main approaches to getting MCP working with self-hosted Supabase:

Option 1: Official Self-Hosted MCP (With Caveats)

Supabase has documentation for enabling MCP on self-hosted instances, but there are important limitations:

  • No OAuth 2.1 authentication - The official self-hosted MCP doesn't support OAuth
  • Must not be exposed to the internet - It should only be accessed via VPN or SSH tunnel
  • Runs behind the internal API - Requires extra networking configuration

If you're comfortable with SSH tunneling and have a VPN setup, this is the most "official" route.

Option 2: Community MCP Servers

The community has built dedicated MCP servers specifically for self-hosted Supabase. The most mature option is HenkDz/selfhosted-supabase-mcp, which provides:

  • Database schema introspection and querying
  • Migration management
  • Database statistics and connection monitoring
  • Authentication user management
  • Storage bucket interaction

This is currently the most practical solution for most self-hosted users.

Option 3: Supabase CLI MCP (For Local Development)

If you're running Supabase locally with the CLI, you automatically get access to MCP at http://localhost:54321/mcp. This is the simplest option for development environments but doesn't help with production self-hosted instances.

Setting Up Community MCP: Step-by-Step

Let's walk through setting up the HenkDz MCP server, which works with Claude Code, Cursor, and other MCP-compatible tools.

Prerequisites

Before starting, ensure you have:

  • A running self-hosted Supabase instance with proper security configurations
  • Node.js 18 or higher
  • Your Supabase connection details (URL, keys, database credentials)

Installation

The easiest installation method uses Smithery:

npx -y @smithery/cli install @HenkDz/selfhosted-supabase-mcp --client claude

For manual installation:

git clone https://github.com/HenkDz/selfhosted-supabase-mcp.git
cd selfhosted-supabase-mcp
npm install
npm run build

Configuration for Claude Code

Create or edit ~/.claude/mcp.json:

{
  "mcpServers": {
    "selfhosted-supabase": {
      "command": "npx",
      "args": [
        "-y",
        "@anthropic/mcp-server-selfhosted-supabase"
      ],
      "env": {
        "SUPABASE_URL": "https://your-supabase-instance.com",
        "SUPABASE_ANON_KEY": "your-anon-key",
        "SUPABASE_SERVICE_ROLE_KEY": "your-service-role-key",
        "DATABASE_URL": "postgresql://postgres:password@host:5432/postgres"
      }
    }
  }
}

Configuration for Cursor

Create .cursor/mcp.json in your project root:

{
  "servers": {
    "selfhosted-supabase": {
      "command": "node",
      "args": ["/path/to/selfhosted-supabase-mcp/dist/index.js"],
      "env": {
        "SUPABASE_URL": "https://your-supabase-instance.com",
        "SUPABASE_ANON_KEY": "your-anon-key",
        "SUPABASE_SERVICE_ROLE_KEY": "your-service-role-key"
      }
    }
  }
}

After saving, restart your AI tool to detect the new MCP server.

Security Considerations You Can't Ignore

Here's where self-hosted MCP requires extra caution. The official Supabase documentation is blunt: "Do not allow connections to the self-hosted MCP server from the Internet."

Why This Matters

MCP servers with service role keys can:

  • Read and write any data in your database (bypassing RLS)
  • Manage authentication users
  • Access and modify storage buckets
  • Run arbitrary SQL queries

An exposed MCP server is essentially giving full database access to anyone who finds it.

For development environments:

Use a separate development project with non-production data. If you're using Supascale to manage multiple projects, spinning up an isolated dev instance takes seconds.

For production access (if absolutely necessary):

  1. Never expose MCP directly - Run it only on localhost or behind a VPN
  2. Use SSH tunneling - Connect through a secure tunnel to your server:
    ssh -L 8080:localhost:8000 user@your-supabase-server
  3. Restrict to specific IPs - Configure your reverse proxy to only allow connections from known IPs
  4. Use read-only credentials when possible - Create a database user with limited permissions for MCP exploration

Prompt Injection Risks

An often-overlooked risk: malicious content in your database could potentially influence AI behavior. If your database contains user-generated content, an attacker could craft data that instructs the AI to execute harmful queries.

Mitigation: Always keep the "manual approval" setting enabled in your MCP client. Cursor, for example, asks you to approve each tool call before execution. Never disable this for MCP connections with write access.

What MCP Actually Enables

Once configured, here's what you can do with your self-hosted Supabase through AI coding tools:

Schema exploration: "What tables exist in my database and how are they related?"

Migration generation: "Create a migration to add a preferences JSONB column to the users table with a default value"

RLS policy creation: "Add row-level security to the posts table so users can only see their own posts"

Query building: "Write a query to find users who signed up in the last 30 days but haven't created any posts"

Auth management: "How many users signed up this week? Show me a breakdown by auth provider"

The AI assistant has full context of your schema, so generated code is actually relevant to your project—not generic examples.

Limitations of Self-Hosted MCP

Being honest about trade-offs, here's what you won't get with self-hosted MCP:

  • No OAuth 2.1 - Cloud users get proper OAuth flows; self-hosted relies on API keys
  • Limited official support - Community servers are maintained by volunteers
  • Manual updates - You're responsible for keeping the MCP server updated
  • No managed authentication - You handle all the security yourself

For many teams, especially those already self-hosting for compliance reasons, these trade-offs are acceptable. You're already managing your own infrastructure; MCP is just another component.

Debugging Connection Issues

If your MCP connection isn't working:

Check the basics first:

# Verify Supabase is accessible
curl https://your-supabase-url/rest/v1/ \
  -H "apikey: your-anon-key"

Verify environment variables: The MCP server needs all credentials to be correctly set. Missing or incorrect keys will fail silently in some configurations.

Check MCP client logs:

  • Claude Code: Check the output panel for MCP-related messages
  • Cursor: Settings > Cursor Settings > Tools & MCP shows connection status

Test with the Supabase CLI first: If you can't get self-hosted MCP working, try the CLI's built-in MCP at localhost:54321/mcp to verify your MCP client is correctly configured.

The Future of Self-Hosted MCP

Supabase has acknowledged the gap between cloud and self-hosted MCP experiences. According to recent GitHub discussions, the team is aware that self-hosted users want feature parity.

The MCP ecosystem is also evolving rapidly. The protocol is moving toward "remote MCP" with dynamic client registration, and PAT-based auth is being phased out. Future versions may bring OAuth 2.1 to self-hosted deployments.

For now, community solutions like the HenkDz MCP server fill the gap effectively for most use cases.

Getting Started

If you're new to self-hosting Supabase, start with our deployment guide before setting up MCP. For existing self-hosted users, the community MCP server can be running in under 10 minutes.

Want a simpler way to manage your self-hosted Supabase projects? Supascale handles deployment, backups, and project management with a one-time purchase—letting you focus on building rather than infrastructure. Check out our pricing to see how it compares to managing everything yourself.

Further Reading