Merge Unified's Okta integration Merge Agent Handler's Okta MCP server

Connect your AI Agents to Okta in minutes

Merge lets you securely connect your agents to Okta and thousands of tools instantly

Start building for free

Read docs

Okta

Learn more about Merge Agent Handler

Available tools

list_app_groups

List groups assigned to an Okta application with cursor pagination. Rows carry the group ID and priority only, so pass expand=group to embed each full group (including its name) instead of calling getgroup per row. Use q to filter by group name. Use listapps to find the app ID.

get_app_group

Get a specific group's assignment to an Okta application. Use listapps and listgroups (or listappgroups) to find IDs.

assign_group_to_app

Assign a group to an Okta application (all group members get app access). Use for the initial assignment; use updateappgroupassignment to change priority or profile on a group that is already assigned. This fully replaces any existing assignment, resetting fields you omit. Use listapps for the app ID and list_groups for the group ID. Optionally set priority or a profile.

update_app_group_assignment

Update a group's assignment (priority or app-specific profile) for an Okta application, leaving fields you omit unchanged. Use when the group is already assigned; use assigngrouptoapp for the initial assignment. Use listappgroups to find assignments and listapps for the app ID.

unassign_group_from_app

Remove a group's assignment from an Okta application. Use listappgroups to find assignments and list_apps for the app ID.

list_app_users

List users assigned to an Okta application with cursor pagination. Use q to filter, expand=user to embed the full user. Use list_apps to find the app ID.

get_app_user

Get a specific user's assignment to an Okta application. Use listapps and listusers (or listappusers) to find IDs.

assign_user_to_app

Assign a user to an Okta application. Provide the user id (use listusers) and the app id (use listapps). Optionally set an app-specific profile or credentials. Only creates new assignments: re-assigning an already-assigned user is rejected, so use updateappuser to change an existing assignment. Returns the app-user assignment.

update_app_user

Update a user's app-specific profile or credentials for an Okta application. Use listappusers to find assigned users and list_apps for the app ID.

unassign_user_from_app

Remove a user's assignment from an Okta application. Use listappusers to find assigned users and list_apps for the app ID.

list_apps

List Okta applications with cursor pagination. Use q to match app name/label, or filter (e.g. 'status eq "ACTIVE"', 'user.id eq "<id>"', 'group.id eq "<id>"'). Pass page_info.cursor as after for the next page.

get_app

Get an Okta application by ID. Use list_apps to find valid IDs.

activate_app

Activate an INACTIVE Okta application. Use list_apps to find IDs.

deactivate_app

Deactivate an ACTIVE Okta application. Required before deleteapp. Use listapps to find IDs.

delete_app

Permanently delete an Okta application. The app must be deactivated first (call deactivateapp). Use listapps to find IDs.

list_group_owners

List owners (users or groups) of an Okta group with cursor pagination. Requires an Okta Identity Governance subscription; without it the Group Owners API is unavailable and this call fails. Use search for a SCIM-style filter (e.g. 'type eq "USER"'). Use list_groups to find the group ID.

add_group_owner

Assign an owner to an Okta group. Set type to USER or GROUP and id to the owner's ID. Use listusers or listgroups to find IDs, and list_groups for the group. Requires an Okta Identity Governance subscription; without it the Group Owners API is unavailable and this call fails.

remove_group_owner

Remove an owner from an Okta group. Use listgroupowners to find owner IDs and list_groups for the group ID. Requires an Okta Identity Governance subscription; without it the Group Owners API is unavailable and this call fails.

list_group_rules

List Okta group rules with cursor pagination. Use search to match a rule name.

get_group_rule

Get an Okta group rule by ID. Use listgrouprules to find valid IDs.

create_group_rule

Create an Okta group rule that auto-assigns matching users to groups. Provide an Okta Expression Language condition and the target groupIds. Use listgroups to find group IDs first. New rules are INACTIVE; call activategroup_rule to enable. Returns the rule with its id.

