Which integrations are available for this server?

Provides tools for authenticating with Okta, managing sessions, and retrieving cookies for AI agents.

How do I use okta-auth?

1. Click on "Deploy Server". 2. Wait a few minutes for the server to deploy. Once ready, it will show a "Started" state. 3. In the chat, type @ followed by the MCP server name and your instructions, e.g., "@okta-auth check my Okta session status" That's it! The server will respond to your query, and you can continue using it as needed. Here is a step-by-step guide with screenshots.

okta-auth

by bunizao

Overview Schema Source Related Servers Discussions Admin

Python

Local

okta-auth

Alpha: this project is under active development. APIs, tool signatures, and session formats may change between releases.

okta-auth is an Okta login toolkit with two entry points:

okta: interactive CLI for humans
okta-auth: MCP server for AI agents that reuse saved sessions

Sessions are stored under ~/.okta-auth/sessions/. Existing sessions under ~/.okta-auth-mcp/sessions/ are migrated automatically.

Install

uv tool

uv tool install okta-auth-cli

pipx

pipx install okta-auth-cli

pip

pip install okta-auth-cli

Browser setup

The project uses Playwright for browser automation. It automatically prefers a local Chrome or Edge install when available.

If no supported system browser is found, install Playwright Chromium:

playwright install chromium

Related MCP server: Agent Identity MCP Server

Upgrade

uv tool: uv tool upgrade okta-auth-cli
pipx: pipx upgrade okta-auth-cli
pip: pip install -U okta-auth-cli

Quick Start

1. Configure credentials

Run the built-in wizard:

okta config

If the wizard asks for a TOTP secret and you are not sure where to find it, see TOTP Secret.

The wizard supports two providers:

keyring: store credentials in the OS credential manager
op: generate ~/.okta-auth/op.env with op://... references for op run

Only non-secret settings such as the default URL and provider metadata are stored in ~/.okta-auth/config.json.

2. Log in

okta

Or pass a target URL directly:

okta https://portal.company.com

The login flow is headless by default. Use --headed to show the browser.

3. Reuse the session from MCP

Once configured, AI agents can authenticate with the saved session or with the credential provider you configured.

TOTP Secret

The TOTP secret is the Base32 key behind your authenticator app. You typically must capture it during initial MFA enrollment.

During Okta MFA setup

Go to Settings -> Security Methods in Okta.
Choose Google Authenticator or another TOTP-compatible factor.
On the QR screen, click Can't scan?
Copy the displayed Base32 secret.
Complete enrollment by entering the generated code.

This project does not currently support portals that rely only on the Okta Verify push app for MFA.

If you already enrolled and lost the secret

You usually need to remove and re-enroll the authenticator factor to get a new secret.

Credential Setup

Credential resolution order is:

Explicit CLI or MCP arguments
Environment variables
Stored keyring credentials when the selected provider is keyring

Recommended: OS keyring

This is the default and recommended local setup:

okta config --provider keyring

What gets stored:

username, password, totp_secret: OS keyring only
default_url: ~/.okta-auth/config.json

Typical keyring backends:

macOS: Keychain Access
Windows: Credential Manager / Credential Locker
Linux: Secret Service or KWallet

If no secure backend is available, the wizard refuses to fall back to plaintext.

1Password CLI

If you already manage secrets in 1Password:

okta config --provider op

What gets stored:

vault, item, field names, default_url: ~/.okta-auth/config.json
OKTA_USERNAME, OKTA_PASSWORD, optional OKTA_TOTP_SECRET references: ~/.okta-auth/op.env

The generated env file contains op://... references, not plaintext values.

Launch the CLI or MCP server through op run:

op run --env-file=$HOME/.okta-auth/op.env -- okta
op run --env-file=$HOME/.okta-auth/op.env -- uvx --from okta-auth-cli okta-auth

1Password vault, item, and field names must be compatible with secret reference paths. If a name contains unsupported separators such as /, use the object's unique ID instead.

Environment variables

Environment variables are still supported for CI, ephemeral shells, or external secret managers. They override okta config values.

export OKTA_USERNAME="you@company.com"
export OKTA_PASSWORD="your-okta-password"
export OKTA_TOTP_SECRET="JBSWY3DPEHPK3PXP"

Manual 1Password setup

If you do not want to use the wizard, you can set up op run manually.

Create a login item:

