Okta MCP Server

This MCP server enables Claude to interact with Okta's user management system, providing comprehensive user and group management capabilities along with onboarding automation.

Prerequisites

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

Setup Instructions

1. 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)

2. 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)

3. Initial Project Setup

Install dependencies:

npm install

4. 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

The server provides the following tools:

User Management

get_user

Retrieves detailed user information from Okta, including:

User Details (ID, Status)
Account Dates (Created, Activated, Last Login, etc.)
Personal Information (Name, Email)
Employment Details
Contact Information
Address
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 (finds users with any value for that attribute)
Features:
- Uses Okta's native search for optimal performance
- Automatic fallback to client-side filtering for unsupported operators
- PII masking in search results for sensitive attributes
- Status filtering (include/exclude inactive users)
- Pagination support with customizable limits

list_users

Lists users from Okta with optional filtering and pagination:

Supports SCIM filter expressions (e.g., 'profile.firstName eq "John"')
Free-form text search across multiple fields
Sorting options (by status, creation date, etc.)
Pagination support with customizable limits

activate_user

Activates a user in Okta:

Option to send activation email
Updates user status to active

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:

Filter expressions for groups (e.g., 'type eq "OKTA_GROUP"')
Free-form text search across group fields
Sorting options (by name, type, etc.)
Pagination support with customizable limits

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)

Note: The onboarding automation tools are experimental and may be subject to changes or limitations based on Okta's API constraints. Use with caution in production environments.

bulk_user_import

Imports multiple users from a CSV string:

Creates user accounts based on CSV data
Optional activation of users
Optional email notifications
Assignment to default groups

assign_users_to_groups

Assigns multiple users to groups based on attribute mappings:

Maps user attributes (department, title, etc.) to specific groups
Bulk assignment of users based on attributes

provision_applications

Provisions application access for multiple users:

Assigns users to applications
Supports bulk provisioning

run_onboarding_workflow

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

User import from CSV
Automatic activation
Group assignment based on attributes
Application provisioning
Welcome email configuration

Example Usage in Claude

After setup, you can use commands like:

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'"
"What's the status of user [email protected]"
"When was the last login for user [email protected]"
"Find users created in the last month"
"Activate user with ID XXXX"
"Suspend user with ID XXXX"
"Delete deactivated user with ID XXXX"
"Where did user XXXX last log in from?"

Advanced User Searches

"Find all users in the Sales department" → Uses find_users_by_attribute with department eq "Sales"
"Show me users whose email starts with 'admin'" → Uses email sw "admin"
"Find users with any manager assigned" → Uses manager pr
"List users whose last name contains 'smith'" → Uses lastName co "smith"

Group Management

"Show me all groups in my Okta organization"
"List groups containing the word 'admin'"
"Create a new group called 'Marketing Team'"
"Get details for group with ID XXXX"
"Delete group with ID XXXX"
"Add user XXXX to group YYYY"
"Remove user XXXX from 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"
"Provision application access for these 5 users"
"Run a complete onboarding workflow for these new hires: [CSV content]"

Error Handling

The server includes robust error handling for:

User or group not found (404 errors)
API authentication issues
Missing or invalid user profiles
General API errors
CSV parsing issues
User attribute mapping failures
Application provisioning errors
Unsupported search operators (automatic fallback to alternative methods)

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

Server Connection Issues:

Check if the server built successfully
Verify file permissions on build/index.js (should be 755)
Try running the server directly: node /path/to/build/index.js

Search Issues:

Some search operators are not supported for all attributes (e.g., contains doesn't work for department)
The server automatically falls back to alternative search methods when needed
Check the response message for which search method was used

Viewing Logs

To view server 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

Environment Variables

If you're getting environment variable errors, verify:

OKTA_ORG_URL: Should be complete URL (e.g., "https://dev-123456.okta.com")
OKTA_API_TOKEN: Should be a valid API token

Security Considerations

Keep your API token secure
Don't commit credentials to version control
Use environment variables for sensitive data
Regularly rotate API tokens
Monitor API usage in Okta Admin Console
Implement rate limiting for API calls
Use minimum required permissions for API token
PII masking is enabled for sensitive search parameters

Search Operator Compatibility

Different Okta attributes support different search operators:

Attribute Type	eq	sw	ew	co	pr
firstName, lastName	✅	✅	✅	✅	✅
email, login	✅	✅	✅	✅	✅
department, title	✅	✅	❌	❌*	✅
division, organization	✅	✅	❌	❌*	✅
All attributes	✅	✅	⚠️	⚠️	✅

*❌ = Not supported, ⚠️ = May not be supported for all attributes

Note: When an operator is not supported, the server automatically falls back to client-side filtering for compatibility.

Types

The server includes TypeScript interfaces for Okta user and group data:

interface OktaUserProfile {
  login: string;
  email: string;
  secondEmail?: string;
  firstName: string;
  lastName: string;
  displayName: string;
  nickName?: string;
  organization: string;
  title: string;
  division: string;
  department: string;
  employeeNumber: string;
  userType: string;
  costCenter: string;
  mobilePhone?: string;
  primaryPhone?: string;
  streetAddress: string;
  city: string;
  state: string;
  zipCode: string;
  countryCode: string;
  preferredLanguage: string;
  profileUrl?: string;
}

interface OktaUser {
  id: string;
  status: string;
  created: string;
  activated: string;
  lastLogin: string;
  lastUpdated: string;
  statusChanged: string;
  passwordChanged: string;
  profile: OktaUserProfile;
}

interface OktaGroup {
  id: string;
  created: string;
  lastUpdated: string;
  lastMembershipUpdated: string;
  type: string;
  objectClass: string[];
  profile: {
    name: string;
    description: string;
  };
}

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

License

MIT License - See LICENSE file for details.

Support

If you encounter any issues:

Check the troubleshooting section above
Review Claude Desktop logs
Examine the server's error output
Check Okta's developer documentation

Note: PRs welcome!

Okta

Okta MCP Server

Prerequisites

Setup Instructions

1. Create an Okta Developer Account

2. Create an API Token

3. Initial Project Setup

4. Configure Claude Desktop

Available Tools

User Management

get_user

find_users_by_attribute

list_users

activate_user

suspend_user

unsuspend_user

delete_user

get_user_last_location

Group Management

list_groups

create_group

get_group

delete_group

assign_user_to_group

remove_user_from_group

list_group_users

Onboarding Automation (Experimental)

bulk_user_import

assign_users_to_groups

provision_applications

run_onboarding_workflow

Example Usage in Claude

User Management

Advanced User Searches

Group Management

Onboarding Automation

Error Handling

Troubleshooting

Common Issues

Viewing Logs

Environment Variables

Security Considerations

Search Operator Compatibility

Types

CSV Format for Onboarding

License

Support

Be the First to Experience MCP Now