Supabase MCP Setup: Project-Scoped and Read-Only First
Use Supabase’s hosted MCP endpoint with OAuth, add your project’s projectref, and set readonly=true. Start with only the feature groups needed to inspect the database, then verify schema, documentation, and advisor reads before enabling SQL, migrations, Edge Functions, branching, storage, or account-level actions.
Use Supabase’s hosted MCP endpoint with OAuth, add your project’s project_ref, and set read_only=true. Start with only the feature groups needed to inspect the database, then verify schema, documentation, and advisor reads before enabling SQL, migrations, Edge Functions, branching, storage, or account-level actions.
Table of contents
- What Supabase MCP can reach
- Build a project-scoped read-only URL
- Connect and complete OAuth
- Verify schema, docs, and advisor reads
- Add write-capable feature groups deliberately
- Fix OAuth, project, local CLI, and permission failures
- FAQ
What Supabase MCP can reach
Supabase MCP can manage a Supabase project end to end, including Postgres tables, SQL, migrations, Edge Functions, development branches, logs, security and performance advisors, and generated TypeScript types. Start with read-only database inspection and expand access only when the task requires it. See the MCPtrove Supabase MCP Server directory entry for the connection details.
The official hosted server uses the remote endpoint https://mcp.supabase.com/mcp over HTTP with OAuth authentication. Its scope can include project data and configuration, so the connection should be treated as an administrative boundary rather than a simple documentation lookup. Supabase’s MCP guide describes the supported connection model and capabilities.
A practical starting posture is:
| Need | Initial access |
|---|---|
| Inspect tables and relationships | Project-scoped, read_only=true, database features only |
| Review security or performance findings | Add the relevant advisor reads |
| Generate TypeScript types | Keep read-only mode; add only the required database capability |
| Run SQL or apply migrations | Enable only for an explicit, reviewed task |
| Manage branches, storage, or account settings | Add the corresponding feature group only when necessary |
The MCP architecture separates the client from the server through a protocol connection, while the server performs the requested operations against the project. Read the MCP architecture overview when you need to map the client, remote server, authorization, and project boundary.
Build a project-scoped read-only URL
Build the URL by adding your Supabase project reference and read_only=true to the hosted endpoint:
https://mcp.supabase.com/mcp?project_ref=<your-project-ref>&read_only=true
Replace <your-project-ref> with the project_ref ID from your Supabase project URL. Keep the URL limited to the project you intend to inspect, and enable only the smallest useful feature groups in the MCP client.
For an initial connection, the important controls are:
- Use the hosted endpoint at
https://mcp.supabase.com/mcp. - Add
project_ref=<id>for project scope. - Add
read_only=trueso the agent can issue read transactions only. - Select only the database or advisor capabilities needed for the first task.
- Save the configuration and begin the OAuth flow from the client.
The query parameters define the server’s security boundary, but they do not replace review of OAuth permissions. The MCP security guidance recommends limiting access, reviewing authorization scopes, and avoiding unnecessary capabilities. See MCP security best practices.
Connect and complete OAuth
Add the hosted URL to an MCP-capable client, then start its OAuth login flow. Complete the browser authorization in the Supabase account and organization context before returning to the client.
The remote server uses an OAuth 2.1 browser flow, so you do not need to paste a Supabase personal access token into the client configuration. Clients such as Cursor, Claude Code, VS Code, and Windsurf can use the remote connection model when they support MCP.
A typical connection sequence is:
- Open the MCP settings in your client.
- Add the remote URL with
project_refandread_only=true. - Select the smallest available feature set.
- Start authentication.
- Complete the browser-based Supabase OAuth flow.
- Return to the client and confirm that the MCP connection is active.
- Request a read-only schema or advisor check.
OAuth authorizes the MCP client against the broader organization context, so inspect the requested scopes before approving. The hosted connection avoids manual token handling, but it does not remove the need to verify which project and capabilities the client can reach. Supabase’s remote MCP announcement explains the hosted OAuth approach.
Verify schema, docs, and advisor reads
Verify the connection by reading the intended project schema, checking the exposed MCP documentation and capabilities, and requesting security or performance advisor results while read-only mode remains active.
Use a short verification sequence:
- Ask the client to identify or summarize the connected project.
- Request a schema read covering tables, columns, and relationships.
- Compare the client’s exposed capabilities with the official Supabase MCP guide.
- Request the relevant security and performance advisor reads.
- If needed, request generated TypeScript types without enabling writes.
- Confirm that SQL execution, migrations, function deployment, and account-level actions are not available or cannot modify state.
For schema-focused work, the MCPtrove database schema capability is a useful practical reference. A successful OAuth handshake is not enough: the project identity, read boundary, and available feature groups should all match the intended task.
If the response is incomplete, compare the client’s tool list with the selected feature groups and reconnect after correcting the URL. Keep the first test narrow so a missing capability has a clear cause.
Add write-capable feature groups deliberately
Keep read_only=true and the smallest feature set until schema and advisor reads are confirmed. Add write-capable groups only for a specific task, with a clear reason to permit SQL, migrations, functions, branching, storage, or account actions.
A deliberate expansion should follow this order:
- State the exact operation the agent must perform.
- Identify the feature group that covers that operation.
- Enable only that group in the client.
- Decide whether read-only mode must be changed.
- Reconnect and verify the new boundary.
- Remove the extra capability when the task is complete.
Do not treat all project capabilities as interchangeable. Database inspection does not require the same access as migration application, Edge Function deployment, branch management, or account administration.
The OAuth flow still authorizes the client in the organization context, and the server can reach project data and configuration. Use the MCPtrove guide to what MCP security controls actually matter alongside the official security best practices when reviewing a broader configuration.
Fix OAuth, project, local CLI, and permission failures
Fix failures by separating authentication, project scope, local prerequisites, and permissions instead of changing several controls at once. Check the URL, OAuth result, selected feature groups, and client logs in that order.
| Symptom | Likely cause | Corrective check |
|---|---|---|
| OAuth does not complete | Browser authorization or requested scopes were denied | Restart the OAuth flow and review the scopes requested for the organization |
| The client reaches the wrong project | Incorrect project_ref | Copy the project ref from the intended Supabase project URL and reconnect |
| The remote client asks for a token | The client is using the wrong connection mode | Use the hosted URL and OAuth flow; remote mode does not require a manual token |
| Local MCP does not start | Node.js, the Supabase CLI, or local configuration is missing | Confirm the local/self-hosted prerequisites before using http://localhost:54321/mcp |
| The agent can write unexpectedly | Read-only mode or feature restrictions are absent | Restore read_only=true, reduce feature groups, and reconnect |
| A needed capability is missing | Its feature group is not enabled | Compare the client’s exposed tools with the official guide and add only the required group |
For local or self-hosted stdio mode, the supplied prerequisites are Node.js, the Supabase CLI, and a Supabase personal access token created under Account > Access Tokens. The hosted remote mode has no installation step. The Supabase MCP repository is the appropriate source for implementation details.
When a client reports an opaque MCP error, capture the client-side message, connection mode, endpoint, project scope, and enabled feature groups. Then consult the MCP debugging guide before changing permissions or switching transport.