# okta/okta-mcp-server architecture

> Architecture diagram of the GitHub repository okta/okta-mcp-server, generated by GitDiagram from its file tree, README and a sample of source files (last updated 2026-10-01). It is an AI-made overview: check details against the source.

- Interactive diagram: https://gitdiagram.com/okta/okta-mcp-server
- Repository: https://github.com/okta/okta-mcp-server

## Overview

This is an MCP server that lets an LLM client manage an Okta organization through natural-language requests. The main path is client request → scope-filtered MCP tool → authenticated Okta SDK call → response serialization. Domain tools cover identity, access controls, device assurance, customization, and audit logs. The README documents additional CRUD capabilities and two authentication modes; unsampled tool implementations are represented by their exact source paths, while edges are limited to relationships shown by the README or SOURCE INDEX.

Main entry points: [`src/okta_mcp_server/server.py`](https://github.com/okta/okta-mcp-server/blob/main/src/okta_mcp_server/server.py) (MCP Server), [`src/okta_mcp_server/utils/client.py`](https://github.com/okta/okta-mcp-server/blob/main/src/okta_mcp_server/utils/client.py) (Okta SDK Client), [`src/okta_mcp_server/tools/users/users.py`](https://github.com/okta/okta-mcp-server/blob/main/src/okta_mcp_server/tools/users/users.py) (User Management), [`src/okta_mcp_server/tools/groups/groups.py`](https://github.com/okta/okta-mcp-server/blob/main/src/okta_mcp_server/tools/groups/groups.py) (Group Management)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_runtime["MCP Runtime"]
  node_server["MCP Server<br/>[server.py]"]
end

subgraph group_identity["Identity Management"]
  node_users["User Management<br/>[users.py]"]
  node_groups["Group Management<br/>[groups.py]"]
  node_user_resources["User Resources<br/>[user_resources.py]"]
  node_applications["Application Management<br/>[applications.py]"]
end

subgraph group_security["Access and Audit"]
  node_policies["Policy Management<br/>[policies.py]"]
  node_device_assurance["Device Assurance"]
  node_system_logs["System Logs<br/>[system_logs.py]"]
  node_login_failures["Login Failure Queries<br/>[login_failures.py]"]
end

subgraph group_custom["Org Customization"]
  node_brands_domains["Brands and Domains"]
  node_custom_pages["Custom Pages<br/>[custom_pages.py]"]
  node_custom_templates["Custom Templates"]
  node_themes["Themes<br/>[themes.py]"]
end

subgraph group_shared["Shared Services"]
  node_scope["Scope Filtering<br/>[scope_guard.py]"]
  node_auth["Authentication<br/>[auth_manager.py]"]
  node_okta_client["Okta SDK Client<br/>[client.py]"]
  node_serialization["JSON Responses<br/>[serialization.py]"]
  node_pagination["Pagination<br/>[pagination.py]"]
  node_validation["Input Validation<br/>[validation.py]"]
  node_elicitation["Destructive-Action Confirmation<br/>[elicitation.py]"]
  node_messages["Confirmation Messages<br/>[messages.py]"]
end

node_client_actor(("MCP Client / Agent"))
node_okta_api["Okta APIs"]

node_client_actor -->|"sends requests"| node_server
node_server -->|"initializes authentication"| node_auth
node_server -->|"filters tools"| node_scope
node_server -->|"registers tools"| node_users
node_server -->|"registers tools"| node_groups
node_server -->|"registers tools"| node_applications
node_server -->|"registers tools"| node_policies
node_server -->|"registers tools"| node_device_assurance
node_server -->|"registers tools"| node_system_logs
node_server -->|"registers tools"| node_login_failures
node_server -->|"registers tools"| node_brands_domains
node_server -->|"registers tools"| node_custom_pages
node_server -->|"registers tools"| node_custom_templates
node_server -->|"registers tools"| node_themes
node_auth -->|"provides credentials"| node_okta_client
node_okta_client -->|"calls"| node_okta_api
node_users -->|"requests client"| node_okta_client
node_groups -->|"requests client"| node_okta_client
node_applications -->|"requests client"| node_okta_client
node_device_assurance -->|"requests client"| node_okta_client
node_server -->|"configures responses"| node_serialization
node_users -->|"uses pagination"| node_pagination
node_groups -->|"uses pagination"| node_pagination
node_custom_templates -->|"uses pagination"| node_pagination
node_users -->|"confirms destructive actions"| node_elicitation
node_groups -->|"confirms destructive actions"| node_elicitation
node_applications -->|"confirms destructive actions"| node_elicitation
node_elicitation -->|"uses prompts"| node_messages
node_device_assurance -->|"validates policy data"| node_validation
node_client_actor -->|"receives responses"| node_server

click node_server "https://github.com/okta/okta-mcp-server/blob/main/src/okta_mcp_server/server.py"
click node_scope "https://github.com/okta/okta-mcp-server/blob/main/src/okta_mcp_server/utils/scope_guard.py"
click node_auth "https://github.com/okta/okta-mcp-server/blob/main/src/okta_mcp_server/utils/auth/auth_manager.py"
click node_okta_client "https://github.com/okta/okta-mcp-server/blob/main/src/okta_mcp_server/utils/client.py"
click node_serialization "https://github.com/okta/okta-mcp-server/blob/main/src/okta_mcp_server/utils/serialization.py"
click node_pagination "https://github.com/okta/okta-mcp-server/blob/main/src/okta_mcp_server/utils/pagination.py"
click node_validation "https://github.com/okta/okta-mcp-server/blob/main/src/okta_mcp_server/utils/validation.py"
click node_elicitation "https://github.com/okta/okta-mcp-server/blob/main/src/okta_mcp_server/utils/elicitation.py"
click node_messages "https://github.com/okta/okta-mcp-server/blob/main/src/okta_mcp_server/utils/messages.py"
click node_users "https://github.com/okta/okta-mcp-server/blob/main/src/okta_mcp_server/tools/users/users.py"
click node_groups "https://github.com/okta/okta-mcp-server/blob/main/src/okta_mcp_server/tools/groups/groups.py"
click node_user_resources "https://github.com/okta/okta-mcp-server/blob/main/src/okta_mcp_server/tools/user_resources/user_resources.py"
click node_applications "https://github.com/okta/okta-mcp-server/blob/main/src/okta_mcp_server/tools/applications/applications.py"
click node_policies "https://github.com/okta/okta-mcp-server/blob/main/src/okta_mcp_server/tools/policies/policies.py"
click node_device_assurance "https://github.com/okta/okta-mcp-server/blob/main/src/okta_mcp_server/tools/device_assurance/device_assurance.py"
click node_system_logs "https://github.com/okta/okta-mcp-server/blob/main/src/okta_mcp_server/tools/system_logs/system_logs.py"
click node_login_failures "https://github.com/okta/okta-mcp-server/blob/main/src/okta_mcp_server/tools/system_logs/login_failures.py"
click node_brands_domains "https://github.com/okta/okta-mcp-server/tree/main/src/okta_mcp_server/tools/customization"
click node_custom_pages "https://github.com/okta/okta-mcp-server/blob/main/src/okta_mcp_server/tools/customization/custom_pages/custom_pages.py"
click node_custom_templates "https://github.com/okta/okta-mcp-server/blob/main/src/okta_mcp_server/tools/customization/custom_templates/custom_templates.py"
click node_themes "https://github.com/okta/okta-mcp-server/blob/main/src/okta_mcp_server/tools/customization/themes/themes.py"

classDef toneNeutral fill:#f8fafc,stroke:#334155,stroke-width:1.5px,color:#0f172a
classDef toneBlue fill:#dbeafe,stroke:#2563eb,stroke-width:1.5px,color:#172554
classDef toneAmber fill:#fef3c7,stroke:#d97706,stroke-width:1.5px,color:#78350f
classDef toneMint fill:#dcfce7,stroke:#16a34a,stroke-width:1.5px,color:#14532d
classDef toneRose fill:#ffe4e6,stroke:#e11d48,stroke-width:1.5px,color:#881337
classDef toneIndigo fill:#e0e7ff,stroke:#4f46e5,stroke-width:1.5px,color:#312e81
classDef toneTeal fill:#ccfbf1,stroke:#0f766e,stroke-width:1.5px,color:#134e4a
class node_server,node_client_actor toneBlue
class node_users,node_groups,node_user_resources,node_applications toneAmber
class node_policies,node_device_assurance,node_system_logs,node_login_failures,node_okta_api toneMint
class node_brands_domains,node_custom_pages,node_custom_templates,node_themes toneRose
class node_scope,node_auth,node_okta_client,node_serialization,node_pagination,node_validation,node_elicitation,node_messages toneIndigo
```

## Components

### MCP Runtime

- [MCP Server](https://github.com/okta/okta-mcp-server/blob/main/src/okta_mcp_server/server.py): `src/okta_mcp_server/server.py`

### Identity Management

- [User Management](https://github.com/okta/okta-mcp-server/blob/main/src/okta_mcp_server/tools/users/users.py): `src/okta_mcp_server/tools/users/users.py`
- [Group Management](https://github.com/okta/okta-mcp-server/blob/main/src/okta_mcp_server/tools/groups/groups.py): `src/okta_mcp_server/tools/groups/groups.py`
- [User Resources](https://github.com/okta/okta-mcp-server/blob/main/src/okta_mcp_server/tools/user_resources/user_resources.py): `src/okta_mcp_server/tools/user_resources/user_resources.py`
- [Application Management](https://github.com/okta/okta-mcp-server/blob/main/src/okta_mcp_server/tools/applications/applications.py): `src/okta_mcp_server/tools/applications/applications.py`

### Access and Audit

- [Policy Management](https://github.com/okta/okta-mcp-server/blob/main/src/okta_mcp_server/tools/policies/policies.py): `src/okta_mcp_server/tools/policies/policies.py`
- [Device Assurance](https://github.com/okta/okta-mcp-server/blob/main/src/okta_mcp_server/tools/device_assurance/device_assurance.py): `src/okta_mcp_server/tools/device_assurance/device_assurance.py`
- [System Logs](https://github.com/okta/okta-mcp-server/blob/main/src/okta_mcp_server/tools/system_logs/system_logs.py): `src/okta_mcp_server/tools/system_logs/system_logs.py`
- [Login Failure Queries](https://github.com/okta/okta-mcp-server/blob/main/src/okta_mcp_server/tools/system_logs/login_failures.py): `src/okta_mcp_server/tools/system_logs/login_failures.py`

### Org Customization

- [Brands and Domains](https://github.com/okta/okta-mcp-server/tree/main/src/okta_mcp_server/tools/customization): `src/okta_mcp_server/tools/customization`
- [Custom Pages](https://github.com/okta/okta-mcp-server/blob/main/src/okta_mcp_server/tools/customization/custom_pages/custom_pages.py): `src/okta_mcp_server/tools/customization/custom_pages/custom_pages.py`
- [Custom Templates](https://github.com/okta/okta-mcp-server/blob/main/src/okta_mcp_server/tools/customization/custom_templates/custom_templates.py): `src/okta_mcp_server/tools/customization/custom_templates/custom_templates.py`
- [Themes](https://github.com/okta/okta-mcp-server/blob/main/src/okta_mcp_server/tools/customization/themes/themes.py): `src/okta_mcp_server/tools/customization/themes/themes.py`

### Shared Services

- [Scope Filtering](https://github.com/okta/okta-mcp-server/blob/main/src/okta_mcp_server/utils/scope_guard.py): `src/okta_mcp_server/utils/scope_guard.py`
- [Authentication](https://github.com/okta/okta-mcp-server/blob/main/src/okta_mcp_server/utils/auth/auth_manager.py): `src/okta_mcp_server/utils/auth/auth_manager.py`
- [Okta SDK Client](https://github.com/okta/okta-mcp-server/blob/main/src/okta_mcp_server/utils/client.py): `src/okta_mcp_server/utils/client.py`
- [JSON Responses](https://github.com/okta/okta-mcp-server/blob/main/src/okta_mcp_server/utils/serialization.py): `src/okta_mcp_server/utils/serialization.py`
- [Pagination](https://github.com/okta/okta-mcp-server/blob/main/src/okta_mcp_server/utils/pagination.py): `src/okta_mcp_server/utils/pagination.py`
- [Input Validation](https://github.com/okta/okta-mcp-server/blob/main/src/okta_mcp_server/utils/validation.py): `src/okta_mcp_server/utils/validation.py`
- [Destructive-Action Confirmation](https://github.com/okta/okta-mcp-server/blob/main/src/okta_mcp_server/utils/elicitation.py): `src/okta_mcp_server/utils/elicitation.py`
- [Confirmation Messages](https://github.com/okta/okta-mcp-server/blob/main/src/okta_mcp_server/utils/messages.py): `src/okta_mcp_server/utils/messages.py`

### Other components

- **MCP Client / Agent**
- **Okta APIs**

## Connections

- MCP Client / Agent → MCP Server: sends requests (evidence: `README.md`)
- MCP Server → Authentication: initializes authentication (evidence: `src/okta_mcp_server/server.py`)
- MCP Server → Scope Filtering: filters tools (evidence: `src/okta_mcp_server/server.py`)
- MCP Server → User Management: registers tools (evidence: `src/okta_mcp_server/server.py`)
- MCP Server → Group Management: registers tools (evidence: `src/okta_mcp_server/server.py`)
- MCP Server → Application Management: registers tools (evidence: `src/okta_mcp_server/server.py`)
- MCP Server → Policy Management: registers tools (evidence: `src/okta_mcp_server/server.py`)
- MCP Server → Device Assurance: registers tools (evidence: `src/okta_mcp_server/server.py`)
- MCP Server → System Logs: registers tools (evidence: `src/okta_mcp_server/server.py`)
- MCP Server → Login Failure Queries: registers tools (evidence: `src/okta_mcp_server/server.py`)
- MCP Server → Brands and Domains: registers tools (evidence: `src/okta_mcp_server/server.py`)
- MCP Server → Custom Pages: registers tools (evidence: `src/okta_mcp_server/server.py`)
- MCP Server → Custom Templates: registers tools (evidence: `src/okta_mcp_server/server.py`)
- MCP Server → Themes: registers tools (evidence: `src/okta_mcp_server/server.py`)
- Authentication → Okta SDK Client: provides credentials (evidence: `src/okta_mcp_server/utils/client.py`)
- Okta SDK Client → Okta APIs: calls (evidence: `README.md`)
- User Management → Okta SDK Client: requests client (evidence: `src/okta_mcp_server/tools/users/users.py`)
- Group Management → Okta SDK Client: requests client (evidence: `src/okta_mcp_server/tools/groups/groups.py`)
- Application Management → Okta SDK Client: requests client (evidence: `src/okta_mcp_server/tools/applications/applications.py`)
- Device Assurance → Okta SDK Client: requests client (evidence: `src/okta_mcp_server/tools/device_assurance/device_assurance.py`)
- MCP Server → JSON Responses: configures responses (evidence: `src/okta_mcp_server/server.py`)
- User Management → Pagination: uses pagination (evidence: `src/okta_mcp_server/tools/users/users.py`)
- Group Management → Pagination: uses pagination (evidence: `src/okta_mcp_server/tools/groups/groups.py`)
- Custom Templates → Pagination: uses pagination (evidence: `src/okta_mcp_server/tools/customization/custom_templates/custom_templates.py`)
- User Management → Destructive-Action Confirmation: confirms destructive actions (evidence: `src/okta_mcp_server/tools/users/users.py`)
- Group Management → Destructive-Action Confirmation: confirms destructive actions (evidence: `src/okta_mcp_server/tools/groups/groups.py`)
- Application Management → Destructive-Action Confirmation: confirms destructive actions (evidence: `src/okta_mcp_server/tools/applications/applications.py`)
- Destructive-Action Confirmation → Confirmation Messages: uses prompts (evidence: `src/okta_mcp_server/tools/groups/groups.py`)
- Device Assurance → Input Validation: validates policy data (evidence: `src/okta_mcp_server/tools/device_assurance/device_assurance.py`)
- MCP Client / Agent → MCP Server: receives responses (evidence: `README.md`)
