Okta Agent

CLI or API | MCP

Version: 2.2.1

Documentation — Installation, deployment, usage across the API, CLI, and MCP server live on the docs site: https://knuckles-team.github.io/okta-agent/

Table of Contents

• Overview
• Architecture
• Installation
• Configure
• Environment Variables
• Quick Start
• Run
• MCP Tools
• Deployment
• Keycloak Parity
• Development

Overview

Enterprise CIAM/SSO connector for the agent fleet: a production-grade MCP applications, policies, and the system log. Complements keycloak-agent (open-source IdP) with the commercial-IdP side of the house, mirroring its verb taxonomy so agents can switch IdPs with familiar verbs.

• Raw httpx client — no Okta SDK; every method documents the endpoint it calls.
• Two auth modes: SSWS API token and OAuth2 private-key-JWT (org authorization server, Okta API scopes).
• Rate-limit aware: every response envelope carries the latest X-Rate-Limit-* snapshot; HTTP 429 triggers capped automatic backoff.
• Cursor pagination via Link: rel="next" headers (Okta's after cursor), with hard item caps and resumable next_cursors.
• Safety: destructive operations (disable / remove / clear sessions / password ops) are blocked unless explicitly allowed; credential material is redacted from logs and error envelopes.

Architecture

Installation

Install the connector-focused [mcp] extra. Examples use okta-agent[mcp] to add FastMCP / FastAPI through agent-connector-sdk; the required Agent Connector SDK core enables model orchestration.

Pick the extra that matches what the operator want to run:

Container images (:mcp)

One multi-stage docker/Dockerfile builds the MCP-only image (--target mcp):

</code></pre>
<p>agent (<code>immutable agent digest</code>) with a co-located <code>:mcp</code> sidecar.</p>
<h3 id="user-content-knowledge-graph-database-epistemic-graph">Knowledge-graph database (<code>epistemic-graph</code>)<a href="#user-content-knowledge-graph-database-epistemic-graph" aria-label="Link to heading 'Knowledge-graph database (epistemic-graph)'" data-heading-content="Knowledge-graph database (epistemic-graph)" class="anchor"></a></h3>
<p>Agent Connector SDK core dependency (<code>epistemic-graph[full]</code>). The <code>[mcp]</code> extra keeps
deployments can use the bundled engine. For production or shared state, run
<strong>epistemic-graph as a dedicated database service</strong> and configure the runtime to use it.
Deployment recipes (single-node + Raft HA), connection configuration, and architecture
diagrams are documented in the
<a href="https://knuckles-team.github.io/epistemic-graph/deployment/">epistemic-graph deployment guide</a>.</p>
<h2 id="user-content-configure">Configure<a href="#user-content-configure" aria-label="Link to heading 'Configure'" data-heading-content="Configure" class="anchor"></a></h2>
<pre><code class="language-bash">export OKTA_ORG_URL="https://acme.okta.com"

# Mode 1 — SSWS API token (takes precedence)
export OKTA_API_TOKEN="<api token>"

# Mode 2 — OAuth2 private-key-JWT (service app, Okta API scopes)
export OKTA_CLIENT_ID="0oa..."
export OKTA_PRIVATE_KEY_FILE="/path/to/key.pem"   # or OKTA_PRIVATE_KEY inline
export OKTA_SCOPES="okta.users.read okta.groups.manage"

See .env.example for every knob (OKTA_TLS_PROFILE, OKTA_MAX_RETRIES, OKTA_BACKOFF_CAP_SECONDS, OKTA_ALLOW_DESTRUCTIVE, per-tool switches).

Environment Variables

Package environment variables

Inherited agent-connector-sdk variables (apply to every connector)

30 package + 16 inherited variable(s). Auto-generated from .env.example + the shared agent-connector-sdk set — do not edit.

Quick Start

from okta_agent import Api
from okta_agent.api.credentials import SswsToken
from okta_agent.okta_input_models import SearchInput, FilterCondition

api = Api(org_url="https://acme.okta.com", credential=SswsToken("<token>"))

active = api.search_users(
    conditions=[{"field": "status", "op": "eq", "value": "ACTIVE"}],
)
print(active["data"], active["rate_limit"])

# Or build typed tool params for the MCP surface:
params = SearchInput(
    conditions=[FilterCondition(field="status", op="eq", value="ACTIVE")]
).model_dump_json(exclude_none=True)

Run

okta-mcp                                  # stdio MCP server
okta-mcp --transport streamable-http --host 0.0.0.0 --port 8000

MCP Tools

Five consolidated, action-routed tools. Each takes action, params_json, and (where applicable) allow_destructive.

Condensed action-routed tools (MCP_TOOL_MODE=condensed)

Verbose 1:1 API-mapped tools (MCP_TOOL_MODE=verbose or both)

6 action-routed tool(s) · 54 verbose 1:1 tool(s). Each is enabled unless its <DOMAIN>TOOL toggle is set false; MCP_TOOL_MODE selects the surface (intent default — the six verb-tools, granular set loaded on demand · condensed action-routed · verbose 1:1 · both). Auto-generated — do not edit.

Examples

{"action": "search", "params_json": "{\"conditions\": [{\"field\": \"status\", \"op\": \"eq\", \"value\": \"ACTIVE\"}, {\"field\": \"profile.department\", \"op\": \"eq\", \"value\": \"Engineering\"}]}"}

{"action": "create", "params_json": "{\"template\": \"oidc\", \"label\": \"My App\", \"settings\": {\"redirect_uris\": [\"https://app.example.com/cb\"]}}"}

{"action": "deactivate", "params_json": "{\"user_id\": \"00u1\"}", "allow_destructive": true}

Every successful response is an envelope:

{"data": [...], "rate_limit": {"limit": 600, "remaining": 599, "reset": 1700000000}, "count": 5, "truncated": false, "next_cursor": null}

Errors map Okta's envelope: {"error": {"status", "error_code", "error_summary", "error_id", "error_causes", "rate_limit"}}.

Deployment

MCP_URL, PROVIDER, and MODEL_ID from the environment. Prebuilt images: (full agent) — see Container images. See docs/deployment.md for transports, reverse proxy, and DNS guidance.

Additional Deployment Options

okta-agent can run as a local stdio process or container, or behind a remote network boundary. The Deployment guide carries the detailed transport contract.

• Local container — launch a reviewed immutable image as a least-privilege stdio child with no listener or published port.
• Remote URL — connect through an operator-supplied authenticated HTTPS ingress. Keep its URL, outbound identity references, trust profile, and exact MCP_ALLOWED_HOSTS in AgentConfig.

Keycloak parity

Verbs intentionally mirror keycloak-agent where the concepts overlap, so an agent fluent in one IdP connector can drive the other:

Okta-only surface: lifecycle states (suspend/unlock), group rules, app assignment profiles, network zones, Okta API scopes via private-key-JWT.

Development

pip install -e .[mcp,test]
pytest -v
pre-commit run --all-files

API references are cited in every client docstring (https://developer.okta.com/docs/api/).

Deploy with agent-connector-sdk-deployment

Provision this package with the consolidated agent-connector-sdk-deployment workflow. It selects an installed-package, editable-source, or immutable-container path; records only runtime secret and TLS-profile references in AgentConfig; and runs doctor, registration, policy, observability, and rollback gates. Ask your agent to "deploy okta-agent with agent-connector-sdk-deployment".

The repository embeds no deployment profile, credential value, certificate path, or environment-specific endpoint. Supply those at runtime through AgentConfig and the configured secret provider.

Governed capability contract

This package ships a compact canonical skill surface with specialist procedures kept as referenced workflows. The current MCP tools, skill metadata, connector_manifest.yml, ontology, mappings, shapes, fixtures, migrations, tool-schema fingerprints, and certification metadata form one versioned capability contract. Validate them together; do not rely on stale tool names or historical per-task skill wrappers.

Runtime endpoints, credentials, certificate trust, tenant identity, retention, and observability policy are deployment inputs and are never packaged values. See Configuration, trust, and privacy before enabling a network transport, connector ingestion, Arbora delegation, or trace export.