update_group_rule

Replace an Okta group rule's name, condition, and target groups. The rule must be INACTIVE (call deactivategrouprule first). Use listgroups for group IDs and listgroup_rules for the rule ID. Returns the updated rule.

delete_group_rule

Delete an Okta group rule. Use listgrouprules to find IDs.

activate_group_rule

Activate an INACTIVE Okta group rule so it starts assigning users. Use listgrouprules to find IDs.

deactivate_group_rule

Deactivate an ACTIVE Okta group rule. Required before updategrouprule. Use listgrouprules to find IDs.

list_groups

List Okta groups with cursor pagination. Use search for a SCIM-style filter (e.g. 'type eq "OKTAGROUP"'), q for a starts-with match on group name, or filter for a property subset. Pass pageinfo.cursor as after for the next page.

get_group

Get an Okta group by ID. Use list_groups to find valid IDs.

create_group

Create an Okta group (OKTA_GROUP type). profile.name is required. Returns the new group with its id.

update_group

Replace an Okta group's profile (name required). Only OKTAGROUP type groups can be updated. Use listgroups to find the group ID. Returns the updated group.

delete_group

Permanently delete an Okta group. Only OKTAGROUP type groups can be deleted. Use listgroups to find IDs.

list_group_users

List members of an Okta group with cursor pagination. Use list_groups to find the group ID.

add_user_to_group

Add a user to an Okta group. Use listgroups to find the group ID and listusers to find the user ID. Only OKTA_GROUP type groups accept members.

remove_user_from_group

Remove a user from an Okta group. Use listgroupusers to find members. Use listgroups/listusers for IDs.

list_group_apps

List applications assigned to an Okta group with cursor pagination. Use list_groups to find the group ID.

list_log_events

List Okta System Log events with cursor pagination. Filter by time window (since/until, ISO 8601), a filter expression (e.g. 'eventType eq "user.session.start"'), or q keyword search. Defaults to the last 7 days. Pass pageinfo.cursor as after for the next page, and stop when hasnext_page is false or a page returns no events.

list_users

List Okta users with cursor pagination. Use search for a SCIM-style filter (e.g. 'status eq "ACTIVE"'), q for a simple starts-with match on name/email, or filter for a subset of properties. Use fields to trim the payload. Pass page_info.cursor as after for the next page.

get_user

Get an Okta user by ID or login. Use list_users to find valid IDs.

create_user

Create an Okta user. profile requires firstName, lastName, email, and login. Optionally set credentials to give the user a password or recovery question at creation. Set activate=false to create in STAGED status. Optionally add to groups via groupIds (use list_groups to find IDs). Returns the new user with its id.

update_user

Partially update an Okta user's profile or credentials. Only supplied fields change. Supply at least one of profile or credentials; use credentials.password.value to set a password after createuser. Use listusers to find the user ID. Returns the updated user.

delete_user

Permanently delete an Okta user. The user must already be deactivated (call deactivateuser first). This is irreversible. Use listusers to find IDs.

activate_user

Activate a STAGED or DEPROVISIONED Okta user. Use listusers to find IDs. Okta emails an activation link by default; with sendEmail=false the returned activationtoken and activation_url are the only way the user can set a password and cannot be re-fetched. Treat both as credentials: deliver them to the user, never echo or store them.

deactivate_user

Deactivate an Okta user (moves to DEPROVISIONED). Required before deleteuser. Use listusers to find IDs.

suspend_user

Suspend an ACTIVE Okta user (moves to SUSPENDED). Use list_users to find IDs.

unsuspend_user

Unsuspend a SUSPENDED Okta user (returns to ACTIVE). Use list_users to find IDs.

unlock_user

Unlock a LOCKEDOUT Okta user (returns to ACTIVE). Use listusers to find IDs.

validate_credential

Validate Okta credentials by making a minimal read call. Returns success status and a message. Works for both API token and OAuth2 auth.