op item create --category login --title "Okta MCP" \
  username="you@company.com" \
  password="your-okta-password" \
  totp_secret="JBSWY3DPEHPK3PXP"

Create ~/.okta-auth/op.env:

OKTA_USERNAME=op://Personal/Okta MCP/username
OKTA_PASSWORD=op://Personal/Okta MCP/password
OKTA_TOTP_SECRET=op://Personal/Okta MCP/totp_secret

Launch through op run:

op run --env-file=$HOME/.okta-auth/op.env -- uvx --from okta-auth-cli okta-auth

CLI

Common commands

okta [url]: log in and save a session
okta config: open the credential wizard
okta config --provider keyring: force keyring configuration
okta config --provider op: force 1Password configuration
okta config --show: show current config status
okta config --reset: remove saved config and credentials
okta check <url>: verify a stored session
okta list: list stored sessions
okta delete <url>: delete a stored session
okta cookies <url>: inspect stored cookies

Example

okta https://portal.company.com --username you@company.com --headed

MCP Server

MCP tools

Tool	Description
`okta_login`	Authenticate to a target URL and store session state
`okta_check_session`	Verify whether a stored session is still valid
`okta_list_sessions`	List saved sessions and metadata
`okta_delete_session`	Remove a stored session
`okta_get_cookies`	Retrieve cookies from a stored session

Claude Code

claude mcp add okta-auth -- uvx --from okta-auth-cli okta-auth

If you use 1Password:

claude mcp add okta-auth -- op run --env-file=$HOME/.okta-auth/op.env -- uvx --from okta-auth-cli okta-auth

Claude Desktop / Cursor / Windsurf

Default:

{
  "mcpServers": {
    "okta-auth": {
      "command": "uvx",
      "args": ["--from", "okta-auth-cli", "okta-auth"]
    }
  }
}

With 1Password:

{
  "mcpServers": {
    "okta-auth": {
      "command": "op",
      "args": ["run", "--env-file=/Users/yourname/.okta-auth/op.env", "--", "uvx", "--from", "okta-auth-cli", "okta-auth"]
    }
  }
}

Use okta for the interactive CLI. Use okta-auth only when wiring the package into an MCP client.

Security

This project is intended for local trusted execution.
Session files and cookies are sensitive credentials.
Prefer okta config over passing credentials directly on the command line.
Prefer keyring or op run over plaintext shell files.
Never post cookie values, passwords, or TOTP secrets in issues or logs.

Development

uv venv && source .venv/bin/activate
uv pip install -e '.[dev]'
playwright install chromium

Run checks locally:

ruff format --check .
ruff check .
pytest

Available Tools

5 tools

okta_check_sessionA

Read-onlyIdempotent

Verify if a stored session for a URL is still valid.

Launches a headless browser with the stored session cookies, navigates to the URL, and checks whether the session is still authenticated (not redirected to Okta login).

Args: url: URL to verify session against. Must match the URL used during login. timeout_ms: Maximum time in ms to wait for page load (5000-120000, default 30000).

Returns: JSON: {"valid": bool, "domain_key": str|null, "message": str, "url": str}

ParametersJSON Schema

Name	Required	Description	Default
`url`	Yes
`timeout_ms`	No

Output Schema

ParametersJSON Schema

Name	Required	Description
`result`	Yes

TDQS

A4.3/5.0

Behavior4/5

Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?

Provides specific behavioral details beyond annotations: launches headless browser, uses cookies, checks for redirect. Annotations already indicate safe read operation; description enriches with mechanism.

Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.

Conciseness5/5

Is the description appropriately sized, front-loaded, and free of redundancy?

Concise yet comprehensive: states purpose, explains mechanism, lists arguments with details, specifies return format. No superfluous content.

Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.

Completeness4/5

Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?

Covers purpose, mechanism, parameters, and return format. Annotations provide safety profile. Could mention prerequisites (must have stored session from login) but implied. Good completeness for its complexity.

Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.

Parameters5/5

Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?

Both parameters described with constraints and usage context. URL: must match login URL; timeout: range and default. Schema had no descriptions, so description fully compensates.

Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.

Purpose5/5

Does the description clearly state what the tool does and how it differs from similar tools?

States clear action: verify session validity for a URL. Distinguishes from sibling tools like login, list, delete, get cookies by focusing on validation. Includes specific method (headless browser, checking for redirect).

Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.

