Okta MCP Server

MCP (Model Context Protocol) is an open protocol introduced by Anthropic that standardizes how large language models communicate with external tools, resources or remote services.

The Okta MCP Server integrates with LLMs and AI agents, allowing you to perform various Okta management operations using natural language. For instance, you could simply ask Claude Desktop to perform Okta management operations:

• Create a new user and add them to the Engineering group

• Show me all failed login attempts from the last 24 hours

• List all applications that haven't been used in the past month

Empower your LLM Agents to Manage your Okta Organization

This server is an Model Context Protocol server that provides seamless integration with Okta's Admin Management APIs. It allows LLM agents to interact with Okta in a programmatic way, enabling automation and enhanced management capabilities.

Key Features

• LLM-Driven Okta Management: Allows your LLM agents to perform administrative tasks within your Okta environment based on natural language instructions.
• Secure Authentication: Supports both Device Authorization Grant for interactive use and Private Key JWT for secure, automated server-to-server communication.
• Interactive Confirmation via Elicitation: Destructive operations (deletes, deactivations) prompt the user for confirmation through the MCP Elicitation API before proceeding, with automatic fallback for clients that do not yet support the feature.
• Integration with Okta Admin Management APIs: Leverages the official Okta APIs to ensure secure and reliable interaction with your Okta org.
• Extensible Architecture: Designed to be easily extended with new functionalities and support for additional Okta API endpoints.
• Comprehensive Tool Support: Full CRUD operations for users, groups, applications, policies, device assurance policies, brands, themes, custom pages, email templates, custom domains, email domains, and more.
• Scope-Based Tool Loading: Tools are automatically enabled or disabled at server startup based on the OAuth 2.0 scopes configured in OKTA_SCOPES. Only tools for which your application has been granted the required scope are registered and visible to the LLM — tools without a matching scope are silently removed before the first request.

This MCP server utilizes Okta's Python SDK v3.4.1 to communicate with the Okta APIs, ensuring a robust and well-supported integration.

🚀 Getting Started

Prerequisites:

• Python 3.8+ OR Docker
• uv package manager (if not using Docker)
• Claude Desktop or any other MCP Client
• Okta account with appropriate permissions

Install the Okta MCP Server

Install Okta MCP Server and configure it to work with your preferred MCP Client.

Choose one of the following installation methods:

Docker provides a consistent environment without needing to install Python or uv locally.

1. Clone the repository:

   bashCopy code
   git clone https://github.com/okta/okta-mcp-server.git
   cd okta-mcp-server
   

2. Create a .env file from the example:

   bashCopy code
   cp .env.example .env
   # Edit .env and add your Okta credentials
   

3. Build and run with Docker Compose:

   bashCopy code
   docker-compose up -d
   

4. Configure your MCP Client to use the Docker container:

Claude Desktop with Docker (Private Key JWT - Recommended for Docker):

This method requires no browser interaction and is ideal for containerized environments.

jsonCopy code
{
  "mcpServers": {
    "okta-mcp-server": {
      "command": "docker",
      "args": [
        "run", "-i", "--rm",
        "-e", "OKTA_ORG_URL",
        "-e", "OKTA_CLIENT_ID",
        "-e", "OKTA_SCOPES",
        "-e", "OKTA_PRIVATE_KEY",
        "-e", "OKTA_KEY_ID",
        "okta-mcp-server"
      ],
      "env": {
        "OKTA_ORG_URL": "https://your-org.okta.com",
        "OKTA_CLIENT_ID": "your-client-id",
        "OKTA_SCOPES": "okta.users.read okta.groups.read",
        "OKTA_PRIVATE_KEY": "-----BEGIN RSA PRIVATE KEY-----\nYour private key content here\n-----END RSA PRIVATE KEY-----",
        "OKTA_KEY_ID": "your-key-id"
      }
    }
  }
}

Claude Desktop with Docker (Device Authorization Grant):

