How to connect an Okta MCP with Claude Code (4 steps)

Okta holds the answer to almost every access question a developer gets pulled into during an incident.

Who can still log into the app that's being deprecated? Did a terminated employee's account actually get deprovisioned before the offboarding deadline? Which admin changed a sign-on policy right before an outage started?

That context lives in Okta's user, group, and System Log data, and right now developers have to open the Okta admin console, search manually, and copy findings back into whatever they're debugging.

To help your developers query user, group, and access data from Okta without leaving the terminal, we'll show you how to connect Okta with Merge Agent Handler's Okta MCP server.

How it works

Merge Agent Handler sits between Claude Code and Okta's API.

You install the Merge CLI, authenticate once with your Merge Agent Handler account, and register the connection with a single command.

Merge will manage your Okta API credentials and handles Okta's rate limits on your behalf, so you don't store an org-wide API token locally or write retry logic for rate-limit responses yourself.

Related: A guide to using an Okta MCP in Codex

Prerequisites

Before getting started, you'll need the following:

• A Merge Agent Handler account
• Claude Code installed (run claude --version to confirm)
• 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 with pipx: pipx install merge-api

Then confirm the installation: merge --version

2. Log in to Merge

Run merge login to authenticate the CLI with your Merge Agent Handler account: merge login

This authenticates your session so the CLI can make authorized requests on your behalf going forward.

3. Add Agent Handler to Claude Code

The simplest way to register Agent Handler with Claude Code:

merge setup claude-code

4. Authenticate Okta

Open a Claude Code session and try: "List every user assigned to our billing-service app who hasn't logged in in the last 30 days, and flag any whose account status is still active."

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

List every user assigned to our billing-service app who hasn't logged in in the last 30 days, and flag any whose account status is still active.

{{this-blog-only-cta}}

Okta MCP FAQ

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

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

With Okta connected, Claude Code can:

• List and search users: retrieve user profiles, status (active, suspended, deprovisioned), and profile attributes across the org or scoped to a specific group

• Query group membership: retrieve which users belong to a group or which groups a user belongs to, useful before granting, auditing, or revoking access

• Inspect application assignments: see which users or groups are assigned to a given app, and what SSO or provisioning settings apply to that assignment

• Read the System Log: query security and admin events, including logins, MFA challenges, and admin changes, for a specific user, app, or time window

• Check MFA factor enrollment: see which authentication factors, like push, SMS, TOTP, or WebAuthn, a user has enrolled

• Create or update users and groups: provision new users or modify group membership directly from the terminal, if write tools are enabled in your Tool Pack

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

You can build directly against Okta's API. For a single developer working against one org, that's workable: generate an API token from the admin console and start making requests.

The friction shows up fast once more than one person needs it.

Okta API tokens are tied to the admin account that created them, and the token stops working if that account is ever deactivated or loses admin rights, which is a common failure mode when the person who set up the integration leaves the team. Rate limits are shared per org across every consumer of a token, so one runaway script can throttle everything else calling Okta. And a raw API token carries full access.

Merge Agent Handler manages Okta authentication centrally and adds a control layer on top.

You can scope which Okta operations a given agent is allowed to call, so a tool built for access reviews gets read access to users and group membership without touching policy or admin role endpoints. Every tool call is logged with the timestamp, tool name, and inputs, which matters when the data involves who has access to what across your org.

For a solo developer prototyping against a sandbox org, a direct API token is fine. For a team running agents against production identity data, the access scoping and audit trail are what make the deployment defensible to a security team.

Why connect Okta to Claude Code?

Okta is the system of record for who has access to what across most of the tools your company runs.

User status, group membership, app assignments, and the security event log all live there, and developers pulled into an access question or an incident currently have to leave their terminal, open the Okta admin console, and search manually to get an answer.

With the Okta MCP connected, Claude Code can query that data directly.

You can ask it to confirm an offboarded employee no longer has access to a specific app, pull every admin change that happened in a given time window, or list which users would lose access if a group got deleted, all without leaving the session where you're already working.

This matters most when the question is time-sensitive: during an incident, ahead of an access review, or right before decommissioning an app that still has active users on 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 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 the employee's AI session

• 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

Put together, employees can use the Okta MCP to review access, audit group membership, investigate security events, and more, while IT keeps centralized control over which identity data each agent can reach.