← All connection guides

How to connect Codex to Supabase

Connect Codex to Supabase with the official plugin or a project-scoped, read-only MCP setup and verify database access.

Free guide · Updated

Based on official documentation · Checked

Ask your agent

Copy the prompt and paste it into your assistant.

Quick answer

Install the official Supabase plugin from Codex’s plugin directory and authorize your Supabase account. The plugin bundles the remote MCP server with Supabase and Postgres skills. If you want an explicitly project-scoped, read-only connection, use the manual CLI setup below instead.

Before you start

Choose a development project and an account authorized to access it. Keep the project reference handy for manual setup. MCP connects Codex to the Supabase platform; installing a Supabase SDK in your app serves a different purpose.

Option A: Install the official plugin

In the Codex desktop app, open its plugin directory and install Supabase. For Codex CLI, start the terminal client and open the plugin manager:

codex
/plugins

Choose Supabase

Search for Supabase and choose Install plugin. Start a fresh session if the tools do not appear. Complete the Supabase authorization flow when the client requests it, selecting the organization containing your project. Review the resulting access scope; plugin installation alone does not restrict the connection to read-only mode.

Option B: Use a scoped read-only CLI connection

Replace YOUR_PROJECT_REF with your development project’s reference. Keep the URL quoted so the shell preserves its query parameters:

codex mcp add supabase --url "https://mcp.supabase.com/mcp?project_ref=YOUR_PROJECT_REF&read_only=true"
codex mcp login supabase

Avoid duplicate connections

Use one setup path. If you switch between the plugin and a manual server, remove the redundant entry after confirming which connection you intend to keep. Loading the same service twice can make tool selection confusing.

Practice

Verify the intended project

  1. Ask Codex to use Supabase MCP to list tables in your selected project and describe the columns of one named table. Request no mutations. Compare the result with the Supabase dashboard.

Output: The table and column details match the intended project; Codex uses Supabase tools rather than guessing from local files.

Troubleshooting and removal

Wrong project: check project_ref or the account and organization authorized by the plugin. Missing tools: inspect the plugin manager or /mcp and restart the session. Read-only mode limits database queries but does not remove every risk of connecting an assistant. Disconnect through the plugin manager or remove the manual MCP entry, then revoke the applicable authorization if it is no longer needed.

Sources

Read the primary material