How to connect a Supabase MCP with Codex (4 steps)

When you hand Codex a task to build a Supabase migration or an API endpoint backed by your database, you'd describe your schema in the prompt.

That description rarely matches the real database. Column types, RLS policies, and the actual shape of an auth user record are details a summary skips.

So Codex writes a migration that conflicts with the real schema, an endpoint that ignores an existing RLS policy, or auth code built on an assumed user object.

To give Codex direct access to Supabase as it works through your coding tasks, we'll show you how to connect Supabase with Merge Agent Handler's Supabase MCP server.

How it works

Merge Agent Handler connects Codex to the Supabase API through the Merge CLI. You install the CLI, authenticate once, and run a single setup command from your project root.

That command writes a Merge CLI section to your project's AGENTS.md file, which tells Codex when to call merge search-tools and merge execute-tool to reach Supabase.

Merge also manages your Supabase credentials on your behalf, so no project key lives in your repo or gets passed around the team.

Related: How to use the Supabase MCP in Claude Code

Prerequisites

Before getting started, you'll need the following:

• A Merge Agent Handler account
• Codex access (available via the OpenAI platform)
• pipx installed (run pipx --version to confirm, or install via pip install pipx)
• A Supabase account with access to the project you want to connect

If you want to connect Merge Agent Handler's Supabase MCP with internal or customer-facing agentic products, you can follow the steps in our docs.

1. Install the Merge CLI

Install the Merge CLI with pipx: pipx install merge-api

Verify the install: merge --version

2. Log in to Merge

Run the following to authenticate the CLI with your Merge Agent Handler account: merge login

This links the CLI to your Merge account and stores your session credentials locally.

3. Add Agent Handler to Codex

From the root of the project where you want Codex to reach Supabase, run:

merge setup agents-md

This writes a Merge CLI section to your project's AGENTS.md file so Codex knows to use the CLI when a task needs Supabase data.

The command is idempotent, so it's safe to re-run if you need to reset the configuration.

Related: A guide to integrating the Supabase MCP with Cursor

4. Authenticate Supabase

Create a Codex task that needs live Supabase data. For example: "Read the schema and RLS policies for my orders table, then scaffold a migration that adds a status column and an endpoint that respects the existing policies."

The first time Codex invokes a Supabase tool, a Magic Link will appear to complete connector authentication.

Once authenticated, Codex can reach your Supabase project through Merge for every later task in this project.

{{this-blog-only-cta}}

Supabase MCP FAQ

In case you have more questions on setting up and using the Supabase MCP with Codex, we've addressed several more commonly-asked questions below.

What can you do once the Supabase MCP is connected to Codex?

With Supabase connected, Codex can:

• Read the real table schema before scaffolding a migration: pull column types and constraints so the migration it generates doesn't conflict with the existing schema

• Pull RLS policies before generating an endpoint: fetch the real policies on a table so the endpoint it scaffolds respects existing access rules instead of assuming open access

• Read a real auth user record before generating auth integration code: fetch a user object so the code it writes handles Supabase's actual identities and metadata structure

• Pull storage bucket structure before generating upload or sync code: fetch real objects so the code it produces matches the real path and metadata format

• Read Edge Function logs before scaffolding a new function or fixing a bug: pull recent invocations and errors so the code it generates matches the real payload and failure modes

Why use Merge Agent Handler vs. a self-hosted Supabase MCP server?

You can build a self-hosted MCP server on Supabase's API. For one project and one use case, it's workable: grab a project key, pass it as a header, and start making calls.

It gets harder once tasks run across more than one project or more than one developer needs access. Each key carries broad access to that project, with no way to scope which operations a Codex task can call.

A self-hosted server also has no central audit log. Supabase projects hold real user data and auth records, and a task that can read or modify them leaves no record of what it touched.

Merge Agent Handler handles Supabase authentication centrally and exposes the same tools across every connected project through one connection. You can scope exactly which Supabase operations a Codex task can call, and block write access to sensitive tables entirely.

Every call is logged with identity, timestamp, and inputs. For an agent working against a live application database, scoped access plus full audit logging is the foundation you want in place first.

Why connect Supabase to Codex?

Supabase holds the table schemas, RLS policies, and auth records that application code has to match exactly.

Codex tasks that scaffold migrations, endpoints, or auth integrations need that ground truth to produce code that works against the real project.

The alternative is describing your schema in the prompt, and those descriptions are always incomplete. A missed constraint, an ignored RLS policy, or a wrong assumption about the auth user object is enough to make Codex generate code that breaks on the real database.

Connecting Supabase lets Codex read the actual structure when a task needs it.

Can I use Merge Agent Handler's Supabase MCP with my employees?

Yes, Agent Handler for Employees is built to help organizations provision, secure, and govern how employees connect AI tools like Codex to operational tools like Supabase.

Common patterns include:

• Provisioning and access control via SCIM with identity providers like Okta and Microsoft Entra ID, so IT can manage which tables and projects an employee's agent can reach by role or team

• DLP and policy enforcement on tool calls, so admins can restrict which operations an employee's AI can run against production tables before the call is made

• User-level audit logging so security and IT teams can review which Supabase resources were queried or changed, by which employee identity, and when

Taken together, employees can use the Supabase MCP to scaffold migrations against real schemas, generate endpoints that respect actual RLS policies, build auth integrations grounded in real user records, and more. All the while, IT keeps centralized control over which projects each agent can reach.