Okta User Management MCP server for AI agents

This MCP server connects Claude to Okta's user management system, enabling comprehensive user and group management with onboarding automation capabilities. It acts as a bridge that allows Claude to interact with Okta's API for managing users and groups.

Prerequisites

Node.js (v16 or higher)
Claude Desktop App
Okta Developer Account
Admin API Token from Okta

Installation

Create an Okta Developer Account

Go to the Okta Developer Console
Create a new account or sign in to an existing one
Note your Okta domain (e.g., dev-123456.okta.com)

Create an API Token

In the Okta Developer Console, go to Security > API > Tokens
Click "Create Token"
Give your token a meaningful name (e.g., "MCP Server Token")
Copy the token value (you won't be able to see it again)

Initial Project Setup

Install dependencies:

npm install

Configure Claude Desktop

Open your Claude Desktop configuration file:

For MacOS:

code ~/Library/Application\ Support/Claude/claude_desktop_config.json

For Windows:

code %AppData%\Claude\claude_desktop_config.json

Add or update the configuration:

{
    "mcpServers": {
        "okta": {
            "command": "node",
            "args": [
                "PATH_TO_PROJECT_DIRECTORY/dist/index.js"
            ],
            "env": {
                "OKTA_ORG_URL": "https://your-domain.okta.com",
                "OKTA_API_TOKEN": "your-api-token"
            }
        }
    }
}

Save the file and restart Claude Desktop.

Available Tools

User Management

get_user

Retrieves detailed user information from Okta, including user details, account dates, personal information, employment details, contact information, address, and preferences.

find_users_by_attribute

Search users by any profile attribute with advanced filtering:

Supported attributes: firstName, lastName, email, manager, department, title, division, organization, employeeNumber, costCenter, userType, city, state
Search operators:
- eq (exact match) - Works for all attributes
- sw (starts with) - Works for all attributes
- ew (ends with) - Works for most attributes
- co (contains) - Works for some attributes (firstName, lastName, email)
- pr (present/exists) - Works for all attributes

list_users

Lists users from Okta with optional filtering and pagination, supporting SCIM filter expressions, free-form text search, sorting options, and pagination.

activate_user

Activates a user in Okta with option to send activation email.

suspend_user

Suspends a user in Okta.

unsuspend_user

Unsuspends a previously suspended user in Okta.

delete_user

Deletes a user from Okta (note: user must be deactivated first).

get_user_last_location

Retrieves the last known location and login information for a user from Okta system logs.

Group Management

list_groups

Lists user groups from Okta with optional filtering and pagination.

create_group

Creates a new group in Okta with a name and optional description.

get_group

Retrieves detailed information about a specific group.

delete_group

Deletes a group from Okta.

assign_user_to_group

Assigns a user to a group in Okta.

remove_user_from_group

Removes a user from a group in Okta.

list_group_users

Lists all users in a specific group with pagination support.

Onboarding Automation (Experimental)

bulk_user_import

Imports multiple users from a CSV string, creating user accounts, with optional activation and email notifications.

assign_users_to_groups

Assigns multiple users to groups based on attribute mappings.

provision_applications

Provisions application access for multiple users.

run_onboarding_workflow

Runs a complete onboarding workflow for multiple users from CSV data.

Usage Examples

User Management

"Show me details for user with userId XXXX"
"Find all users in the engineering department"
"Search for users with first name starting with 'John'"
"Find users whose email contains 'gmail'"
"Show me all users who have a department assigned"
"List users whose title is 'Manager'"
"Activate user with ID XXXX"
"Suspend user with ID XXXX"
"Where did user XXXX last log in from?"

Advanced User Searches

"Find all users in the Sales department"
"Show me users whose email starts with 'admin'"
"Find users with any manager assigned"
"List users whose last name contains 'smith'"

Group Management

"Show me all groups in my Okta organization"
"List groups containing the word 'admin'"
"Create a new group called 'Marketing Team'"
"Add user XXXX to group YYYY"
"List all users in the 'Finance' group"

Onboarding Automation

"Import these users from CSV data: [CSV content]"
"Assign users to groups based on their department attribute"
"Run a complete onboarding workflow for these new hires: [CSV content]"

Troubleshooting

Common Issues

Tools not appearing in Claude:

Check Claude Desktop logs: tail -f ~/Library/Logs/Claude/mcp*.log
Verify all environment variables are set correctly
Ensure the path to index.js is absolute and correct

Authentication Errors:

Verify your API token is valid
Check if OKTA_ORG_URL includes the full URL with https://
Ensure your Okta domain is correct

Search Issues:

Some search operators are not supported for all attributes
Check the response message for which search method was used

Viewing Logs

For MacOS/Linux:

tail -n 20 -f ~/Library/Logs/Claude/mcp*.log

For Windows:

Get-Content -Path "$env:AppData\Claude\Logs\mcp*.log" -Wait -Tail 20

CSV Format for Onboarding

When using the bulk import or onboarding workflow tools, your CSV should include these headers:

firstName (required)
lastName (required)
email (required)
department (optional)
title (optional)
mobilePhone (optional)

Example:

firstName,lastName,email,department,title,mobilePhone
John,Doe,[email protected],Engineering,Senior Developer,+1-555-123-4567
Jane,Smith,[email protected],Marketing,Director,+1-555-987-6543

How to install this MCP server

For Claude Code

To add this MCP server to Claude Code, run this command in your terminal:

claude mcp add-json "okta" '{"command":"node","args":["PATH_TO_PROJECT_DIRECTORY/dist/index.js"],"env":{"OKTA_ORG_URL":"https://your-domain.okta.com","OKTA_API_TOKEN":"your-api-token"}}'

See the official Claude Code MCP documentation for more details.

For Cursor

There are two ways to add an MCP server to Cursor. The most common way is to add the server globally in the ~/.cursor/mcp.json file so that it is available in all of your projects.

If you only need the server in a single project, you can add it to the project instead by creating or adding it to the .cursor/mcp.json file.

Adding an MCP server to Cursor globally

To add a global MCP server go to Cursor Settings > Tools & Integrations and click "New MCP Server".

When you click that button the ~/.cursor/mcp.json file will be opened and you can add your server like this:

{
    "mcpServers": {
        "okta": {
            "command": "node",
            "args": [
                "PATH_TO_PROJECT_DIRECTORY/dist/index.js"
            ],
            "env": {
                "OKTA_ORG_URL": "https://your-domain.okta.com",
                "OKTA_API_TOKEN": "your-api-token"
            }
        }
    }
}

Adding an MCP server to a project

To add an MCP server to a project you can create a new .cursor/mcp.json file or add it to the existing one. This will look exactly the same as the global MCP server example above.

How to use the MCP server

Once the server is installed, you might need to head back to Settings > MCP and click the refresh button.

The Cursor agent will then be able to see the available tools the added MCP server has available and will call them when it needs to.

You can also explicitly ask the agent to use the tool by mentioning the tool name and describing what the function does.

For Claude Desktop

To add this MCP server to Claude Desktop:

1. Find your configuration file:

macOS: ~/Library/Application Support/Claude/claude_desktop_config.json
Windows: %APPDATA%\Claude\claude_desktop_config.json
Linux: ~/.config/Claude/claude_desktop_config.json

2. Add this to your configuration file:

{
    "mcpServers": {
        "okta": {
            "command": "node",
            "args": [
                "PATH_TO_PROJECT_DIRECTORY/dist/index.js"
            ],
            "env": {
                "OKTA_ORG_URL": "https://your-domain.okta.com",
                "OKTA_API_TOKEN": "your-api-token"
            }
        }
    }
}

3. Restart Claude Desktop for the changes to take effect