Supabase MCP setup: project scope and read-only access
Set up Supabase MCP: distinguish project_ref, read_only and feature groups, choose test data and verify the actual database access.
Still choosing an access path? The database planner builds a test plan; the database comparison explains file, role and project boundaries.
Before a first Supabase MCP test, establish which project may be accessed and which data you intend to read. Choose a development project with a small test table rather than an open-ended request covering every database. This guide separates three settings with different purposes: project selection, read-only mode and available feature groups. A subsequent read is still needed to establish whether the intended table is actually reachable.
Scope the hosted endpoint
Supabase documents https://mcp.supabase.com/mcp as its hosted endpoint. The project_ref parameter scopes access to one project, read_only=true runs database queries as a read-only Postgres user, and features selects tool groups. These settings complement each other. Restricting the available tool groups is not the same as selecting a single project.
A preparation example is https://mcp.supabase.com/mcp?project_ref=YOUR_PROJECT_REFERENCE&read_only=true&features=database. Replace the placeholder with your test project reference and put the URL in the appropriate client field. Use the client overview for the format, then inspect the configuration actually displayed. The normal hosted setup includes an authorization flow; a database password does not belong in this URL.
Check the three boundaries independently
| Setting | Purpose | Your check |
|---|---|---|
| project_ref | One specific project | Compare the reference with the dashboard |
| read_only=true | Read-only database queries | Inspect configuration and intended operation |
| features=database | Database tool group | Inspect the tools after connecting |
Record the project address and expected table name before testing. A successful query against a different project would be technically successful but still answer the wrong question. Check a prepared test row as well as the table name. Choose a few columns and a small result set. A complete export adds little to this check and makes independent verification unnecessarily difficult. Keep the expected values separate from the result returned by the client.
Start with a small table
Choose a non-sensitive test resource in the intended development project. Record the schema, table and expected values.
Configure the scoped server URL and complete authorization. Inspect the project assignment and tool list.
Check the table structure first, then read only the prepared values. Compare the result directly with the dashboard.
Record scope and result. After changing projects or feature groups, repeat this same test before extending the workflow.
Separate connection failures from database questions
If authorization fails, start with MCP troubleshooting. If tables are missing, verify the project and schema before recreating the connection. The PostgreSQL guide covers planning a bounded database test. The Supabase registry search lists further entries; inspect their sources before transferring official service settings to another implementation. A similar name does not establish identical behavior.
- Does the project reference enforce read-only access?
- No. Project selection and read-only mode are separate settings. Check both before the test.
- Does read_only establish limits for every data flow?
- No. The documented parameter concerns database queries. Also review the feature groups and the specific operation.
- Does a table name establish the correct dataset?
- Not alone. Compare the project reference and a known test row, because names can repeat across projects.
- Should I immediately enable writes after a failure?
- No. First check project, schema, authorization and the failed operation. A read test needs no precautionary write attempt.
Provider documentation accessed on 1 October 2026. Test procedures are editorial suggestions.
- Supabase MCP Server
Show retrieval command
curl -s https://supabase.com/docs/guides/ai-tools/mcp