This method requires browser-based authentication. When the server starts, it will display an authentication URL in the logs. Copy and paste this URL into your browser to complete the authentication.

Note: Docker containers cannot open a browser on the host automatically. You must manually copy the URL from docker logs okta-mcp-server and paste it into your browser.

jsonCopy code
{
  "mcpServers": {
    "okta-mcp-server": {
      "command": "docker",
      "args": [
        "run", "-i", "--rm",
        "-v", "okta-keyring:/home/appuser/.local/share/python_keyring",
        "-e", "OKTA_ORG_URL",
        "-e", "OKTA_CLIENT_ID",
        "-e", "OKTA_SCOPES",
        "-e", "PYTHON_KEYRING_BACKEND=keyrings.alt.file.PlaintextKeyring",
        "okta-mcp-server"
      ],
      "env": {
        "OKTA_ORG_URL": "https://your-org.okta.com",
        "OKTA_CLIENT_ID": "your-client-id",
        "OKTA_SCOPES": "okta.users.read okta.groups.read"
      }
    }
  }
}

The -v okta-keyring:/home/appuser/.local/share/python_keyring volume persists tokens between container restarts.

VS Code with Docker (Private Key JWT - Recommended for Docker):

jsonCopy code
{
  "mcp": {
    "inputs": [
      {
        "type": "promptString",
        "description": "Okta Organization URL (e.g., https://dev-123456.okta.com)",
        "id": "OKTA_ORG_URL"
      },
      {
        "type": "promptString",
        "description": "Okta Client ID",
        "id": "OKTA_CLIENT_ID",
        "password": true
      },
      {
        "type": "promptString",
        "description": "Okta Scopes (separated by whitespace)",
        "id": "OKTA_SCOPES"
      },
      {
        "type": "promptString",
        "description": "Okta Private Key (for browserless auth)",
        "id": "OKTA_PRIVATE_KEY",
        "password": true
      },
      {
        "type": "promptString",
        "description": "Okta Key ID (for browserless auth)",
        "id": "OKTA_KEY_ID",
        "password": true
      }
    ],
    "servers": {
      "okta-mcp-server": {
        "command": "docker",
        "args": [
          "run", "-i", "--rm",
          "-e", "OKTA_ORG_URL=${input:OKTA_ORG_URL}",
          "-e", "OKTA_CLIENT_ID=${input:OKTA_CLIENT_ID}",
          "-e", "OKTA_SCOPES=${input:OKTA_SCOPES}",
          "-e", "OKTA_PRIVATE_KEY=${input:OKTA_PRIVATE_KEY}",
          "-e", "OKTA_KEY_ID=${input:OKTA_KEY_ID}",
          "okta-mcp-server"
        ]
      }
    }
  }
}

VS Code with Docker (Device Authorization Grant):

Note: Device Authorization requires manual browser interaction. When the server starts, check the MCP output panel for the authentication URL, then copy and paste it into your browser.

jsonCopy code
{
  "mcp": {
    "inputs": [
      {
        "type": "promptString",
        "description": "Okta Organization URL (e.g., https://dev-123456.okta.com)",
        "id": "OKTA_ORG_URL"
      },
      {
        "type": "promptString",
        "description": "Okta Client ID",
        "id": "OKTA_CLIENT_ID",
        "password": true
      },
      {
        "type": "promptString",
        "description": "Okta Scopes (separated by whitespace)",
        "id": "OKTA_SCOPES"
      }
    ],
    "servers": {
      "okta-mcp-server": {
        "command": "docker",
        "args": [
          "run", "-i", "--rm",
          "-v", "okta-keyring:/home/appuser/.local/share/python_keyring",
          "-e", "OKTA_ORG_URL=${input:OKTA_ORG_URL}",
          "-e", "OKTA_CLIENT_ID=${input:OKTA_CLIENT_ID}",
          "-e", "OKTA_SCOPES=${input:OKTA_SCOPES}",
          "-e", "PYTHON_KEYRING_BACKEND=keyrings.alt.file.PlaintextKeyring",
          "okta-mcp-server"
        ]
      }
    }
  }
}

