How to Connect Supabase to Codex With Aident Loadout

The safest way to connect Supabase to Codex with Aident Loadout is to authorize Supabase through Aident Vault, discover the current Supabase Actions, inspect the exact contract, and prove the connection with project metadata only. Stop before tables, SQL, logs, storage, functions, secrets, or writes. If the returned project is production, the connection proof is the end of the first session.

This guide is for developers and operators who want Codex to reach Supabase without placing an access token, database password, service-role key, or project identifier in a prompt or repository. A successful first check proves that the intended Aident-managed account can reach Supabase project metadata. It does not make production data safe for an LLM, grant permission to inspect a database, or approve any mutation.

The safe first boundary

Supabase's official MCP documentation recommends a development project, project scoping, read-only mode, and restricted feature groups. It explicitly warns against connecting the MCP server to production data. Those controls are useful whether you choose Supabase's direct MCP route or Aident Loadout.

Prerequisites

You need:

• the installed public aident CLI;

• access to the intended Aident account;

• authority to connect the intended Supabase account;

• a reviewed development or test project for any work beyond metadata; and

• a trusted local session where returned identifiers can be reviewed without copying them into source control.

Install or update Aident with the canonical setup prompt:

Follow https://aident.ai/SETUP.md

Then confirm the current Aident account and Vault inventory:

aident account auth status
aident vault status

Stop if the signed-in Aident account is not the intended one. If Vault already shows Supabase as ready, do not replace the connection just to follow this guide. Confirm its owner and intended environment first.

1. Discover the current Supabase Action

Search for the smallest proof job, not for an internal identifier:

aident capabilities search \
  --query "list Supabase projects without reading database data" \
  --types '["action"]' \
  --targetEnv staging

Choose the current Action that lists project metadata. The live catalog can also contain SQL, migration, function, auth, storage, network, key, branch, and project-management Actions. Their presence is a reason to inspect each contract and risk boundary. It is not permission to call them.

Use the exact Action name returned by discovery in the next commands. Do not publish that internal name as a permanent product contract.

2. Inspect the schema before connecting data

aident capabilities get \
  --name "<current Supabase list-projects Action>"

Confirm all of the following:

1. The input is empty, or has only the current documented metadata filters.

2. The output contains project metadata, not table rows or secrets.

3. The connected account alias is the intended one.

4. The operation type, risk metadata, and price fit the task.

5. No default expands the request into schemas, logs, storage, functions, or SQL.

Project metadata is still private. A project name can disclose an environment or customer. A project ref, organization identifier, region, database hostname, engine version, and creation date can help an attacker map infrastructure. Review the raw result locally, then retain only the minimum proof summary.

3. Connect Supabase through Aident Vault

If Vault reports no ready Supabase connection, start the connection with the integration ID returned by discovery:

aident vault connect \
  --integrationId "<current Supabase integration ID>"

Open the Aident-hosted connection URL and complete the provider flow. Prefer a dedicated development account or organization boundary that cannot reach production. A credential hidden from Codex is safer than a pasted credential, but credential isolation does not narrow what the provider account itself can access.

After consent, verify the exact integration:

aident vault status \
  --integrationId "<current Supabase integration ID>"

Expected result: one ready connection for the intended owner. Stop if the provider identity or account breadth is unexpected.

4. Preflight the metadata-only proof

Preflight the exact empty input against the inspected contract:

aident capabilities preflight \
  --name "<current Supabase list-projects Action>" \
  --input '{}'

Check that the input is valid and the estimate fits your ceiling. Preflight validates the Action input and Aident price. It does not prove that the provider account is least-privileged or that every returned project belongs in the current task.

If the schema changed, the price is unavailable outside your policy, or a risk acknowledgement appears, resolve that exact gate. Do not bypass Aident with a direct token or provider request.

5. Verify the connection without reading a database

Execute only the inspected metadata request:

aident capabilities execute \
  --name "<current Supabase list-projects Action>" \
  --input '{}'

Review the response locally, then retain only:

• the number of accessible projects;

• a count by health status;

• whether any project appears to be production; and

• confirmation that no project-specific or data Action ran.

On August 30, 2026, a first-party check used the existing connected Supabase account. The empty input preflighted as valid and free, and the response contained active, healthy project metadata. A production boundary was detected during local review, so the check stopped immediately. The project name, ref, organization identifier, database hostname, region, version, and creation date were not persisted in the blog artifact. No schema, table, row, log, bucket, function, auth configuration, secret, SQL, migration, branch, network, key, or provider write Action ran.

