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

Related MCP server: Okta MCP Server

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 john.doe@company.com"

• "When was the last login for user jane.smith@organization.com"

• "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:

*❌ = 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,john.doe@example.com,Engineering,Senior Developer,+1-555-123-4567
Jane,Smith,jane.smith@example.com,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!