Alternatively, use docker-compose (requires .env file):

jsonCopy code
{
  "mcp": {
    "servers": {
      "okta-mcp-server": {
        "command": "docker-compose",
        "args": [
          "-f",
          "/path/to/okta-mcp-server/docker-compose.yml",
          "run",
          "--rm",
          "okta-mcp-server"
        ]
      }
    }
  }
}

Alternatively, build and run directly:

bashCopy code
# Build the image
docker build -t okta-mcp-server .

# Run the container
docker run -i --rm \
  -e OKTA_ORG_URL="<OKTA_ORG_URL>" \
  -e OKTA_CLIENT_ID="<OKTA_CLIENT_ID>" \
  -e OKTA_SCOPES="<OKTA_SCOPES>" \
  okta-mcp-server

1. Clone and install the server:

   bashCopy code
   git clone https://github.com/okta/okta-mcp-server.git
   cd okta-mcp-server
   uv sync
   

2. Configure Claude Desktop by adding the following to your claude_desktop_config.json:

   jsonCopy code
   {
     "mcpServers": {
       "okta-mcp-server": {
         "command": "uv",
         "args": [
           "run",
           "--directory",
           "/path/to/okta-mcp-server",
           "okta-mcp-server"
         ],
         "env": {
           "OKTA_ORG_URL": "<OKTA_ORG_URL>",
           "OKTA_CLIENT_ID": "<OKTA_CLIENT_ID>",
           "OKTA_SCOPES": "<OKTA_SCOPES>",
           "OKTA_PRIVATE_KEY": "<PRIVATE_KEY_IF_NEEDED>",
           "OKTA_KEY_ID": "<KEY_ID_IF_NEEDED>"
         }
       }
     }
   }
   

Configure with Different MCP Clients

Add the following to your VS Code settings.json:

jsonCopy code
{
  "mcp": {
    "inputs": [
      {
        "type": "promptString",
        "description": "Okta Organization URL (e.g., https://dev-123456.okta.com)",
        "id": "OKTA_ORG_URL"
      },
      {
        "type": "promptString",
        "description": "Okta Client ID",
        "id": "OKTA_CLIENT_ID",
        "password": true
      },
      {
        "type": "promptString",
        "description": "Okta Scopes (separated by whitespace, e.g., 'okta.users.read okta.groups.manage')",
        "id": "OKTA_SCOPES"
      },
      {
        "type": "promptString",
        "description": "Okta Private Key. Required for 'browserless' auth.",
        "id": "OKTA_PRIVATE_KEY",
        "password": true
      },
      {
        "type": "promptString",
        "description": "Okta Key ID (KID) for the private key. Required for 'browserless' auth.",
        "id": "OKTA_KEY_ID",
        "password": true
      }
    ],
    "servers": {
      "okta-mcp-server": {
        "command": "uv",
        "args": [
          "run",
          "--directory",
          "/path/to/the/okta-mcp-server",
          "okta-mcp-server"
        ],
        "env": {
          "OKTA_ORG_URL": "${input:OKTA_ORG_URL}",
          "OKTA_CLIENT_ID": "${input:OKTA_CLIENT_ID}",
          "OKTA_SCOPES": "${input:OKTA_SCOPES}",
          "OKTA_PRIVATE_KEY": "${input:OKTA_PRIVATE_KEY}",
          "OKTA_KEY_ID": "${input:OKTA_KEY_ID}"
        }
      }
    }
  }
}

To use Okta MCP Server with any other MCP Client, you can manually add this configuration to the client and restart for changes to take effect:

jsonCopy code
{
  "mcpServers": {
    "okta-mcp-server": {
      "command": "uv",
      "args": [
        "run",
        "--directory",
        "/path/to/okta-mcp-server",
        "okta-mcp-server"
      ],
      "env": {
        "OKTA_ORG_URL": "<OKTA_ORG_URL>",
        "OKTA_CLIENT_ID": "<OKTA_CLIENT_ID>",
        "OKTA_SCOPES": "<OKTA_SCOPES>",
        "OKTA_PRIVATE_KEY": "<PRIVATE_KEY_IF_NEEDED>",
        "OKTA_KEY_ID": "<KEY_ID_IF_NEEDED>"
      }
    }
  }
}

Authenticate with Okta

The server supports two authentication methods. Choose the one that best fits your use case.

Method 1: Device Authorization Grant (Interactive)

1. In your Okta org, create a new App Integration.
2. Select OIDC - OpenID Connect and Native Application.
3. Under Grant type, ensure Device Authorization is checked.
4. Go to the Okta API Scopes tab and Grant permissions for the APIs you need (e.g., okta.users.read, okta.groups.manage).
5. Save the application and copy the Client ID.
6. Documentation: Okta Device Authorization Grant Guide

Method 2: Private Key JWT (Browserless)

1. Create App: In your Okta org, create a new App Integration. Select API Services. Save the app and copy the Client ID.
2. Configure Client Authentication:
   • On the app's General tab, find the Client Credentials section and click Edit.
   • Disable Require Demonstrating Proof of Possession (DPoP) header in token requests.
   • Select Public key / Private key for the authentication method.
3. Add a Public Key: You have two options for adding a key.
   • Option A: Generate Key in Okta (Recommended)
     1. In the Public keys section, click Add key.
     2. In the dialog, choose Generate new key.
     3. Okta will instantly generate a key pair. Download or save the private key (private.pem) and store it securely.
     4. Copy the Key ID (KID) displayed for the newly generated key.
   • Option B: Use Your Own Key
     1. Generate a key pair locally using the following openssl commands:

        bashCopy code
        # Generate a 2048-bit RSA private key
        openssl genpkey -algorithm RSA -out private.pem -pkeyopt rsa_keygen_bits:2048
        
        # Extract the public key from the private key
        openssl rsa -in private.pem -pubout -out public.pem
        

     2. Click Add key and paste the contents of your public key (public.pem) into the dialog.
     3. Copy the Key ID (KID) displayed for the key you added.
4. Grant API Scopes: Go to the Okta API Scopes tab and Grant permissions for the APIs you need.
5. Assign Admin Roles: Go to the Admin roles tab and assign the appropriate admin role to this application.

Verify your integration

Restart your MCP Client (Claude Desktop, VS Code, etc.) and ask it to help you manage your Okta tenant:

Show me the users in my Okta organization

🛠️ Supported Tools

The Okta MCP Server provides the following tools for LLMs to interact with your Okta tenant:

Users

Required scope: okta.users.read (read) · okta.users.manage (write)

Groups

Required scope: okta.groups.read (read) · okta.groups.manage (write)

Applications

Required scope: okta.apps.read (read) · okta.apps.manage (write)

Policies

Required scope: okta.policies.read (read) · okta.policies.manage (write)

Device Assurance Policies

Required scope: okta.deviceAssurance.read (read) · okta.deviceAssurance.manage (write)

Logs

Required scope: okta.logs.read

Brands

Required scope: okta.brands.read (read) · okta.brands.manage (write)

Themes

Required scope: okta.brands.read (read) · okta.brands.manage (write)

Custom Pages

Required scope: okta.brands.read (read) · okta.brands.manage (write)

Email Templates & Customizations

Required scope: okta.templates.read (read) · okta.templates.manage (write)

Custom Domains

Required scope: okta.domains.read (read) · okta.domains.manage (write)

Email Domains

Required scope: okta.emailDomains.read (read) · okta.emailDomains.manage (write)

