Menu

Subscribe

How to connect the Supabase MCP server to Codex and Claude CLIs (step-by-step)

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

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

This setup allows either CLI 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 your CLI or giving the model unrestricted system access.

This article shows how to connect the Supabase MCP server to either Codex CLI or Claude 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.

Using Claude Code CLI

If you prefer Anthropic’s Claude Code CLI, you can connect the Supabase MCP server using the claude mcp add command with HTTP transport. The authentication and workflow are similar to Codex CLI.

  • Add the Supabase MCP server: run the following command to register the remote Supabase MCP server:
claude mcp add --transport http supabase https://mcp.supabase.com/mcp

Expected output:

Added HTTP MCP server supabase with URL: https://mcp.supabase.com/mcp to local config
File modified: ~/.claude.json

This registers a server named supabase that connects to Supabase’s hosted MCP endpoint and saves it to your Claude CLI config.

  • Authenticate with Supabase: launch Claude CLI and check the MCP status:
claude

Inside Claude CLI, run /mcp to see the registered servers:

 Manage MCP servers
 1 server

   Local MCPs (~/.claude.json)
 ❯ supabase · △ needs authentication

The △ needs authentication indicator means the server is registered but not yet authenticated. The first time you attempt to use a Supabase MCP tool (e.g., ask Claude to “list my projects”), the CLI will prompt you to complete browser-based OAuth. Complete the flow, and the CLI will cache your credentials.

  • Verify the connection: after authentication, run /mcp again to confirm the server is ready:
 Manage MCP servers
 1 server

   Local MCPs (~/.claude.json)
 ✓ supabase · ready

You should see ✓ ready (or similar) and the available tools (for example, execute_sql, list_projects, get_logs, etc.).

Troubleshooting notes for Claude CLI:

  • If the CLI reports authentication errors when using a Supabase tool, you may need to re-authenticate. Use claude mcp remove supabase to remove the server, then re-run claude mcp add --transport http supabase https://mcp.supabase.com/mcp and log in again.
  • To view or modify a registered MCP server’s details, use claude mcp get supabase.
  • For more advanced MCP configuration (environment variables, custom headers, etc.), consult claude mcp add --help.

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.