Menu

Subscribe

How to connect the Supabase MCP server to OpenAI Codex CLI (step-by-step)

on supabase, mcp, openai, cli, codex, devtools, ai-agents

You can manage Supabase projects, branches, migrations, and logs directly from OpenAI Codex CLI by enabling Supabase’s hosted Model Context Protocol (MCP) server.

This setup allows Codex to interact with Supabase through structured, permissioned tools instead of ad-hoc shell commands. In practice, this means you can inspect projects, run migrations, execute SQL, and fetch logs without leaving Codex or Claude CLI.

This article shows how to connect the Supabase MCP server to Codex CLI and verify that it works.

What MCP enables in practice

The Model Context Protocol (MCP) allows tools like Codex CLI to call external systems through explicit, well-defined interfaces.

Instead of giving an AI unrestricted access to your shell, MCP exposes a fixed set of tools such as:

  • list_projects
  • apply_migration
  • execute_sql
  • get_logs
  • create_branch

Supabase provides a hosted MCP server, which means:

  • no local processes to run,
  • OAuth-based authentication,
  • a stable HTTPS endpoint.

If you’re new to MCP, OpenAI’s overview of the protocol and ecosystem is a good starting point:
https://openai.com/index/model-context-protocol/

Step 1: Enable the remote MCP client in Codex CLI

Codex CLI supports local MCP servers by default. To connect to Supabase’s hosted MCP server, you must enable the experimental remote MCP client.

Edit (or create):

~/.codex/config.toml

Add the following configuration:

experimental_use_rmcp_client = true

[mcp_servers.supabase]
url = "https://mcp.supabase.com/mcp"

Why this flag is required

Supabase’s MCP server uses an HTTP-based transport instead of a locally spawned process.

At the time of writing, Codex CLI ships this functionality behind an experimental flag while remote transports, authentication flows, and MCP conventions continue to stabilize. Expect occasional breaking changes.

Step 2: Start Codex CLI

Launch Codex CLI as usual:

codex

On first startup, Codex detects the Supabase MCP server but reports that authentication is missing:

⚠ The supabase MCP server is not logged in.
Run `codex mcp login supabase`.

This is expected.

Step 3: Authenticate with Supabase (OAuth)

Run the suggested command:

codex mcp login supabase

This opens a browser window where you:

  • log into Supabase,
  • grant Codex access,
  • complete the OAuth flow.

After the flow completes, restart Codex CLI to ensure the credentials are loaded.

Step 4: Verify the MCP connection

Inside Codex CLI, run:

/mcp

You should see output similar to:

🔌  MCP Tools

  • supabase
    • Status: enabled
    • Auth: OAuth
    • URL: https://mcp.supabase.com/mcp
    • Tools: apply_migration, confirm_cost, create_branch, create_project, delete_branch, deploy_edge_function, execute_sql,
generate_typescript_types, get_advisors, get_cost, get_edge_function, get_logs, get_organization, get_project, get_project_url,
get_publishable_keys, list_branches, list_edge_functions, list_extensions, list_migrations, list_organizations, list_projects,
list_tables, merge_branch, pause_project, rebase_branch, reset_branch, restore_project, search_docs
    • Resources: (none)
    • Resource templates: (none)

If you see this, the connection is working.

What you can do now

With the Supabase MCP server connected, Codex CLI can:

  • inspect organizations and projects,
  • generate and apply database migrations,
  • execute SQL through scoped MCP tools,
  • fetch logs and project metadata,
  • manage branches and Edge Functions.

All from the terminal, without giving the model unrestricted system access.

If you see an auth error on startup

Occasionally Codex fails to refresh the Supabase OAuth token during startup. If you see a message like this when launching Codex, re-authenticate:

⚠ MCP client for `supabase` failed to start: MCP startup failed: handshaking with MCP server failed: Send message error Transport
  [rmcp::transport::worker::WorkerTransport<rmcp::transport::streamable_http_client::StreamableHttpClientWorker<rmcp::transport::auth::AuthClient<reqwest::async_impl::client::Client
  >>>] error: Auth error: OAuth token refresh failed: Failed to parse server response, when send initialize request

⚠ MCP startup incomplete (failed: supabase)

To fix it, run codex mcp login supabase again and restart Codex CLI.

FAQ

How do I enable remote MCP support in Codex CLI?
Set experimental_use_rmcp_client = true in ~/.codex/config.toml, add the Supabase MCP server entry, and restart Codex.

How do I authenticate with Supabase MCP?
Run codex mcp login supabase, complete the browser-based OAuth flow, restart Codex, and verify the connection with /mcp.

Is this safe to use on production projects?
MCP tools are explicit and scoped, which is significantly safer than allowing arbitrary shell access. That said, always review migrations and destructive actions before approving them.

Final note

Supabase MCP combined with Codex CLI is a good example of how AI tooling fits into existing developer workflows: operating through clearly defined interfaces, with guardrails, inside the tools you already use.