Confirmation for Destructive Operations

All destructive operations (deleting groups, applications, policies, policy rules, device assurance policies, and deactivating/deleting users) use the MCP Elicitation API to prompt the user for explicit confirmation before proceeding.

• Clients that support elicitation (e.g., Claude Desktop with MCP SDK ≥ 1.26): The user sees a confirmation dialog directly in the chat UI. They can accept, decline, or cancel.
• Clients that do not yet support elicitation: The tool returns a JSON payload describing the pending action so the LLM can relay the confirmation request to the user. The deprecated confirm_delete_group / confirm_delete_application tools remain available as a fallback for these clients.

� Scope-Based Tool Loading

The Okta MCP Server uses a scope-based tool loading mechanism to ensure that only the tools your application is authorized to use are exposed to the LLM.

How it works

1. At startup, after authentication completes, the server reads the scopes listed in your OKTA_SCOPES environment variable.
2. Every tool in the server is mapped to a minimum required OAuth 2.0 scope (e.g. okta.users.read, okta.brands.manage). This mapping is defined in scope_registry.py.
3. The server compares each tool's required scope against your configured scopes. Tools whose required scope is not present are silently removed from the tool registry — they will never appear in tools/list and the LLM will not be aware of them.
4. At runtime, a @require_scopes decorator on each tool provides a second layer of enforcement: if a scope is missing at call time (e.g. token was refreshed with fewer scopes), the tool returns a clear error message instead of making an API call.

Scope → Tool mapping

What you need to do

To enable a group of tools, you must do two things:

1. Grant the scope to your Okta application

In your Okta Admin Console, open the App Integration you created for the MCP server:

• Go to the Okta API Scopes tab.
• Click Grant next to each scope you want to enable.

2. Add the scope to OKTA_SCOPES in your MCP client configuration

Update the OKTA_SCOPES value in your mcp.json / settings.json to include the required scopes as a space-separated string:

jsonCopy code
"OKTA_SCOPES": "okta.users.read okta.groups.read okta.brands.read okta.templates.read"

Then restart your MCP client so the server picks up the new scope list.

[!TIP] Start with the minimum set of scopes your use-case requires. For example, if you only need to read users and brands, use okta.users.read okta.brands.read. Adding okta.*.manage scopes enables write operations — only grant those if needed.

[!NOTE] Scopes follow the pattern okta.<resource>.read for read-only access and okta.<resource>.manage for full read+write access. You do not need both — okta.users.manage implicitly enables all read operations on users.

�🔐 Authentication

The Okta MCP Server uses the Okta Management API and requires authentication to access your Okta tenant.

Authentication Flow

The server uses OAuth 2.0 device authorization flow for secure authentication with Okta, or Private Key JWT for browserless authentication. Your credentials are managed securely and are never exposed in plain text.

Initial Setup

The MCP Server will automatically initiate the appropriate authentication flow based on your configuration:

• Device Authorization Grant: Interactive browser-based authentication
• Private Key JWT: Browserless authentication using client credentials

[!NOTE] Device authorization flow is not supported for private cloud tenants. Private Cloud users should use Private Key JWT authentication with client credentials.

[!IMPORTANT] Using the MCP Server will consume Management API rate limits according to your subscription plan. Refer to the Rate Limit Policy for more information.

🩺 Troubleshooting

When encountering issues with the Okta MCP Server, several troubleshooting options are available to help diagnose and resolve problems.

🐞 Debug Mode

Enable debug mode for more detailed logging:

bashCopy code
export OKTA_LOG_LEVEL=DEBUG

[!TIP] Debug mode is particularly useful when troubleshooting connection or authentication issues.

🚨 Common Issues

1. Authentication Failures

   • Ensure you have the correct permissions in your Okta tenant
   • Verify your OKTA_ORG_URL, OKTA_CLIENT_ID, and OKTA_SCOPES are correct
   • Check that your application has the necessary API scopes granted

