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

Workday holds the source of truth for how an organization is actually structured: real reporting lines, actual job grades, current headcount, live compensation data.

When developers create Codex tasks to build HR features or integrations, they describe that structure from memory or static documentation.

The actual org data that should inform the feature logic lives in Workday, not in what the developer wrote into the task description. Codex builds against the description, which means it builds against a stale, incomplete version of the org.

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

How it works

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

Once authenticated, Merge handles credential storage and OAuth token refresh on your behalf, so you never embed Workday credentials in your repo or manage rotation yourself.

Related: How to use the Workday 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 Workday account with permission to authenticate the connector

If you want to connect Merge Agent Handler's Workday MCP with internal or customer-facing agentic products, you can follow the steps in our docs.

1. Install the Merge CLI

Run the following to install the Merge CLI: pipx install merge-api

Verify your installation: merge --version

2. Log in to Merge

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

Run the following from the root of the project where you want Codex to have access to Workday:

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 requires Workday data. The command is idempotent, safe to re-run if you need to reset the configuration.

Commit the updated AGENTS.md so every developer and CI environment that runs Codex gets the same tool configuration.

Related: A guide to integrating the Workday MCP with Cursor

4. Authenticate Workday

Create a Codex task that requires live Workday data. This can be something like: "Read the current org structure and reporting hierarchy, then generate a provisioning workflow that correctly handles manager-subordinate relationships and department groupings."

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

Once authenticated, Codex has access to your Workday account through Merge for all subsequent tasks in this project.

{{this-blog-only-cta}}

Workday MCP FAQ

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

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

With Workday connected, Codex can:

• Read live org structure before generating a provisioning workflow: pull the actual reporting hierarchy and department groupings so the generated provisioning logic correctly reflects who reports to whom and how access should cascade through the real org, not a simplified version of it

• Pull current headcount data before generating a team capacity planning feature: fetch live worker counts by department and location so the planning feature Codex scaffolds operates against accurate numbers rather than placeholder data or outdated documentation

• Read actual position and compensation data before generating a pay equity analysis script: retrieve real job grades, salary bands, and compensation fields so the analysis script Codex writes targets the fields that exist in the org, with the correct names and value ranges

• Pull worker lifecycle data to generate an accurate offboarding automation: fetch employment type definitions and worker status values from the live system so the automation Codex generates correctly handles every employment type the org actually uses, including contractor and part-time variants

• Read open position data before generating a candidate matching feature: retrieve live job requisition records, including required skills and hiring manager assignments, so the matching logic Codex produces is grounded in the real positions the org is hiring for

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

You can build a self-hosted Workday MCP server that calls Workday's APIs directly. For an individual developer with a single Workday tenant, that's viable: register an integration system user, configure ISU credentials, write tool schemas for the workers and orgs endpoints you need, and wire it into Codex.

The self-hosted path becomes difficult at the team level.

Workday credentials are ISU-scoped, so credential rotation and sharing has to be managed manually. There's no central place to control which Workday workers or org data a Codex task is allowed to access, no audit trail of what the agent read, and no revocation flow if a developer's access needs to be removed.

Merge Agent Handler adds a managed layer: credential storage and token refresh handled by Merge, per-user authentication so each developer connects with their own identity, and full audit logging on every tool call Codex makes into Workday.

For teams building HR features where Workday holds compensation, employment status, and org structure data, that observability matters.

Why connect Workday to Codex?

Most teams building HR features or workforce integrations use Workday as the authoritative record of how the org is structured. Codex doesn't have access to that structure unless a developer manually describes it in the task. That description is always a simplification.

Real orgs have edge cases: dual-reporting relationships, temporary worker categories, cost center structures that don't map cleanly to department hierarchies. Developers don't include those details in task descriptions. Codex writes code that doesn't handle them.

Connecting Workday gives Codex the ability to read the actual data before generating code. The provisioning workflow it produces reflects the real org. The offboarding automation it generates handles the employment types that actually exist. The pay equity script it writes targets the compensation fields that are live in the system.

That's the difference between code that works for the average case and code that works for the org as it actually is.

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

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 access which Workday data by role or team

• DLP and policy enforcement on tool calls, so admins can block queries that would return compensation records, performance data, or other sensitive HR fields before results reach the employee's Codex session

• User-level audit logging so security and data teams can review which Workday records were accessed, which org or position data was retrieved, by which employee identity, and when

In practice, employees can use the Workday MCP to generate HR feature code grounded in live org data, build workforce integrations that reflect real employment types, and produce automation logic that matches actual Workday configurations, while IT keeps centralized control over which records and operations each developer's agent can reach.