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

When you hand Codex a task to build a Ramp reconciliation tool or a spend dashboard, you describe the transaction and GL structure in the prompt.

That description rarely matches the real account. Real merchant and accounting field formats, the actual department and GL code structure, and how reimbursement line items are shaped are details a summary skips.

So Codex writes a sync against an assumed transaction shape, accounting logic that references GL codes that don't exist, or reimbursement handling that misses how line items are structured.

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

How it works

Merge Agent Handler connects Codex to the Ramp 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 Ramp.

Merge also manages Ramp's OAuth client credentials and token refresh on your behalf, so no client secret lives in your repo.

Related: How to use the Ramp 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 Ramp account with admin access to authorize an API client

If you want to connect Merge Agent Handler's Ramp 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 Ramp, 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 Ramp 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.

4. Authenticate Ramp

Create a Codex task that needs live Ramp data, for example: "Read a real transaction's merchant and accounting field structure, then scaffold a GL sync that maps Ramp transactions into our internal accounting schema."

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

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

{{this-blog-only-cta}}

Ramp MCP FAQ

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

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

With Ramp connected, Codex can:

• Read the real transaction schema before scaffolding a GL sync: pull a real transaction so the sync it generates maps merchant, memo, and accounting fields correctly instead of an assumed shape

• Pull department and GL code structure before generating accounting-sync logic: fetch the real org structure so the code it writes assigns transactions to categories that actually exist

• Read reimbursement line-item structure before generating expense automation: fetch a real reimbursement so the code it produces handles line items and receipts the way Ramp actually structures them

• Pull card and spend-limit data before generating budget-alert logic: fetch real limits so the thresholds it writes match the account's actual configured limits

• Read a webhook payload before generating an event handler: fetch a real event so the handler it writes matches the object shape Ramp actually sends

Why use Merge Agent Handler vs. building directly on the Ramp API?

You can build directly against Ramp's API. For one account and one use case, it's workable: register an OAuth client, request the scopes you need, and start making calls.

It gets harder once tasks run across more than one Ramp account or need scoped access. Ramp's OAuth scopes are coarse relative to how teams want to divide access, so a client with transaction read access often also reaches adjacent data, with no way to limit a Codex task to just what it needs.

Ramp also holds real spend and cardholder data, and a direct integration has no field-level control or audit log to keep that data out of a task's context.

Merge Agent Handler manages Ramp's OAuth credentials centrally and lets you scope exactly which operations a Codex task can call. Every call is logged with identity, timestamp, and inputs.

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

Why connect Ramp to Codex?

Ramp holds the transaction schema, GL and department structure, and reimbursement format that spend-automation code has to match exactly.

Codex tasks that build reconciliation tools, syncs, or reporting need that ground truth to produce code that works against the real account.

The alternative is describing the account's structure in the prompt, and those descriptions are always incomplete. An assumed transaction field, a GL code that doesn't exist, or a misunderstood reimbursement line-item shape is enough to make Codex generate code that breaks on real data.

Connecting Ramp lets Codex read the actual structure when a task needs it. The real transaction before a sync, the real GL and department structure before accounting logic, the real reimbursement shape before expense automation: Codex works from the account itself, not a paraphrase of it.

Can I use Merge's Ramp MCP with my employees?

Yes, Merge for Workforce is built to help organizations provision, secure, and govern how employees connect AI tools like Codex to systems like Ramp.

Common patterns include:

• Provisioning and access control via SCIM with identity providers like Okta and Microsoft Entra ID, so IT can manage which employees can query transaction and spend data by role or team

• DLP and policy enforcement on tool calls, so admins can block queries that would return card numbers or other cardholders' spend data before results reach a Codex task's context

• User-level audit logging so security and finance teams can review which transactions, reimbursements, or bills were queried or modified, by which employee identity, and when

Taken together, employees can use the Ramp MCP to scaffold syncs against real transaction data, generate accounting logic grounded in actual GL structure, build automations tied to real reimbursement formats, and more, while IT keeps centralized control over which spend data each agent can reach.