2. MCP Client Can't Connect to the Server

   • Restart your MCP client after installation
   • Verify the server path is correct in your configuration
   • Check that uv is installed and accessible in your PATH

3. API Errors or Permission Issues

   • Enable debug mode with export OKTA_LOG_LEVEL=DEBUG
   • Verify your Okta application has the required scopes
   • Ensure your application has appropriate admin roles assigned
   • Check the Okta System Log for detailed error information

4. Docker: "No recommended backend was available" (Keyring Error)

   • Docker containers don't have a system keyring. Set the environment variable:

     bashCopy code
     -e PYTHON_KEYRING_BACKEND=keyrings.alt.file.PlaintextKeyring
     

   • Use a volume to persist tokens: -v okta-keyring:/home/appuser/.local/share/python_keyring
   • Alternatively, use Private Key JWT authentication which doesn't require keyring storage

5. Docker: "Invalid code" when using Device Authorization

   • The MCP client may restart the server, generating a new device code
   • Copy the URL immediately from the logs and complete authentication quickly
   • Consider using Private Key JWT authentication for Docker environments
   • Use a persistent volume to cache tokens and avoid repeated authentication

6. "Claude's response was interrupted..." Error

   • This typically happens when Claude hits its context-length limit
   • Try to be more specific and keep queries concise
   • Break large requests into smaller, focused operations

[!TIP] Most connection issues can be resolved by restarting both the server and your MCP client.

📋 Debug Logs

Enable debug mode to view detailed logs:

bashCopy code
export OKTA_LOG_LEVEL=DEBUG

You can also specify a log file:

bashCopy code
export OKTA_LOG_FILE="/path/to/okta-mcp.log"

👨‍💻 Development

Building from Source

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

# Install dependencies
uv sync

# Run the server directly
uv run okta-mcp-server

Development Scripts

bashCopy code
# Run with debug logs enabled
OKTA_LOG_LEVEL=DEBUG uv run okta-mcp-server

# Run tests
uv run pytest

# Install in development mode
uv pip install -e .

[!NOTE] This server requires Python 3.8 or higher and uv.

🔒 Security

The Okta MCP Server prioritizes security:

• Credentials are managed through secure authentication flows
• No sensitive information is stored in plain text
• Authentication uses OAuth 2.0 device authorization flow or Private Key JWT
• Supports fine-grained API scope permissions
• Easy credential management through environment variables

[!IMPORTANT] For security best practices, always review the permissions requested during the authentication process to ensure they align with your security requirements.

[!CAUTION] Always use the principle of least privilege when granting API scopes to your Okta application.

🧪 Security Scanning

We recommend regularly scanning this server, and any other MCP-compatible servers you deploy, with community tools built to surface protocol-level risks and misconfigurations.

These scanners help identify issues across key vulnerability classes including: server implementation bugs, tool definition and lifecycle risks, interaction and data flow weaknesses, and configuration or environment gaps.

If you discover a vulnerability, please follow our responsible disclosure process.

💬 Feedback and Contributing

We appreciate feedback and contributions to this project! Before you get started, please see:

• Okta's general contribution guidelines

Reporting Issues

To provide feedback or report a bug, please raise an issue on our issue tracker.

Vulnerability Reporting

Please do not report security vulnerabilities on the public GitHub issue tracker. Please follow the responsible disclosure process.

📄 License

This project is licensed under the Apache 2.0 license. See the LICENSE file for more info.

What is Okta?

Copyright © 2025-Present, Okta, Inc.

Licensed under the Apache License, Version 2.0 (the "License"); you may not use this file except in compliance with the License. You may obtain a copy of the License at http://www.apache.org/licenses/LICENSE-2.0. Unless required by applicable law or agreed to in writing, software distributed under the License is distributed on an "AS IS" BASIS, WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied. See the License for the specific language governing permissions and limitations under the License.