How to connect an Okta MCP with Codex (4 steps)

When you hand Codex a task to build an Okta sync or an access-review tool, you describe the org's user and group structure in the prompt.

That description rarely matches the real org. Custom profile attributes, real group and app IDs, and how pagination and rate limits actually behave are details a summary skips.

So Codex writes a sync against an assumed profile schema, a report that misses how Okta paginates through its Link header instead of a body field, or provisioning logic that doesn't account for real rate limits. The source of truth lives in Okta, not the few lines you wrote into the task.

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

How it works

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

Merge will also manage your Okta API credentials and handles rate limits on your behalf, so no org-wide token lives in your repo.

Related: How to use the Okta 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 Okta account with API access enabled (requires an Okta admin to generate an API token or configure an OAuth service app)

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

Create a Codex task that needs live Okta data, for example: "Read a real user's profile schema and their group and app assignments, then scaffold a sync that maps our org's Okta users into our internal directory schema, handling pagination correctly."

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

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

{{this-blog-only-cta}}

Okta MCP FAQ

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

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

With Okta connected, Codex can:

• Read the real user profile schema before scaffolding a sync: pull a real user so the sync it generates maps the org's actual custom attributes instead of an assumed profile shape

• Pull group and app assignment data before generating provisioning logic: fetch real group membership and app assignments so the provisioning code it writes reflects the real access model

• Read System Log event structure before generating security monitoring code: fetch real log events so the parser or alerting logic it writes matches the actual actor, target, and outcome shape

• Pull pagination and rate-limit behavior before generating a sync loop: fetch a paginated response and the rate-limit headers so the loop it writes follows Okta's Link-header pagination and backs off correctly

• Read factor enrollment data before generating MFA-related code: fetch real factor records so the code it produces handles the actual enrolled factor types and statuses

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

You can build directly against Okta's API. For one org and one use case, it's workable: generate an API token from the admin console and start making calls.

It gets harder once tasks run across more than one org or need scoped access. Okta API tokens are tied to the admin account that created them and stop working if that account is deactivated, and a raw token carries full org access with no way to limit a Codex task to read-only user lookups.

Rate limits are also shared per org across every consumer of a token, so a task with no backoff logic can throttle every other integration calling Okta at the same time.

Merge Agent Handler manages Okta authentication centrally and handles rate limits on your behalf. You can scope exactly which Okta operations a Codex task can call, and every call is logged with identity, timestamp, and inputs.

For an agent that can read or modify identity data across your org, scoped access plus full audit logging is the foundation you want in place first.

Why connect Okta to Codex?

Okta holds the user profile schema, group and app assignment structure, and System Log format that identity automation code has to match exactly.

Codex tasks that build syncs, access-review tools, or security monitoring need that ground truth to produce code that works against the real org.

The alternative is describing the org's structure in the prompt, and those descriptions are always incomplete. A missed custom attribute, an assumed pagination format, or a wrong guess at the log event shape is enough to make Codex generate code that breaks on real data.

Connecting Okta lets Codex read the actual structure when a task needs it. The real user schema before a sync, the real group and app assignments before provisioning logic, the real log format before a monitoring script: Codex works from the org itself, not a paraphrase of it.

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

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 user, group, and app data by role or team

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

• User-level audit logging so security and IT teams can review which user, group, and app records were queried or modified, by which employee identity, and when

Taken together, employees can use the Okta MCP to scaffold syncs against real user schemas, generate provisioning logic grounded in actual group and app assignments,  build monitoring tied to real log data, and more. All the while, IT can keep centralized control over which identity data each agent can reach.