Connect Codex to Supabase

What you get

Supabase hosts the server itself at https://mcp.supabase.com/mcp over streamable HTTP, so there’s nothing local to install. Supabase’s docs publish a Codex TOML block right alongside the Cursor and Claude Desktop ones, which almost no vendor bothers to do. If you’re running the stack locally with supabase start, the same server answers at http://localhost:54321/mcp.

The tools come in eight groups you switch on with a features query parameter. The supabase-community/supabase-mcp README names the slugs: account, database, debugging, development, docs, functions, storage, and branching. Every group except storage is on by default. Watch the two slugs that don’t match their headings in the docs: Edge Functions is functions, and Account management is account.

Here’s what Supabase’s docs list under each group:

Group	Tools
database	list_tables, list_extensions, list_migrations, apply_migration, execute_sql
debugging	get_logs, get_advisors
development	get_project_url, get_publishable_keys, generate_typescript_types
functions	list_edge_functions, get_edge_function, deploy_edge_function
account	list_projects, get_project, create_project, pause_project, restore_project, list_organizations, get_organization, get_cost, confirm_cost
docs	search_docs
branching	create_branch, list_branches, merge_branch, rebase_branch, reset_branch, delete_branch
storage	list_storage_buckets, get_storage_config, update_storage_config

Branching carries a note in Supabase’s docs: “Requires a paid plan.”

Setup

1. There is no npx step. Supabase’s docs show two connection points, the hosted URL and the local one. The npx -y @supabase/mcp-server-supabase command that older writeups and most models still hand out does not appear on that page. The package is still published and isn’t deprecated, but its README now covers using it as a library to populate tool schemas, so treat it as the wrong answer to “how do I connect Codex.”

2. Write the block by hand. codex mcp add takes a stdio command only. The documented syntax is codex mcp add <name> --env KEY=VALUE -- <command> <args>, and the Codex MCP docs tell you to edit the config file directly for streamable HTTP servers. There’s no --url flag. Put this in ~/.codex/config.toml:

[mcp_servers.supabase]
url = "https://mcp.supabase.com/mcp?project_ref=<your-project-ref>&read_only=true&features=database,docs"
default_tools_approval_mode = "writes"

Your project ref is in the dashboard URL. Multiple features go in one comma-separated string. Everything after url = is a single literal string to Codex, so it’s not a TOML array and not repeated params.

3. Log in.

codex mcp login supabase

Supabase defaults to dynamic client registration, so there’s no OAuth app to create first. Its docs note that a personal access token “was previously required, but is no longer needed.”

4. CI and headless boxes use a bearer token. Supabase still supports a personal access token for CI, and Codex reads it out of the environment:

[mcp_servers.supabase]
url = "https://mcp.supabase.com/mcp?project_ref=<your-project-ref>&read_only=true"
bearer_token_env_var = "SUPABASE_ACCESS_TOKEN"

Keep the token in the CI secret store. Don’t paste the value into config.toml, since that’s the file people commit.

5. Confirm it initialized.

codex mcp list

Testing against supabase start instead? Swap the url for http://localhost:54321/mcp and drop project_ref, since there’s only one project to talk to.

Gotchas

Supabase is blunt about the big one, so I’ll quote it straight: “Remember to never connect the MCP server to production data. Supabase MCP is only designed for development and testing purposes.”

The two URL params are how you hold yourself to that. Supabase’s config page says project_ref “disables account tools,” which is literal: scope to one project and the whole account group drops out of what Codex can call. read_only=true is documented to “execute all queries as a read-only Postgres user.” Note the exact wording there. Supabase documents it as a permissions change at the Postgres level, and does not say it hides or removes any tools, so don’t treat it as a tool allow-list. If you want a specific tool gone, name it in disabled_tools or cut its group out of features. default_tools_approval_mode = "writes" sits on top and makes anything classified as a write clear a manual approval first.

Hand-editing TOML is where #6020 bites. It reports every configured server failing the handshake at once on 0.53.0, still open. One malformed entry can take the whole set down, so if Supabase breaks your other servers, bisect by disabling blocks one at a time.

A streamable HTTP server can connect and still hand you nothing. #4707 covered exactly that, with correctly configured HTTP servers showing “Tools: (none)”. It’s closed, fixed via PR #5298, so if you hit it today the answer is to update Codex before you start rewriting your features string.

Windows paths aren’t a factor here the way they are for stdio servers, since there’s no local binary to point at. The formatting that still bites is the query string: a stray space in features=database, docs breaks the parameter, because a URL won’t tolerate the whitespace a TOML array would.

Related

• Connect an MCP server: the stdio vs. remote shape, and the JSON-to-TOML translation
• mcp_servers.<id>.url: the remote endpoint and its auth keys
• mcp_servers.<id>.env: where a secret like SUPABASE_ACCESS_TOKEN belongs instead of inline
• mcp_servers.<id>.startup_timeout_sec: raise it if the initial connection stalls
• “handshaking with MCP server failed”: the connection dies at startup
• Install Codex CLI