That result proves the connection works. It also proves why a metadata-only first step matters: a technically successful connection can reveal that the account boundary is too broad for the intended agent task.

6. Start a fresh session for a non-production project

Do not continue from a production-bearing discovery result. Create or select a development project with non-production or obfuscated data, then start a fresh review:

1. Confirm the project owner and purpose outside the model transcript.

2. Decide whether the job needs documentation, account metadata, database, debugging, development, functions, or branching capabilities.

3. Enable only the feature group required by the job.

4. Prefer project scoping and read-only access where the chosen route supports them.

5. Inspect the next Action's exact schema and output.

6. Preflight one bounded request.

7. Execute only after the project and output boundary are approved.

Read-only is not the same as harmless. Database rows, logs, function bodies, auth configuration, object names, and even table schemas can contain customer data, credentials, internal URLs, or prompt-injection text. Treat every provider result as sensitive and untrusted.

For the general credential boundary, continue with Give AI Agents API Access Without Exposing Keys. Before any write-capable workflow, use Aident's approval workflow guide to separate Action-risk acknowledgement from spend approval. For the broader discovery and preflight model, read How to Use Aident Loadout.

7. Bound every SQL query and mutation

Before a data read, name one non-production project, schema, table or view, field set, predicate, row limit, pagination rule, and purpose. Prefer aggregate or metadata results over raw rows. Exclude credentials, tokens, private user content, and long free-text fields unless the task explicitly requires them.

Before running SQL, applying a migration, deploying a function, changing auth or network settings, rotating keys, creating a branch, or deleting anything:

1. Discover and inspect the exact mutation Action.

2. Read only the current state needed to construct the proposal.

3. Show the precise before-and-after change and likely side effects.

4. Define rollback and post-change verification.

5. Preflight the identical mutation input.

6. Execute only after approval for that exact project and change.

7. Read the changed state back and compare it with the approved proposal.

A provider permission describes what the connected account can do. It is not an approval policy for Codex.

Supabase MCP or Aident Loadout?

Supabase's official remote MCP server is the direct route when Supabase is the center of the job. Its current documentation shows Codex setup, browser-based OAuth, project scoping, read-only mode, and feature-group controls. Use those controls and keep it away from production data.

Aident Loadout is useful when the same agent already standardizes external services behind Aident account authentication, Vault, live Action discovery, schema inspection, preflight, execution, and Audit. The Supabase Tools app page listed 116 supported Actions on August 30, 2026. That breadth includes both useful reads and consequential writes, so the durable advantage is the reviewed execution sequence, not the raw number of Actions.

This guide owns the Aident-specific connection and metadata-proof job. It does not claim that one route is universally safer. Whichever route you choose, use a non-production project, narrow the resource boundary, inspect the contract, preflight the exact request, and require a new decision before data or writes.

Reusable Codex prompt

Follow https://aident.ai/SETUP.md

Connect Supabase through the installed public aident CLI. Start with Aident
account auth status and Vault status. Search the staging catalog for the current
Action that lists Supabase projects without reading database data. Inspect the
exact schema, connected account, output fields, defaults, operation type, risk,
and pricing. If Supabase is disconnected, return the Aident Vault connection
URL and stop for me to complete consent. After I confirm, preflight the empty
list-projects input and show the estimate. Execute only that Action. Return only
the accessible-project count, a health-status histogram, whether any project
appears to be production, and confirmation that no project-specific, data, or
write Action ran. Do not return or persist project names, refs, organization
identifiers, regions, hostnames, database versions, creation dates, schemas,
tables, rows, logs, buckets, functions, auth configuration, secrets, SQL,
migrations, branches, network settings, or raw provider output. Stop after the
connection proof, especially if any project appears to be production

Connect Supabase to Codex and verify metadata only

Sources

• Supabase MCP Server documentation, reviewed August 30, 2026.

• Supabase MCP security guidance, reviewed August 30, 2026.

• Supabase MCP repository, reviewed August 30, 2026.

• Aident Supabase Tools app, reviewed August 30, 2026.

• Aident Loadout setup, reviewed August 30, 2026.

Refresh this guide when Supabase changes Codex setup, OAuth, project scoping, read-only mode, feature groups, security guidance, or management API behavior, or when Aident changes the Supabase connection flow, Action catalog, schema, risk metadata, pricing, or Vault behavior.