How to connect an Oracle HCM MCP with Codex (4 steps)

When you hand Codex a task to build an Oracle HCM sync or a workforce reporting tool, you'd describe the tenant's data model in the prompt.

That description rarely matches the real tenant. Flexfield segment names, the Person and Assignment split, and which fields are effective-dated are details a summary skips.

So Codex writes a parser that merges Person and Assignment incorrectly, a sync that ignores flexfield segments unique to that tenant, or logic that doesn't account for effective-dating.

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

How it works

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

Merge will resolve the per-tenant domain URL and manages Oracle Identity Cloud Service OAuth credentials on your behalf, so no instance-specific secret lives in your repo.

Related: How to use the Oracle HCM 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 Oracle HCM account with API access (requires an Oracle Cloud administrator to enable REST API access and provide your instance's base URL and OAuth credentials)

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

4. Authenticate Oracle HCM

Create a Codex task that needs live Oracle HCM data. For example: "Read the Person and Assignment schema for one employee, including any flexfield segments, then scaffold a sync that maps Oracle HCM fields into our internal HR data warehouse schema, respecting effective-dating."

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

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

{{this-blog-only-cta}}

Oracle HCM MCP FAQ

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

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

With Oracle HCM connected, Codex can:

• Read a real Person and Assignment schema before scaffolding a sync: pull both resources for one employee so the sync it generates joins identity and work-relationship data correctly instead of assuming a flat structure

• Pull real flexfield segments before generating type definitions: fetch a record with descriptive or extensible flexfields so the types it emits match the actual segments configured for that tenant

• Read the REST link structure before generating a client that traverses related resources: fetch a resource with its links array so the traversal code it writes follows the real relationships between resources

• Pull effective-dated records before generating as-of-date logic: fetch a record valid on a specific date so the code it writes handles Oracle's effective-dating correctly instead of assuming a single current value

• Read lookup and value set codes before generating validation: pull the real job code and grade values so the validation and enums it produces match the tenant's actual codes

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

You can build directly against Oracle HCM's REST API. For one tenant and one use case, it's workable: get OAuth credentials from an Oracle Cloud administrator, configure the token endpoint for the IDCS domain, and start making calls.

It gets harder once tasks run across more than one Oracle HCM tenant.

Each tenant has its own domain URL, its own IDCS instance, and its own OAuth application, with no single global endpoint and no way to scope which operations a Codex task can call.

Oracle HCM also holds compensation and talent review 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 resolves the per-tenant domain and handles IDCS authentication centrally across every connected Oracle HCM deployment. You can scope exactly which operations a Codex task can call, and every call is logged with identity, timestamp, and inputs.

Why connect Oracle HCM to Codex?

Oracle HCM holds the Person and Assignment structure, tenant-specific flexfields, and effective-dated history that workforce automation code has to match exactly.

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

The alternative is describing the tenant's data model in the prompt, and those descriptions are always incomplete. An assumed Person/Assignment join, a missed flexfield segment, or an ignored effective-dating rule is enough to make Codex generate code that breaks on real data.

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

Can I use Merge's Oracle HCM 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 Oracle HCM.

Common patterns include:

• Provisioning and access control via SCIM with identity providers like Okta and Microsoft Entra ID, so IT can manage which tenants and fields 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 compensation or talent review data before results reach a Codex task's context

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

Taken together, employees can use the Oracle HCM MCP to scaffold syncs against real Person and Assignment structure, generate validation tied to actual flexfield segments, build automations that respect real effective-dating, and more. All the while, IT keeps centralized control over which tenants and fields each agent can reach.