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

When you hand Codex a task to build an Airtable sync or an integration endpoint, you'd describe your base's structure in the prompt.

That description rarely matches the real base; the source of truth lives in Airtable, not the few lines you wrote into the task.

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

How it works

Merge Agent Handler connects Codex to Airtable's 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 Airtable.

Merge also manages your Airtable OAuth credentials and token refresh on your behalf, so no token state lives in your repo or local environment.

Related: How to use the Airtable 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)
• An Airtable account with access to the bases you want to connect

If you want to connect Merge Agent Handler's Airtable 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 Airtable, 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 Airtable data. The command is idempotent, safe to re-run if you need to reset the configuration.

Commit the updated AGENTS.md so the configuration travels with the repo.

Related: A guide to integrating the Airtable MCP with Cursor

4. Authenticate Airtable

Create a Codex task that needs live Airtable data, for example: "Read the field schema and a real record from my launches table, then scaffold a sync that maps Airtable fields, including linked records and attachments, into our internal schema."

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

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

{{this-blog-only-cta}}

Airtable MCP FAQ

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

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

With Airtable connected, Codex can:

• Read the real field schema before generating type definitions: pull a table's field definitions, including each select field's actual option values, so the types and enums it generates match the real base

• Pull a real record before generating a parser: fetch an actual record so the parsing code it writes handles real linked record arrays and attachment objects instead of a guessed shape

• Read a base's structure before scaffolding an integration endpoint: pull the tables and views in a base so the endpoint code it generates matches the real layout

• Pull select and multi-select option lists before generating validation: fetch the actual option values for a field so the validation logic it produces checks against real choices, not assumed ones

• Read linked record structure before generating cross-table logic: fetch a record with linked fields so the traversal or join code it writes follows the real references between tables

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

You can build a self-hosted MCP server on Airtable's API. For one base and one use case, it's workable: generate a personal access token, pass it as a header, and start making calls.

It gets harder once tasks run across more than one base or more than one workspace.

Each token carries that workspace's full access, with no way to scope which operations a Codex task can call, and a self-hosted server only ever solves Airtable.

Airtable also holds product specs, launch data, and sometimes customer records, and a self-hosted setup has no field-level control or audit log to keep sensitive data out of a task's context.

Merge Agent Handler handles Airtable authentication centrally and exposes the same tools across every connected base through one connection. You can scope exactly which Airtable operations a Codex task can call, and every call is logged with identity, timestamp, and inputs.

For an agent working with production Airtable data, scoped access plus full audit logging is the foundation you want in place first.

Why connect Airtable to Codex?

Airtable holds the field schemas, select option values, and linked record structures that integration code has to match exactly.

Codex tasks that build syncs, endpoints, or data pipelines need that ground truth to produce code that works against the real base.

The alternative is describing your base's structure in the prompt, and those descriptions are always incomplete. An assumed field shape, a label used instead of a real select option, or a missed attachment structure is enough to make Codex generate code that breaks on real data.

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

Can I use Merge Agent Handler's Airtable 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 systems like Airtable.

Common patterns include:

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

• DLP and policy enforcement on tool calls, so admins can block queries that would return sensitive record data before results reach a Codex task's context

• User-level audit logging so security and IT teams can review which records were accessed, created, or updated, by which employee identity, and when

Taken together, employees can use the Airtable MCP to scaffold syncs against real field schemas, generate mappings grounded in actual select option values, and build integrations tied to real linked record structure. All the while, IT keeps centralized control over which bases each agent can reach.