Usage Guidelines3/5

Does the description explain when to use this tool, when not to, or what alternatives exist?

Implies usage after login to verify session, but does not explicitly state when to use this tool over alternatives like okta_list_sessions. No exclusions or when-not guidance provided.

Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.

okta_delete_sessionA

DestructiveIdempotent

Delete a stored session for a given URL.

Removes the session file and metadata from ~/.okta-auth/sessions/. The agent will need to re-authenticate to access the service again.

Args: url: URL whose stored session should be deleted.

Returns: JSON: {"deleted": bool, "message": str, "url": str}

ParametersJSON Schema

Name	Required	Description	Default
`url`	Yes

Output Schema

ParametersJSON Schema

Name	Required	Description
`result`	Yes

TDQS

A4.5/5.0

Behavior4/5

Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?

Annotations already indicate destructiveHint=true. The description adds valuable context beyond annotations: it specifies that the tool removes 'the session file and metadata from ~/.okta-auth/sessions/' and that re-authentication is required. No contradictions with annotations.

Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.

Conciseness5/5

Is the description appropriately sized, front-loaded, and free of redundancy?

The description is extremely concise: a single-sentence summary followed by a brief explanation and structured Args/Returns. It is front-loaded with the main action and every sentence adds value without waste.

Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.

Completeness5/5

Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?

Given the tool's simplicity (one required parameter, no enums, output schema exists) and the richness of annotations, the description covers all necessary information: what it does, what happens (file removal, re-auth needed), and the return format. No gaps.

Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.

Parameters4/5

Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?

The input schema has 0% description coverage for the single parameter 'url'. The description adds meaning: 'URL whose stored session should be deleted,' clarifying the parameter's purpose beyond its name.

Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.

Purpose5/5

Does the description clearly state what the tool does and how it differs from similar tools?

The description clearly states 'Delete a stored session for a given URL,' specifying the verb (delete) and resource (stored session). This distinguishes it from sibling tools like okta_check_session, okta_login, okta_list_sessions, and okta_get_cookies.

Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.

Usage Guidelines4/5

Does the description explain when to use this tool, when not to, or what alternatives exist?

The description explains the consequence of use: 'The agent will need to re-authenticate to access the service again,' providing clear context for when this tool is appropriate. It does not explicitly mention when not to use or list alternatives, but the context is sufficient.

Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.

okta_get_cookiesA

Read-onlyIdempotent

Retrieve cookies from a stored session.

Returns the raw cookie data from a stored Playwright session. Useful for making authenticated HTTP requests without launching a browser.

Args: url: URL whose stored session cookies to retrieve. domain_filter: Optional domain substring to filter cookies (e.g., 'okta.com').

Returns: JSON: {"count": int, "cookies": [{name, value, domain, path, ...}], "url": str} Error: {"error": str, "url": str}

ParametersJSON Schema

Name	Required	Description	Default
`url`	Yes
`domain_filter`	No

Output Schema

ParametersJSON Schema

Name	Required	Description
`result`	Yes

TDQS

A4.6/5.0

Behavior4/5

Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?

Annotations already indicate read-only, idempotent, non-destructive behavior. The description adds context about returning raw cookie data from a Playwright session, and specifies the return format including error handling.

Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.

Conciseness5/5

Is the description appropriately sized, front-loaded, and free of redundancy?

The description is concise and well-structured: a one-line summary, usage context, and clearly separated Args and Returns sections. No wasted sentences.

Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.

Completeness5/5

Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?

The description covers purpose, usage, parameter details, return format, and error responses. Given the tool's simplicity (2 params, output schema present), it provides complete guidance for an agent.

Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.

Parameters5/5

Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?

Despite 0% schema description coverage, the description's Args section fully explains both parameters: url (the URL whose cookies to retrieve) and domain_filter (optional substring filter), providing clear semantics.

Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.

Purpose5/5

Does the description clearly state what the tool does and how it differs from similar tools?

The description clearly states 'Retrieve cookies from a stored session.' It uses a specific verb and resource, and the tool's purpose is distinct from siblings like okta_check_session or okta_login.

Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.

Usage Guidelines4/5

Does the description explain when to use this tool, when not to, or what alternatives exist?

The description provides a use case ('making authenticated HTTP requests without launching a browser') and explains the tool's utility, but does not explicitly contrast with siblings or state when not to use it.

Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.