View all tools by creating a free account See more tools

How to set up Merge Agent Handler

In an mcp.json file, add the configuration below, and restart Cursor.

Learn more in the official documentation ↗

1{
2  "mcpServers": {
3    "agent-handler": {
4      "url": "https://ah-api-develop.merge.dev/api/v1/tool-packs/{TOOL_PACK_ID}/registered-users/{REGISTERED_USER_ID}/mcp",
5      "headers": {
6        "Authorization": "Bearer yMt*****"
7      }
8    }
9  }
10}
11

Copy Code

Open your Claude Desktop configuration file and add the server configuration below. You'll also need to restart the application for the changes to take effect.

Make sure Claude is using the Node v20+.

Learn more in the official documentation ↗

1{
2  "mcpServers": {
3    "agent-handler": {
4      "command": "npx",
5      "args": [
6        "-y",
7        "mcp-remote@latest",
8        "https://ah-api-develop.merge.dev/api/v1/tool-packs/{TOOL_PACK_ID}/registered-users/{REGISTERED_USER_ID}/mcp",
9        "--header",
10        "Authorization: Bearer ${AUTH_TOKEN}"
11      ],
12      "env": {
13        "AUTH_TOKEN": "yMt*****"
14      }
15    }
16  }
17}

Copy Code

Open your Windsurf MCP configuration file and add the server configuration below.
Click on the refresh button in the top right of the Manage MCP server page or in the top right of the chat box in the box icon.

Learn more in the official documentation ↗

1{
2    "mcpServers": {
3      "agent-handler": {
4        "command": "npx",
5        "args": [
6          "-y",
7          "mcp-remote@latest",
8          "https://ah-api.merge.dev/api/v1/tool-packs/<tool-pack-id>/registered-users/<registered-user-id>/mcp",
9          "--header",
10          "Authorization: Bearer ${AUTH_TOKEN}"
11        ],
12        "env": {
13          "AUTH_TOKEN": "<ah-production-access-key>"
14        }
15      }
16    }
17  }

Copy Code

In Command Palette (Cmd+Shift+P on macOS, Ctrl+Shift+P on Windows), run "MCP: Open User Configuration".

You can then add the configuration below and press "start" right under servers. Enter the auth token when prompted.

Learn more in the official documentation ↗

1{
2  "inputs": [
3    {
4      "type": "promptString",
5      "id": "agent-handler-auth",
6      "description": "Agent Handler AUTH_TOKEN", // "yMt*****" when prompt
7      "password": true
8    }
9  ],
10  "servers": {
11    "agent-handler": {
12      "type": "stdio",
13      "command": "npx",
14      "args": [
15        "-y",
16        "mcp-remote@latest",
17        "https://ah-api-develop.merge.dev/api/v1/tool-packs/{TOOL_PACK_ID}/registered-users/{REGISTERED_USER_ID}/mcp",
18        "--header",
19        "Authorization: Bearer ${input:agent-handler-auth}"
20      ]
21    }
22  }
23}

Copy Code

FAQs on using Merge's Okta MCP server

What is an Okta MCP?

It's an MCP server that lets your agents access data and functionality from Okta via tools. Your agents can invoke these tools to look up a user's account status, check group membership, review recent sign-in activity, list assigned applications, and more.

Okta offers an official MCP server, but you can also use one from a third-party platform, like Merge Agent Handler.

How can I use the Okta MCP server?

The use cases naturally depend on the agent you've built, but here are a few common ones:

Offboarding automation: when an HR system marks an employee as terminated, an agent can deactivate the corresponding Okta user and remove them from all assigned groups, cutting off access the moment the trigger fires

Suspicious sign-in investigation: an agent watching for anomaly alerts can pull a user's recent Okta system log events, correlate the location and device against their normal pattern, and flag the session for a security analyst

Access review reporting: on a recurring schedule, an agent can list group memberships and application assignments for a department and compile a summary for a compliance audit

