# Okta MCP Server

A TypeScript Model Context Protocol server that exposes Okta incident-support and administrative workflows to MCP-compatible IDE clients over stdio.

## Capabilities

- Read org metadata.
- Investigate user incidents with one summary tool.
- List and inspect users, groups, app assignments, MFA factors, sessions, policies, IdPs, network zones, and System Log events.
- Query focused user System Log events by actor, event type, and outcome.
- Optionally expose write/remediation tools for lifecycle, group membership, session clearing, password expiry, and MFA reset.

## Requirements

- Node.js 20 or newer.
- An Okta org URL such as `https://example.okta.com`.
- An Okta API token with the least privileges needed for the tools you plan to use.

## Setup

```bash
npm install
cp .env.example .env
npm run build
```

Set these environment variables before launching the server:

```bash
export OKTA_ORG_URL="https://your-org.okta.com"
export OKTA_API_TOKEN="your-okta-api-token"
export OKTA_REQUEST_TIMEOUT_MS="30000"
export OKTA_ENABLE_WRITE_TOOLS="false"
```

`OKTA_ENABLE_WRITE_TOOLS` defaults to false. Keep it false for read-only support triage. Set it to `true` only for trusted remediation sessions where your MCP host has explicit tool-call approval.

## Run

For local development:

```bash
npm run dev
```

For the local React support console:

```bash
npm run build
export OKTA_ORG_URL="https://your-org.okta.com"
export OKTA_API_TOKEN="your-okta-api-token"
export OKTA_ENABLE_WRITE_TOOLS="false"
npm run ui
```

Open `http://127.0.0.1:5173`. The React app talks to a local HTTP bridge on port `4174`, and the bridge talks to this MCP server over stdio.

For an MCP client, use the built entrypoint:

```json
{
  "mcpServers": {
    "okta": {
      "command": "node",
      "args": ["/absolute/path/to/Okta MCP Server/dist/index.js"],
      "env": {
        "OKTA_ORG_URL": "https://your-org.okta.com",
        "OKTA_API_TOKEN": "your-okta-api-token"
      }
    }
  }
}
```

## Tools

| Tool | Purpose |
| --- | --- |
| `okta_get_org_info` | Read organization metadata. |
| `okta_get_user_incident_summary` | Gather profile, groups, factors, sessions, app links, and recent logs for a user. |
| `okta_list_users` | List users with `q`, `search`, `filter`, `limit`, and `after`. |
| `okta_get_user` | Read one user by ID, login, or shortname. |
| `okta_list_user_groups` | List groups assigned to a user. |
| `okta_list_user_factors` | List enrolled MFA factors for a user. |
| `okta_get_user_factor` | Read one enrolled MFA factor. |
| `okta_list_user_sessions` | List active sessions for a user. |
| `okta_list_user_app_links` | List app links visible to a user. |
| `okta_list_groups` | List groups with `q`, `search`, `filter`, `limit`, and `after`. |
| `okta_get_group` | Read one group. |
| `okta_list_group_users` | List users assigned to a group. |
| `okta_list_applications` | List applications. |
| `okta_get_application` | Read one application. |
| `okta_list_application_users` | List users assigned to an application. |
| `okta_get_application_user` | Read one app assignment for a user. |
| `okta_list_policies` | List Okta policies for access and sign-on troubleshooting. |
| `okta_get_policy` | Read one policy. |
| `okta_list_policy_rules` | List policy rules. |
| `okta_list_identity_providers` | List identity providers. |
| `okta_get_identity_provider` | Read one identity provider. |
| `okta_list_network_zones` | List network zones. |
| `okta_list_system_logs` | Query System Log events. |
| `okta_search_user_system_logs` | Search user-related System Log events by login, email, or user ID. |

These remediation tools are registered only when `OKTA_ENABLE_WRITE_TOOLS=true`:

| Tool | Purpose |
| --- | --- |
| `okta_create_user` | Create a user with a supplied profile, credentials, and optional groups. |
| `okta_update_user` | Update a user's profile or credentials. |
| `okta_deactivate_user` | Deactivate a user. |
| `okta_unlock_user` | Unlock a locked user. |
| `okta_suspend_user` | Suspend a user. |
| `okta_unsuspend_user` | Unsuspend a user. |
| `okta_expire_user_password` | Expire a password and optionally issue a temporary password. |
| `okta_reset_user_factor` | Reset a user's MFA factor. |
| `okta_clear_user_sessions` | Clear user sessions and optionally revoke OAuth tokens. |
| `okta_create_group` | Create a group. |
| `okta_add_user_to_group` | Add a user to a group. |
| `okta_remove_user_from_group` | Remove a user from a group. |

## Incident Workflows

Common support prompts from an MCP client IDE:

- "Use Okta to summarize the incident context for user jane@example.com since 2026-07-06T12:00:00Z."
- "Check whether this user has active sessions, enrolled factors, and recent MFA failures."
- "Find failed sign-in or app access events for jane@example.com in the last two hours."
- "Compare the user's assigned groups with the failing application's assignments."
- "List sign-on and MFA policies that may affect this app or user."

## Security Notes

- Use a scoped Okta admin/API token and rotate it regularly.
- Store `OKTA_API_TOKEN` in your MCP host's secret storage when available.
- Leave `OKTA_ENABLE_WRITE_TOOLS=false` for normal incident triage.
- Treat lifecycle, MFA reset, session clearing, and membership tools as privileged operations.
- Review MCP host approvals before allowing write operations.

See [Architecture](docs/ARCHITECTURE.md) for component design, data flow, and extension guidance. See [Using Okta MCP from Claude or VS Code](docs/IDE_SUPPORT_USAGE.md) for natural-language support workflows.