Unclear how to use the MCP server with multiple projects

[scopendo]

Improve documentation

Link

Supabase MCP server docs

Describe the problem

If I have multiple Supabase projects, either in the same org or different orgs, it's not clear how we can set up an AI coding assistant to have MCP access to each project, without disabling and re-enabling.

I seem to end up in a loop of OAuth authorisation requests, and confusion as to which MCP server gets used despite telling the agent to use a specifically named agent e.g. use MCP server named supabase-project1 and verify that it is for a project with id xyz. In my case, I'm using the Codex app.

Describe the improvement

Perhaps allow a single MCP to be set up for multiple projects with the requirement to confirm the project id (other MCP servers like Sentry seem to do this OK), or provide guidance on the recommended approach for multiple, which perhaps is simply enabling / disabling parallel MCP servers.

[farmhutsoftwareteam]

I ran into this exact problem — here's what ended up working for me.

The trick is a .mcp.json file at your project root with two separate named server entries, each pinned to a different --project-ref:

{
  "mcpServers": {
    "supabase": {
      "type": "stdio",
      "command": "npx",
      "args": ["-y", "@supabase/mcp-server-supabase@latest", "--project-ref=<staging-ref>"],
      "env": { "SUPABASE_ACCESS_TOKEN": "<your-pat>" }
    },
    "supabase-prod": {
      "type": "stdio",
      "command": "npx",
      "args": ["-y", "@supabase/mcp-server-supabase@latest", "--read-only", "--project-ref=<prod-ref>"],
      "env": { "SUPABASE_ACCESS_TOKEN": "<your-pat>" }
    }
  }
}

A few things worth knowing:

• Same token for both — PATs are org-scoped so one token covers all your projects
• --project-ref locks the server at startup — each process only ever talks to one project, which is why the "tell the agent to use server X" approach actually works reliably here. In Claude Code for example the tools get namespaced: mcp__supabase__* vs mcp__supabase-prod__*
• --read-only on prod — worth doing; it restricts to SELECTs at the protocol level so you can't accidentally run DDL against production
• The OAuth loop issue — this happens because project scope is resolved at process startup. A single server trying to switch projects mid-session has to re-authenticate, which is what causes the loop. Two processes sidesteps this entirely

Generate a PAT at supabase.com/dashboard/account/tokens if you haven't already — that's what goes in SUPABASE_ACCESS_TOKEN and kills the OAuth prompts.

[scopendo]

Thanks @farmhutsoftwareteam, that's "supahelpful".

It suggests even more that the documentation needs updating as it doesn't mention supabase/mcp-server-supabase only the remote MCP endpoint.

I did have two MCP servers defined previously, so it wasn't a single server trying to switch projects, so not sure what the deal is there, but the approach you took the time to make clear is working nicely.

[AnuragRaut08]

Hi! I’ve opened a PR adding documentation for configuring multiple Supabase MCP server instances across multiple projects.