okta_list_sessionsA

Read-onlyIdempotent

List all stored authentication sessions.

Returns metadata for every saved session including the domain, when it was saved, and cookie/origin counts. Does NOT verify if sessions are still valid — use okta_check_session for that.

Returns: JSON: {"count": int, "sessions": [{url, domain_key, saved_at_iso, cookie_count, origin_count}]}

ParametersJSON Schema

Name	Required	Description	Default
No parameters

Output Schema

ParametersJSON Schema

Name	Required	Description
`result`	Yes

TDQS

A4.4/5.0

Behavior4/5

Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?

Annotations already declare readOnlyHint=true and destructiveHint=false. The description adds valuable behavioral context beyond annotations, notably that the tool does NOT verify session validity. This helps the agent understand a key limitation.

Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.

Conciseness5/5

Is the description appropriately sized, front-loaded, and free of redundancy?

The description is highly concise: two short paragraphs and a return format example. It front-loads the purpose, explains the limitation in one sentence, and provides the output format. Every sentence provides necessary information without repetition.

Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.

Completeness4/5

Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?

Given no parameters and an output schema described inline, the description covers the tool's behavior, return format, and limitation about session validity. It does not mention error handling or rate limits, but for a simple read-only list tool with good annotations, it is sufficiently complete.

Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.

Parameters4/5

Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?

The tool has no parameters, so the input schema fully covers them (100% coverage). The description is not required to add parameter details, achieving the baseline of 4 for zero-parameter tools.

Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.

Purpose5/5

Does the description clearly state what the tool does and how it differs from similar tools?

The description clearly states 'List all stored authentication sessions' with a specific verb and resource. It distinguishes from sibling tools by explicitly stating it does NOT verify session validity and directs users to okta_check_session for that purpose.

Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.

Usage Guidelines4/5

Does the description explain when to use this tool, when not to, or what alternatives exist?

The description provides a clear context for when to use the tool (listing all sessions) and an explicit alternative for verification (okta_check_session). It does not cover when to use versus other siblings like okta_login or okta_delete_session, but the purpose is distinct enough.

Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.

okta_loginA

Idempotent

Authenticate to a website via Okta SSO and persist the session.

Launches a headless browser, navigates to the target URL, performs Okta login (including TOTP MFA if configured), and saves the browser session for later use. Sessions are stored per-domain in ~/.okta-auth/sessions/.

Credentials are resolved in order: explicit parameter → environment variable → OS keyring when the local provider is set to keyring. When the provider is set to op, launch the server through op run so the environment is populated at process start.

Args: url: Target URL to authenticate against (e.g., 'https://portal.company.com'). username: Okta username or email. Falls back to OKTA_USERNAME or stored keyring data. password: Okta password. Falls back to OKTA_PASSWORD or stored keyring data. totp_secret: Base32 TOTP secret for automated MFA. Falls back to OKTA_TOTP_SECRET or stored keyring data. headed: Show the browser window during login. Set to true for debugging. timeout_ms: Maximum time in ms to wait for page loads (5000-300000, default 60000).

Returns: JSON: {"success": bool, "domain_key": str|null, "message": str, "url": str}

ParametersJSON Schema

Name	Required	Description	Default
`url`	Yes
`headed`	No
`password`	No
`username`	No
`timeout_ms`	No
`totp_secret`	No

Output Schema

ParametersJSON Schema

Name	Required	Description
`result`	Yes

TDQS

A4.8/5.0

Behavior5/5

Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?

Beyond the annotations (idempotent, non-destructive), the description reveals that the tool launches a headless browser, performs TOTP MFA if configured, persists sessions to ~/.okta-auth/sessions/, and details credential fallback logic. This provides substantial behavioral context that aids agent decision-making.

Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.

Conciseness5/5

Is the description appropriately sized, front-loaded, and free of redundancy?

The description is concise and well-structured: opening purpose sentence, brief behavioral overview, standalone credential resolution paragraph, clearly labeled Args section, and Returns specification. Every sentence contributes value without redundancy.

Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.

Completeness5/5

Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?

Given the tool's complexity (6 parameters, 1 required, credential fallback, MFA handling, session persistence), the description covers the overall flow, parameter details, return format, and credential resolution. The output schema is described in the Returns section, making it self-contained. Minor details like error handling could be inferred from the 'message' field in the return.

Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.

