Okta MCP Server

Model Context Protocol (MCP) server for Okta API operations. Provides identity and access management capabilities to LLMs through a standardized interface.

⚠️ CRITICAL PRODUCTION SAFETY WARNING

🚨 USE WITH EXTREME CAUTION IN PRODUCTION ENVIRONMENTS 🚨

This MCP server provides FULL ADMINISTRATIVE ACCESS to your Okta organization, including the ability to:

• CREATE, MODIFY, AND DELETE USERS (including administrators)
• MODIFY GROUP MEMBERSHIPS (including security groups)
• CREATE AND MODIFY APPLICATIONS (including SSO configurations)
• CHANGE SECURITY POLICIES (including MFA and password policies)
• PERFORM BULK OPERATIONS (affecting thousands of users at once)

🔒 STRONGLY RECOMMENDED: Use Read-Only Mode in Production

For production environments, always enable read-only mode:

# Claude Code (RECOMMENDED for production)
claude mcp add okta npx okta-mcp-server \
  -e OKTA_DOMAIN=your-domain.okta.com \
  -e OKTA_API_TOKEN=your-api-token \
  -e READ_ONLY_MODE=true

// Claude Desktop (RECOMMENDED for production)
{
  "mcpServers": {
    "okta": {
      "command": "npx",
      "args": ["okta-mcp-server"],
      "env": {
        "OKTA_DOMAIN": "your-domain.okta.com",
        "OKTA_API_TOKEN": "your-api-token",
        "READ_ONLY_MODE": "true"
      }
    }
  }
}

Read-only mode blocks all write operations while allowing:

• ✅ User and group queries
• ✅ Application and policy inspection
• ✅ Audit log analysis
• ✅ Data exports and reporting
• ✅ Compliance reporting

🛡️ Production Safety Guidelines

1. Use read-only mode by default - Only disable for specific, controlled operations
2. Limit API token permissions - Use principle of least privilege
3. Monitor all operations - Review audit logs regularly
4. Test in development first - Never run untested operations in production
5. Have rollback procedures - Know how to quickly reverse changes
6. Use version control - Track all configuration changes

🚫 NOT RECOMMENDED for Production (Without Read-Only Mode)

Direct write access in production can lead to:

• Accidental user lockouts (including your own)
• Unintended security policy changes
• Mass user modifications or deletions
• Application configuration corruption
• Compliance violations

Features

Core Capabilities

• User Management: Create, read, update, delete, and search users with advanced filtering
• Group Management: Full group lifecycle management including member operations
• Application Management: Manage SAML, OIDC, and other application integrations
• Policy Management: Configure and manage authentication, authorization, and MFA policies
• Bulk Operations: Process thousands of users efficiently with CSV/JSON import/export
• Audit Logging: Comprehensive audit trail with compliance reporting (SOC2, HIPAA, GDPR)

Technical Features

• Simple Configuration: Just provide your Okta domain and API token
• High Performance: Memory/SQLite caching and optimized pagination
• Rate Limiting: Automatic rate limiting to comply with Okta API limits
• Error Handling: Comprehensive error handling with detailed error messages
• Type Safety: Full TypeScript implementation with strict typing
• Streaming Support: Async generators for handling large datasets

Installation

npm install -g okta-mcp-server

Quick Start

Option 1: Claude Code (Recommended)

Production Setup (Read-Only Mode - RECOMMENDED)

1. Get an Okta API token from your Okta admin console
2. Add the MCP server with read-only mode for safety:

claude mcp add okta npx okta-mcp-server \
  -e OKTA_DOMAIN=your-domain.okta.com \
  -e OKTA_API_TOKEN=your-api-token \
  -e READ_ONLY_MODE=true

Development Setup (Full Access)

For development/testing environments only:

claude mcp add okta npx okta-mcp-server \
  -e OKTA_DOMAIN=your-domain.okta.com \
  -e OKTA_API_TOKEN=your-api-token

3. You're done! The server is now available in Claude Code.

Option 2: Claude Desktop

Production Setup (Read-Only Mode - RECOMMENDED)

1. Get an Okta API token from your Okta admin console
2. Configure Claude Desktop with read-only mode:

{
  "mcpServers": {
    "okta": {
      "command": "npx",
      "args": ["okta-mcp-server"],
      "env": {
        "OKTA_DOMAIN": "your-domain.okta.com",
        "OKTA_API_TOKEN": "your-api-token",
        "READ_ONLY_MODE": "true"
      }
    }
  }
}

Development Setup (Full Access)

For development/testing environments only:

{
  "mcpServers": {
    "okta": {
      "command": "npx",
      "args": ["okta-mcp-server"],
      "env": {
        "OKTA_DOMAIN": "your-domain.okta.com",
        "OKTA_API_TOKEN": "your-api-token"
      }
    }
  }
}

3. Restart Claude Desktop - you're done!

Quick Start Examples

Try these commands immediately after setup:

"Show me my Okta domain statistics"
"List the first 10 users in my organization"
"What groups exist in my Okta instance?"
"Show me users who logged in today"
"Find inactive users from the last 30 days"

