Connect your AI Agents to CyberArk Identity in minutes
Available tools
list_applications
List or search the web/SaaS applications configured on the tenant with pagination. Pass 'search' to filter by a case-insensitive substring of the app name or display name; omit it to browse all. Returns applications (each with its ID for getapplication/deleteapplication) and page_info.
get_application
Get one application's full configuration by its row key (use list_applications to find valid IDs). Returns the complete configuration object, whose keys vary by application type (SAML, OIDC, username/password). Raises a not-found error if no application has that ID.
delete_application
Permanently delete an application instance by its row key (use list_applications to find it). This removes the application and cannot be undone. Returns whether the deletion succeeded.
list_groups
List or search directory groups across the tenant's directory services with pagination. Pass 'search' to filter by a substring of the group display or system name; omit it to list all. Returns groups (each with its InternalName GUID, usable as a groupid for adduserstorole) and page_info. Pages are capped at 50; use search to narrow very large directories.
list_auth_profiles
List the authentication (MFA) profiles configured on the tenant, each with its UUID, name, and challenge duration. Authentication policies reference these profiles. Use this to see which MFA profiles exist. Returns the profiles.
list_devices
List the devices enrolled/managed on the tenant with pagination, each with its ID, name, and enrollment state. Use this to see which devices are registered. Returns devices and page_info.
list_directories
List the directory services configured on the tenant (cloud directory, Active Directory, federated directories, etc.), each with its UUID, type, display name, and status. Use this to discover which directories exist before working with users and roles sourced from them.
get_tenant_suffixes
List the username suffixes (directory aliases) configured for the tenant. A new user's login name is 'username@suffix', so call this before createuser to choose a valid suffix, or to see which suffix createuser will default to. Returns each suffix and whether it is the cloud-directory alias.
list_organizations
List the organization units (sub-organizations) configured on the tenant, each with its ID, name, path, and administrators. Use this to discover org units before fetching one with get_organization. Returns the org units.
get_organization
Get one organization unit's details (name, description, path) by its ID. Use list_organizations to find valid org IDs. Raises a not-found error if no org unit has that ID.
get_policy
Retrieve a policy set's full configuration block by its path/name, e.g. '/Policy/Default Policy'. The block includes authentication profiles, directory services, settings, and risk levels. Policy names follow the '/Policy/<Name>' convention. Returns the policy configuration object.
list_roles
List or search CyberArk Identity roles with pagination. Pass 'search' to filter by a case-insensitive substring of the role name; omit it to browse all roles. Returns roles (each with its ID) and pageinfo. Call this first to get the roleid required by updaterole, deleterole, listrolemembers, adduserstorole, removeusersfromrole, and assignadminrightstorole.
get_role
Get a single role's details (ID, name, description) by its internal ID. Use listroles to find valid role IDs. Use listrolemembers to see who belongs to the role, or listrole_apps for its applications. Raises a not-found error if no role has that ID.
list_role_apps
List the applications assigned to a role, identified by its ID (use listroles to find it). Returns each application's ID, name, and type, plus pageinfo. The API returns the full set; pagination is applied client-side.
list_role_members
List the members (users, groups, and nested roles) of a role, identified by its ID. Use listroles to find valid role IDs. Returns each member's GUID, name, and type, plus pageinfo. The API returns the full member set; pagination is applied client-side.
create_role
Create a new role with a name and optional description. The name must be unique within the tenant. Returns the new role's ID for use with updaterole, deleterole, and the membership tools. Use assignadminrightstorole afterwards to grant administrative rights.
update_role
Rename a role or change its description, identified by role ID (use list_roles to find it). Only the fields you pass are changed. Overwrites the previous name/description. Returns whether the update succeeded.
delete_role
Permanently delete a role by its ID (use list_roles to find it). This removes the role and its membership assignments and cannot be undone. Returns whether the deletion succeeded.
add_users_to_role
Add users, groups, and/or nested roles to a role, identified by role ID (use listroles to find it). Provide any combination of userids (from listusers), groupids, and nestedroleids; at least one is required. Adds to the existing membership without removing anyone. Returns whether the change succeeded.
remove_users_from_role
Remove users, groups, and/or nested roles from a role, identified by role ID (use listroles to find it). Provide any combination of userids, groupids, and nestedrole_ids; at least one is required. Removes only the members you name. Returns whether the change succeeded.
list_administrative_rights
List distinct administrative rights held by roles of the connected, signed-in account. Rights absent from those roles are not returned because CyberArk exposes no full rights catalog endpoint. Use this tool to discover valid opaque ServiceRight/* paths for assignadminrightstorole and unassignadminrightsfromrole.
assign_admin_rights_to_role
Grant administrative rights to a role, identified by role ID (use listroles to find it). adminrights is a list of opaque CyberArk right paths like ['ServiceRight/administrationShowTile'] (NOT friendly names) — call listadministrativerights first to discover valid paths. Adds the rights to the role. Returns whether the change succeeded.
unassign_admin_rights_from_role
Revoke administrative rights from a CyberArk Identity role using opaque ServiceRight/* paths, not friendly names. Use listroles to find the role ID and listadministrativerights to discover valid paths. This is the inverse of assignadminrightsto_role and returns whether the rights were removed.
list_users
List or search CyberArk Identity users with pagination. Pass 'search' to filter by a case-insensitive substring across username, display name, and email; omit it to browse all users. Returns users (each with its ID for getuser/updateuser/deleteuser) and pageinfo. Use get_user when you already have a user ID.
get_user
Get a single CyberArk Identity user's details by their internal UUID. Use list_users to find valid user IDs. Returns the user's profile (username, display name, email, mobile, last login). Raises a not-found error if no user has that ID.
create_user
Create a new user in the tenant's cloud directory. Requires 'username' and 'password'; the login suffix is appended automatically (call gettenantsuffixes to see valid suffixes, or pass 'suffix' to override). Optionally set display name, email, and mobile. Returns the new user's ID and fully-qualified username for use with getuser/updateuser/delete_user.
update_user
Update an existing user's display name, email, or mobile number. Identify the user by their UUID (use listusers or getuser to find it). Only the fields you pass are changed; omitted fields are left as-is. Overwrites the previous values of the fields it sets.
delete_user
Permanently delete a user by their UUID (use listusers or getuser to find it). This removes the user from the directory and cannot be undone. Returns whether the deletion succeeded.
reset_user_password
Set a new password for an existing user, identified by UUID (use listusers or getuser to find it). The new password must satisfy the tenant's password policy. Overwrites the user's current password. Returns whether the reset succeeded.
get_user_attributes
Get a user's full attribute set by UUID (use listusers or getuser to find it): directory attributes, group memberships, account state, and password-policy flags, beyond the lean fields get_user returns. Use this when you need a user's complete profile. Returns the attribute object.
get_user_roles
List the roles (and administrative rights) assigned to a user, identified by UUID (use listusers or getuser to find it). This is the user->roles direction; listrolemembers is the role->users direction. Returns the user's roles, each with its ID.
exempt_user_from_mfa
Exempt a user from multi-factor authentication, identified by UUID (use listusers or getuser to find it). A documented onboarding operation that overrides the user's MFA requirement. Returns whether the exemption was applied.
invite_users
Send login/activation invitations to one or more users by UUID (use list_users to find them). Adds an invitation for each user without changing existing accounts. Returns whether the invitations were sent and how many users were requested.
validate_credential
Validate CyberArk Identity credentials by signing in and calling Security/whoami. Returns success status and a message. Use this to confirm the subdomain, username, and password are correct before running other 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}
11Copy 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 CyberArk Identity MCP server
FAQs on using Merge's CyberArk Identity MCP server
Ready to try it out?
Whether you're an engineer experimenting with agents or a product manager looking to add tools, you can get started for free now