App assignment provisioning for new hires: triggered by a new employee record in the HRIS, an agent can assign the right Okta applications and add the user to the groups their role requires

What are popular tools for Okta's MCP server?

Here are some of the most commonly used tools:

list_users: returns Okta user records filtered by status, group, or search query. Useful for agents that need to check who's active, suspended, or deactivated before taking action

get_user: fetches the full profile and status for a single Okta user by ID or login. Call this when an agent needs to confirm account state before a downstream action like resetting a factor or updating group membership

list_groups: retrieves Okta groups and their metadata, including group type and membership rules. Good for workflows that map organizational structure or check whether a user belongs to a privileged group

list_applications: lists the applications configured in an Okta org along with their assignment status. Helpful when an agent needs to confirm which apps a user or group has access to

list_system_log_events: pulls Okta's system log filtered by actor, event type, or time range. Use this when an agent is investigating sign-in activity or reconstructing a sequence of account changes

list_user_factors: returns the MFA factors enrolled for a given user, such as push, SMS, or security key. Useful for agents handling factor troubleshooting or verifying MFA enrollment status

What makes Merge Agent Handler's Okta MCP server better than alternative Okta MCP servers?

There are several reasons to use Merge Agent Handler's Okta MCP server over building or maintaining one yourself:

Enterprise-grade security and DLP: Merge Agent Handler includes built-in data loss prevention controls that let you block or redact sensitive fields before they reach an agent. For Okta, this means you can prevent MFA factor details, session tokens, or personal identity attributes from being exposed even when the agent has broad read access

Managed authentication and credentials: Merge stores and refreshes Okta credentials on your behalf. You never expose raw API keys or OAuth tokens to an agent or manage token rotation manually

Real-time observability and audit trail: Every tool call made against Okta is logged with timestamp, tool name, input parameters, and response metadata. You can audit exactly what an agent read or wrote without instrumenting anything yourself

Tool Packs and controlled access: Tool Packs let you bundle specific Okta tools with tools from other connectors into a single MCP endpoint, scoped to a specific use case. An agent gets exactly the tools it needs, nothing more

How can I start using Merge Agent Handler's Okta MCP server?

You can take the following steps:

1. Create or log into your Merge Agent Handler account.

2. Install the Merge CLI by running pipx install merge-api, then run merge configure to link the CLI to your Merge account and merge login to authenticate your session.

3. Register the Agent Handler MCP server with Claude Code by running claude mcp add --transport http agent-handler https://ah-api.merge.dev/mcp, then open Claude Code and run /mcp to confirm agent-handler appears with a connected status.

4. Select agent-handler from the MCP list. This opens a browser window where you select which integrations to authenticate. Choose Okta and complete the auth flow. Merge stores and manages the credentials going forward.

5. Open a Claude Code session and start querying Okta data directly. The first time you use an Okta tool, a Magic Link may appear to complete connector authentication.

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.

Can employees use Merge to connect their AI tools to Okta?

Yes, Merge for Workforce lets your employees connect Claude, ChatGPT, Microsoft Copilot, Cursor, Codex, and other MCP-compatible AI tools to Okta without bypassing IT governance.

Instead of setting up direct connections with personal credentials that IT can't monitor or revoke, each employee authenticates through Merge and gets individual credentials tied to their identity. An IT support employee, for instance, can ask their AI to check whether a user's account is locked, review recent sign-in attempts, or confirm which applications are assigned, all within the permissions IT has defined.

IT also provisions access by role or group via SCIM. A security analyst, for example, gets Okta access to investigate sign-in anomalies, Slack to coordinate incident response, and PagerDuty to escalate alerts; while an HR coordinator gets Okta access to manage new-hire app assignments, Workday to sync employee records, and Gmail to send onboarding confirmations.

Every tool call an employee's AI makes to Okta is also inspected against your DLP rules and logged to a searchable audit trail, giving security teams full visibility into what data was accessed and by whom.