Verify Read-Only Mode (Production Safety Check)

"What is the current read-only mode status?"
"Show me which operations are allowed and blocked"

If read-only mode is enabled, you'll see a clear message about which operations are available.

Option 3: OAuth Protection (Advanced)

Claude Code with OAuth

# Add server with OAuth protection
claude mcp add okta npx okta-mcp-server \
  -e OKTA_DOMAIN=your-domain.okta.com \
  -e OKTA_API_TOKEN=your-api-token \
  -e MCP_AUTH_REQUIRED=true \
  -e MCP_AUTH_AUDIENCE=https://okta-mcp-server \
  -e MCP_AUTH_ISSUER=https://auth.example.com

Claude Desktop with OAuth

Protect your MCP server with OAuth so Claude must authenticate before using it:

{
  "mcpServers": {
    "okta": {
      "command": "npx",
      "args": ["okta-mcp-server"],
      "env": {
        "OKTA_DOMAIN": "your-domain.okta.com",
        "OKTA_API_TOKEN": "your-api-token",
        "MCP_AUTH_REQUIRED": "true",
        "MCP_AUTH_AUDIENCE": "https://okta-mcp-server",
        "MCP_AUTH_ISSUER": "https://auth.example.com"
      },
      "oauth": {
        "authorization_url": "https://auth.example.com/authorize",
        "token_url": "https://auth.example.com/oauth/token",
        "client_id": "your-oauth-client-id",
        "scopes": ["read:okta", "write:okta"]
      }
    }
  }
}

Environment Variables

Required

| Variable | Description | |----------|-------------| | OKTA_DOMAIN | Your Okta domain (e.g., your-domain.okta.com) | | OKTA_API_TOKEN | Your Okta API token |

Production Safety (STRONGLY RECOMMENDED)

| Variable | Description | Default | |----------|-------------|---------| | READ_ONLY_MODE | Enable read-only mode to prevent write operations | false |

Optional - MCP OAuth Protection

| Variable | Description | Default | |----------|-------------|---------| | MCP_AUTH_REQUIRED | Enable OAuth protection for MCP server | false | | MCP_AUTH_AUDIENCE | Expected audience in JWT tokens | - | | MCP_AUTH_ISSUER | Expected issuer of JWT tokens | - |

Optional - Performance

| Variable | Description | Default | |----------|-------------|---------| | CACHE_ENABLED | Enable caching | true | | CACHE_TYPE | Cache type (memory or sqlite) | memory | | CACHE_TTL | Cache TTL in seconds | 300 | | CACHE_MAX_SIZE | Maximum cache entries | 1000 |

Optional - Other

| Variable | Description | Default | |----------|-------------|---------| | LOG_LEVEL | Logging level (debug, info, warn, error) | info | | USE_MOCK_OKTA | Use mock Okta client for testing | false |

Claude Code Specific Features

MCP Resource References

Use @ mentions to reference MCP resources directly:

@okta://users?status=ACTIVE  # Reference active users
@okta://groups               # Reference all groups  
@okta://audit-logs?since=2024-01-01  # Reference recent audit logs

Slash Commands

If your server provides MCP prompts, use them as slash commands:

/okta-security-audit        # Run security audit prompt
/okta-user-cleanup         # Run user cleanup prompt

Server Management

# Check server status
/mcp

# Add server with different scopes
claude mcp add okta npx okta-mcp-server --scope project  # Share with team
claude mcp add okta npx okta-mcp-server --scope user     # Available across projects

# Remove server
claude mcp remove okta

Example Usage in Claude Code

Once you've added the Okta MCP server, here are some powerful things you can ask Claude to do:

🔍 User Discovery & Analysis

"Show me all users who haven't logged in for 90 days"
"Find users without MFA enabled and create a report"
"List all admin users and their last activity"
"Which users have access to our production apps?"
"Find duplicate user accounts by email domain"

👥 User Management Automation

"Create 50 test users for our QA environment with usernames like qa-user-001"
"Disable all users who haven't logged in since January"
"Add all users from the Engineering department to the GitHub-Users group"
"Reset passwords for all users in the compromised-users.csv file"
"Update all user profiles to include their department from this CSV"

🛡️ Security & Compliance

"Generate a SOC2 compliance report for user access changes this month"
"Show me all privileged access grants in the last 7 days"
"Find all users with admin roles and verify they have MFA"
"Create an audit report of all user deletions this quarter"
"Which service accounts have excessive permissions?"

📊 Bulk Operations

"Export all users to a CSV with their group memberships"
"Import these 500 new employees from this CSV file and assign to onboarding group"
"Migrate all users from @oldcompany.com to @newcompany.com email addresses"
"Bulk update user departments based on this mapping file"
"Remove all users in the contractors group who haven't logged in for 30 days"

🔧 Application & Policy Management

"Show me all SAML applications and their user counts"
"Which applications have the most inactive users?"
"Create a new password policy requiring 12 characters and MFA"
"List all policies that don't enforce MFA"
"Find applications without any assigned users"

📈 Analytics & Reporting

