Skip to content

Docs/multi project setup #290

New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

Sign up for GitHub

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Open
AnuragRaut08 wants to merge 3 commits into
base: main
Choose a base branch
from
Open

Docs/multi project setup #290

Changes from all commits
Commits
Show all changes
3 commits
Select commit Hold shift + click to select a range
804c6c5
docs: add guide for configuring multiple Supabase projects
May 21, 2026
3257d46
docs: fix production MCP configuration example
May 21, 2026
00603a6
docs: improve multi-project MCP configuration guidance
AnuragRaut08 Jun 6, 2026
File filter

Filter by extension

Filter by extension
Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
55 changes: 55 additions & 0 deletions README.md
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -87,6 +87,61 @@ We recommend enabling this setting by default. This prevents write operations on
`rebase_branch`
`update_storage_config`.




### Using multiple projects simultaneously

If you work across multiple Supabase projects (in the same org or different orgs), you can run multiple named MCP server instances — one per project — rather than switching a single server between projects.

> [!NOTE]
> We recommend using project-scoped MCP configuration files (for example, `.mcp.json` inside each repository) instead of global user-wide configuration such as `~/.claude.json`.
>
> This helps ensure each repository is automatically associated with the correct Supabase project, reduces configuration mistakes, and makes switching between projects easier.

Create a `.mcp.json` file at your project root:

```json
{
"mcpServers": {
"supabase-staging": {
"type": "stdio",
"command": "npx",
"args": [
"-y",
"@supabase/mcp-server-supabase@latest",
"--project-ref=<staging-ref>"
],
"env": {
"SUPABASE_ACCESS_TOKEN": "<your-pat>"
}
},
"supabase-secondary": {
"type": "stdio",
"command": "npx",
"args": [
"-y",
"@supabase/mcp-server-supabase@latest",
"--read-only",
"--project-ref=<secondary-ref>"
],
"env": {
"SUPABASE_ACCESS_TOKEN": "<your-pat>"
}
}
Comment on lines +107 to +131

@gregnr gregnr Jun 10, 2026

Copy link
Copy Markdown
Member

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Perhaps we can reduce this to a single entry called supabase for demonstration purposes? Also the stdio transport is no longer recommended in favour of the remote HTTP transport (https://mcp.supabase.com/mcp). Can we please change the config accordingly?

}
}
```

A few things worth knowing:

* **One PAT covers all projects** — Personal Access Tokens are org-scoped, so the same token works for every project in your organization.
* **`--project-ref` locks the server at startup** — each process only ever talks to one project. In clients like Claude Code, tools get namespaced automatically: `mcp__supabase-staging__*` vs `mcp__supabase-secondary__*`, so you can tell the agent exactly which server to use.
* **Avoid connecting to production** — prefer development projects whenever possible. If production access is required, use project scoping and read-only mode.
* **Why not a single server?** — Project scope is resolved at startup. A single server switching projects mid-session may require re-authentication each time. Running separate server instances avoids that workflow entirely.

Generate a Personal Access Token at `supabase.com/dashboard/account/tokens` and use it as `SUPABASE_ACCESS_TOKEN` to avoid OAuth prompts altogether.
Comment on lines +136 to +143

@gregnr gregnr Jun 10, 2026

Copy link
Copy Markdown
Member

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Remote MCP (http transport) no longer requires a PAT - the happy path is to simply use OAuth to authorize. Perhaps we can omit most or all of these points?


### Feature groups

You can enable or disable specific tool groups by passing the `features` query parameter to the MCP server. This allows you to customize which tools are available to the LLM. For example, to enable only the [database](#database) and [docs](#knowledge-base) tools, you would specify the server URL as:
Expand Down