Supabase MCP Setup

Why First: The Context Switch Problem

You're in the middle of writing a query. You need to know the exact column names in the fee_records table — not paid_date, or is it paid_at? Or did you rename it last week?

Without the MCP, your workflow is:

1. Save what you're doing in VS Code
2. Open a browser
3. Go to supabase.com/dashboard
4. Log in (if your session expired)
5. Click on the project
6. Navigate to the Table Editor
7. Find the fee_records table
8. Check the column names
9. Switch back to VS Code
10. Continue writing

That's 60–90 seconds of context switching. You do this 10 times in a session. That's 15 minutes of friction — plus the mental cost of breaking your concentration each time.

With the MCP, that same workflow is:

In Claude Code: "What columns does the fee_records table have?" Claude: "The fee_records table has: id, student_id, fee_structure_id, amount, status, due_date, paid_at, payment_id, created_at." Time: 5 seconds. Never left VS Code.

What the MCP Is

MCP stands for Model Context Protocol — a standard that lets Claude Code talk directly to external services. The Supabase MCP server is a small program that runs alongside Claude Code and acts as a bridge between Claude and your Supabase account.

Once set up, Claude can:

• List your Supabase projects and their tables
• Query data directly: "Show me all fee records with status 'overdue' from this month"
• Apply SQL migrations to your project
• Read table schemas on demand — so it always knows the current shape of your database
• Deploy edge functions
• Check logs for errors

Think of it as giving Claude Code a direct line to your Supabase dashboard — the same information you'd get by clicking around the UI, but available as conversational answers without the context switch.

Prerequisites

Before setting up the MCP, you need:

1. A Supabase access token (from the API Keys page — the one starting with sbp_...)
2. Node.js installed (already done in the setup manual)
3. Claude Code installed and working

Setup: Adding the MCP to Claude Code

The MCP is configured in Claude Code's settings file. Here's how to add it:

Step 1: Get your access token

If you haven't already: Supabase dashboard → click your avatar (top-right) → Account → Access Tokens → Generate new token.

Account → Access Tokens — the page where you generate sbp_... personal access tokens. The "Generate new token" button is highlighted.

Name it something clear: Claude MCP - [your name]

Copy it immediately. Save it to VaultMate:

• Category: Token
• Title: Supabase Platform Access Token - MCP
• Secret: sbp_xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx

Step 2: Open Claude Code settings

The global Claude Code config file is at:

• Windows: C:\Users\YourName\.claude\claude.json
• macOS/Linux: ~/.claude/claude.json

Open this file in VS Code (or create it if it does not exist).

Step 3: Add the MCP server configuration

Add the following mcpServers section to the file, replacing sbp_your_actual_token_here with your actual access token:

The key part: "url": "https://mcp.supabase.com" and your sbp_... token in the Authorization header value.

Step 4: Restart Claude Code

Close Claude Code completely and reopen it. Type claude in your terminal to start a fresh session. The MCP server will not load until Claude Code restarts.

Step 5: Test the connection

In Claude Code, type List my Supabase projects. and press Enter.

Claude should respond with a list of your projects, including their names and reference IDs. If it does, the MCP is working.

If you see an error like "tool not found" or "MCP server not responding," see the troubleshooting section below.

How to Use the MCP in Sessions

Once connected, you interact with your Supabase project through natural language. Claude handles the translation to actual Supabase API calls.

Checking table structure:

Querying data:

Applying SQL:

Applying a migration:

Listing all tables:

Checking for errors or security issues:

The Workflow This Enables

The MCP is most powerful when combined with the CLAUDE.md pattern you learned in the Claude Code module. When your project's CLAUDE.md contains the Supabase project ref:

Claude automatically knows which project to target in every MCP call. You don't have to specify the project ref in every message — Claude reads it from CLAUDE.md at the start of every session.

This means a conversation like this works seamlessly:

Claude found the bug by checking the real database, not by guessing.

Project-Level vs Account-Level MCP

The MCP token you set up is account-level — it has access to all your Supabase projects. This is intentional: you work across multiple projects, and having one token that covers all of them is more practical than managing one token per project.

The trade-off is that the token is powerful. Guard it accordingly:

• One copy in VaultMate
• One copy in ~/.claude/claude.json (your machine only)
• Nowhere else

When Claude Code queries a specific project, you direct it using the project ref (abcdefghijklmnop). The MCP knows which project you mean because you tell it — either in the prompt or via CLAUDE.md.

Troubleshooting

"MCP server not found" or Claude doesn't recognize Supabase commands:

• Confirm the claude.json file is saved and valid JSON (no trailing commas, all brackets closed)
• Restart Claude Code completely
• Run npx @supabase/mcp-server-supabase@latest --help in your terminal — if this errors, Node.js or npx has a problem

"Authentication failed" or "Invalid token":

• Confirm the token in claude.json starts with sbp_
• Check if the token has been revoked in Supabase dashboard → Account → Access Tokens
• Generate a new token and update claude.json

Claude can list projects but can't query tables:

• Make sure you're specifying the correct project ref
• Confirm the project still exists and you're the owner/admin

The MCP works for listing projects but errors on SQL execution:

• Some SQL operations require specific permissions. Check that your access token has full project access, not read-only.

What Changes After Setup

This is one of the setup steps that feels like a minor convenience at first and becomes essential within a week.