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

When you hand Codex a task to build a BambooHR sync or an onboarding automation, you describe your BambooHR setup in the prompt.

That description rarely matches the real account. The field aliases, the custom fields, the time-off types, and the tables behind job and compensation history are details a summary skips.

So Codex writes a parser for an assumed employee shape, a mapping built on field labels instead of BambooHR's real aliases, or validation that misses the actual time-off types. The source of truth lives in BambooHR, not the few lines you wrote into the task.

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

How it works

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

Once connected, Merge stores and manages your BambooHR API key, so you never embed a company key in your repo or rotate it by hand.

Related: How to use the BambooHR 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 BambooHR account with API access enabled (Admin access required to generate an API key)

If you want to connect Merge Agent Handler's BambooHR 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 BambooHR, 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 BambooHR 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 BambooHR MCP with Cursor

4. Authenticate BambooHR

Create a Codex task that needs live BambooHR data, for example: "Read one employee record and the time-off types, then scaffold a sync that maps BambooHR fields to our internal schema and validates the time-off type IDs."

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

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

{{this-blog-only-cta}}

BambooHR MCP FAQ

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

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

With BambooHR connected, Codex can:

• Read the real field schema before scaffolding a sync: pull the list of standard and custom employee fields so the sync it generates uses BambooHR's actual field aliases instead of assumed names

• Pull a real employee record before generating a parser: fetch one record so the parsing code it writes handles BambooHR's real value formats and empty-field behavior rather than a guessed shape

• Read time-off types before generating absence code: fetch the time-off types and a real request so the handling it writes uses BambooHR's actual type IDs, statuses, and date formats

• Pull a table's rows before generating job-history code: fetch a table like job info or compensation so the code it produces matches BambooHR's row-per-change structure

• Read a report's output before generating ingestion code: run a company report so the parser it writes matches the report's real columns and layout

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

You can build a self-hosted MCP server on BambooHR's API. For one company and one use case, it's workable: generate an API key from the admin panel, pass it as a header, and start making calls.

It gets harder once tasks run across more than one account or more than one HR system.

Each API key carries that company's full access, with no way to scope which operations a Codex task can call, and a BambooHR-specific server only ever solves BambooHR.

The moment a task needs Workday or another HRIS instead, you're building and authenticating another integration. BambooHR also holds compensation and personal data, and a self-hosted setup has no field-level control or audit log to keep that data out of a task's context.

Merge Agent Handler handles BambooHR authentication centrally and exposes the same tools across HR systems through one connection. You can scope exactly which BambooHR operations a Codex task can call, block sensitive fields before they reach the task, and every call is logged with identity, timestamp, and inputs.

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

Why connect BambooHR to Codex?

BambooHR holds the field aliases, custom fields, time-off types, and tables that people ops code has to match exactly.

Codex tasks that build syncs, mappings, or onboarding automations need that ground truth to produce code that works against the real account.

The alternative is describing your BambooHR setup in the prompt, and those descriptions are always incomplete. An assumed field shape, a label used instead of an alias, or a missing time-off type is enough to make Codex generate code that breaks on real data.

Connecting BambooHR lets Codex read the actual structure when a task needs it. The real record before a parser, the real field aliases before a mapping, the real time-off types before validation: Codex works from the account itself, not a paraphrase of it.

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

Common patterns include:

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

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

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

Taken together, employees can use the BambooHR MCP to scaffold syncs against the real field schema, generate mappings grounded in actual field aliases, build validation tied to real time-off types, and more, while IT keeps centralized control over which employee data each agent can reach.