Parameters5/5

Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?

With 0% schema description coverage, the description fully compensates by documenting all 6 parameters in an Args section. It explains fallback order for credentials (explicit → env var → keyring), the purpose of 'headed' for debugging, and timeout range/default. This adds critical meaning beyond the schema's bare names and types.

Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.

Purpose5/5

Does the description clearly state what the tool does and how it differs from similar tools?

The first sentence clearly states the tool's function: 'Authenticate to a website via Okta SSO and persist the session.' This specific verb+resource combination immediately distinguishes it from sibling tools (check, list, delete, get_cookies) which deal with session inspection and cleanup.

Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.

Usage Guidelines4/5

Does the description explain when to use this tool, when not to, or what alternatives exist?

The description provides clear context for when to use the tool (to perform Okta login including MFA) and gives detailed information about credential resolution order and headed mode for debugging. However, it does not explicitly exclude alternatives or mention when not to use this tool, though the context of sibling tools makes this largely inferable.

Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.

Tool Schema Changelog

Recent tool additions, removals, and schema changes observed during successful MCP inspections.

5 tool updatesv0.2.2Jul 29, 2026
- First observedokta_check_session
- First observedokta_delete_session
- First observedokta_get_cookies
- First observedokta_list_sessions
- First observedokta_login

Deploy Server

One endpoint for every MCP toolRayrun runs every MCP server behind one URL and holds the credentials. Each call is decided per client, tool, and argument, then recorded.ray.runAd

TDQS

A4.5/5.0

Scored 2026-07-29 23:55 across 5 tools

Disambiguation5/5

Each tool has a clearly distinct purpose: login, check, list, delete, and get cookies. No overlap or ambiguity.

Naming Consistency5/5

All tools follow a consistent pattern: okta_ + verb_noun (e.g., check_session, list_sessions). Even login is an action verb, fitting the pattern.

Tool Count5/5

5 tools cover the core operations for Okta session management: create, verify, list, delete, and export cookies. Not too few or too many for the scope.

Completeness4/5

Covers the main lifecycle: login, check, list, delete, and get cookies. Minor gaps like session refresh or logout are handled implicitly (delete functions as logout), but still a solid set.

Maintenance

ActivityInactive

ResponsivenessNo issues

Resources

GitHub Repository

Need Help?

Related Servers

Related MCP Connectors

ClawLinkOAuth
dev.claw-link
MCP server connecting AI agents to 100+ apps (Gmail, Slack, Notion, GitHub) via one-click OAuth.
App Automation Workplace & Productivity
24
secureflows-mcp A
io.github.michal-lefler
MCP server for secureFlows: token-free URL builders and integration-linting tools for AI agents.
Code Analysis Developer Tools Security
181
anotherai
dev.anotherai
MCP server for building and testing AI agents with multi-model experimentation and insights.
Agent Orchestration Autonomous Agents Testing & QA Tools
2
microservices.sh
sh.microservices
MCP server for AI agents to plan, verify, and deploy Cloudflare-native apps.
Cloud Platforms Agent Orchestration Developer Tools
21

Related MCP Servers

Okta-mcp-server
Agent Orchestration Security Developer Tools
fctr-id
A
license
Not graded
quality
B
maintenance
MCP server to work with okta entities
Updated 5 months ago (2026-04-25 13:57 UTC)
38
Apache 2.0
Agent Identity MCP Server
Security Autonomous Agents
AiAgentKarl
A
license
Not graded
quality
D
maintenance
MCP Server for AI agent identity and authorization. Create, verify, and manage agent identities with trust scores and scoped authorization tokens.
Updated 5 months ago (2026-04-03 16:05 UTC)
MIT
Okta MCP Server
Security Cloud Platforms
BalaGanaparthi
F
license
Not graded
quality
D
maintenance
An MCP server for managing Okta users (CRUD operations) with full OAuth 2.1 compliance, enabling secure integration with Claude Desktop and other MCP clients.
Updated 6 months ago (2026-03-21 09:07 UTC)
-
mcp-ory-kratos
Security Developer Tools
feedback-loop-ai
A
license
Not graded
quality
A
maintenance
MCP server for managing Ory Kratos identities, sessions, and authentication flows, enabling AI assistants to perform identity management tasks via natural language.
Updated 5 days ago (2026-09-12 08:13 UTC)
341 npm
1
MIT