"Create a dashboard of user growth over the last 6 months"
"Show me login patterns by hour of day and day of week"
"Which departments have the highest MFA adoption?"
"Generate a report of all API tokens and their last usage"
"Analyze group membership overlap between Engineering and DevOps"

🚨 Incident Response

"Immediately disable all users who logged in from these suspicious IPs"
"Find and suspend all accounts created in the last hour"
"List all users who had password resets today"
"Show me all admin actions performed by [email protected]"
"Revoke all sessions for users in the security-incident group"

🤖 Automation Workflows

"Every Friday, send me a report of users added this week"
"Create a cleanup list of users to be deactivated next month"
"Set up monitoring for any new admin role assignments"
"Generate onboarding tasks for all users created today"
"Check for users with conflicting group memberships"

Available Tools

User Management

• listUsers - List users with pagination and filtering
• getUser - Get a single user by ID or login
• createUser - Create a new user
• updateUser - Update user profile
• deleteUser - Deactivate or delete a user
• getUserGroups - Get groups for a user

Group Management

• listGroups - List groups with pagination
• getGroup - Get a single group
• createGroup - Create a new group
• updateGroup - Update group profile
• deleteGroup - Delete a group
• listGroupMembers - List members of a group
• addGroupMember - Add user to group
• removeGroupMember - Remove user from group

Application Management

• listApps - List applications
• getApp - Get application details
• createApp - Create new application
• updateApp - Update application
• deleteApp - Delete application
• assignUserToApp - Assign user to app
• assignGroupToApp - Assign group to app

Policy Management

• listPolicies - List policies by type
• getPolicy - Get policy details
• createPasswordPolicy - Create password policy
• createSignOnPolicy - Create sign-on policy
• createMfaPolicy - Create MFA policy
• updatePolicy - Update policy
• deletePolicy - Delete policy

Bulk Operations

• bulkCreateUsers - Create multiple users from CSV/JSON
• bulkUpdateUsers - Update multiple users
• bulkDeleteUsers - Delete multiple users
• exportUsers - Export users to CSV/JSON

Audit & Compliance

• queryAuditLogs - Query audit logs with filters
• getAuditStatistics - Get audit statistics
• exportAuditLogs - Export audit logs
• generateComplianceReport - Generate compliance reports

System Management

• getReadOnlyStatus - Check read-only mode status and show allowed/blocked operations

Example Usage in Claude

Human: List all active users in Okta

Assistant: I'll help you list all active users in your Okta organization. Let me query the Okta API for you.

[Uses listUsers tool with filter "status eq \"ACTIVE\""]

I found 247 active users in your Okta organization. Here's a summary of the first few users:

1. **John Smith** ([email protected])
   - Department: Engineering
   - Created: 2024-01-15
   - Last login: 2024-03-20

2. **Jane Doe** ([email protected])
   - Department: Sales
   - Created: 2024-02-01
   - Last login: 2024-03-19

[... more users ...]

Would you like me to:
- Export the full list to CSV?
- Filter by a specific department?
- Show users who haven't logged in recently?

Security

• API tokens are never exposed in logs or error messages
• All sensitive data is automatically masked in audit logs
• Supports encryption for cached data
• Rate limiting prevents API abuse
• Circuit breaker pattern for reliability

Troubleshooting

Common Issues

1. "OKTA_API_TOKEN must be provided"

   • Ensure you've set the OKTA_API_TOKEN environment variable
   • Check that your API token has the necessary permissions

2. "Invalid domain"

   • Use just the domain part: your-domain.okta.com (not https://your-domain.okta.com)

3. Rate limiting errors

   • The server automatically handles rate limits with exponential backoff
   • For bulk operations, consider using the batch endpoints

Development

# Clone the repository
git clone https://github.com/yourusername/okta-mcp-server.git
cd okta-mcp-server

# Install dependencies
npm install

# Build
npm run build

# Run tests
npm test

# Run in development mode
npm run dev

Migration from v1.x

Version 2.0 is a major simplification:

1. Removed OAuth client implementation - The server no longer tries to authenticate TO Okta using OAuth
2. Simplified to API token only - Just provide your Okta API token
3. Optional MCP OAuth protection - Let Claude handle the OAuth flow if you want to protect your MCP server
4. Removed unnecessary dependencies - Smaller, faster, more reliable

Migration Steps

For Claude Code Users

1. Remove the old server: claude mcp remove okta
2. Update to v2.0: npm update -g okta-mcp-server
3. Re-add with simplified config:

   claude mcp add okta npx okta-mcp-server \
     -e OKTA_DOMAIN=your-domain.okta.com \
     -e OKTA_API_TOKEN=your-api-token

For Claude Desktop Users

1. Update to v2.0: npm update okta-mcp-server
2. Simplify your configuration to just OKTA_DOMAIN and OKTA_API_TOKEN
3. Remove any OAuth client configuration (CLIENT_ID, CLIENT_SECRET, etc.)
4. Restart Claude Desktop

Contributing

Contributions are welcome! Please read our Contributing Guide for details.

License

Apache-2.0 - see LICENSE for details.