fctr-id/fctr-okta-mcp-server

Built by the Fctr Identity team • Not affiliated with Okta

TAKO MCP Server for Okta (beta v0.1)

⚡ Powered by Anthropic's Code Execution with MCP Architecture

Production-ready MCP server implementing Anthropic's Code Execution with MCP pattern with dual-mode operation, context-engineering, enhanced security sandbox, and enterprise-grade features.

Overview

A production-ready MCP server for Okta administration with dual-mode operation. Successor to okta-mcp-server.

This server enables AI assistants to query Okta resources using the Model Context Protocol. It is designed for IAM engineers, security teams, and Okta administrators who want to give their AI tools safe, controlled access to their Okta environment.

Key Features:

• 🔄 Dual-Mode Operation - Standard MCP server mode or autonomous agent mode
• 🌐 Flexible Transports - STDIO for desktop clients, HTTP for remote deployments
• 🔑 Okta Tokens - API Token (simple) or OAuth2 with Private Key JWT (production)
• 📊 CSV Export - Save query results to files for reporting
• 🔒 Secure Execution - AST-based sandbox with whitelisted operations
• ✅ MCP Compliant - Elicitation, Progress notifications, logging, and tool annotations

📋 Table of Contents

• Core Concepts
• Quick Start
• Configuration
  • Okta Authentication
• MCP Client Setup
• Available Tools
• Security
• Rate Limits
• Get Help
• License

🧠 Core Concepts

Before installing, it's helpful to understand the two key configuration choices: Mode and Transport.

1. Operating Modes

Controls how the AI interacts with the server. Set via ENABLE_AGENT_MODE environment variable.

Basic MCP ServerMode (Default)

Tools exposed directly to the LLM. The AI calls read_system_instructions() first, then uses okta_* tools for sample data and execute_code() for full results.

Can be used for:

Agent Mode

AI discovers APIs dynamically via get_available_operations() and get_operation_details(), then generates code for execution. This mode is ideal for complex, multi-step queries where the agent explores the API surface as needed.

2. Transports

Controls how clients connect to the server.

🚀 Quick Start

Choose the installation method that fits your workflow.

Option A: Docker (Recommended)

The fastest way to get started without managing Python dependencies.

# 1. Clone the repository
git clone https://github.com/fctr-id/fctr-okta-mcp-server.git
cd fctr-okta-mcp-server

# 2. Create directories for persistent data
mkdir -p logs okta_results  # Windows: New-Item -ItemType Directory -Path logs, okta_results -Force

# 3. Create a .env file (see Configuration section for all options)
cp .env.sample .env
# Edit .env with your Okta credentials

# 4. Build with Docker
docker build --target stdio -t tako-mcp-server:stdio .  # STDIO mode
docker build --target http -t tako-mcp-server:http .    # HTTP mode

Option B: Local Python (uv)

We recommend uv for fast, reliable package management.

# 1. Clone and setup
git clone https://github.com/fctr-id/fctr-okta-mcp-server.git
cd fctr-okta-mcp-server

# 2. Create virtual environment
uv venv .venv
source .venv/bin/activate  # Windows: .venv\Scripts\activate

# 3. Install dependencies
uv pip install -e .

# 4. Create a .env file (see Configuration section for all options)
cp .env.sample .env
# Edit .env with your Okta credentials

# 5. Run (HTTP - for remote/web access)
python -m fctr_okta_mcp.server --http-transport --i-understand-the-risks

⚙️ Configuration

Configuration is managed via environment variables. Set these in a .env file or pass them directly.

Environment Variables

Okta Authentication

TOKEN_METHOD=API_TOKEN
OKTA_API_TOKEN=your-api-token-here

TOKEN_METHOD=OAUTH2
OKTA_OAUTH2_CLIENT_ID=your-client-id
OKTA_OAUTH2_SCOPES=okta.users.read okta.groups.read okta.apps.read
OKTA_OAUTH2_PRIVATE_KEY_PEM="-----BEGIN PRIVATE KEY-----
MIIEvgIBADANBgkqh...
...your-private-key...
-----END PRIVATE KEY-----"

🔌 MCP Client Setup

STDIO Transport (Desktop Clients)

For Claude Desktop, VS Code, Cursor, and other local MCP clients:

{
  "mcpServers": {
    "tako-mcp": {
      "command": "path/to/.venv/Scripts/python",
      "args": ["-m", "fctr_okta_mcp.server"],
      "env": {
        "OKTA_CLIENT_ORGURL": "https://your-org.okta.com",
        "OKTA_API_TOKEN": "your_api_token",
        "ENABLE_AGENT_MODE": "true"
      }
    }
  }
}

HTTP Transport (Remote/Web)

For web-based deployments, remote access, or programmatic clients.

Start the server first:

python -m fctr_okta_mcp.server --http-transport --i-understand-the-risks

Then configure your MCP client:

{
  "mcpServers": {
    "tako-mcp": {
      "url": "http://localhost:8000/mcp",
      "type": "http"
    }
  }
}

Docker (STDIO)

See Quick Start - Docker for build instructions.

{
  "mcpServers": {
    "tako-mcp": {
      "command": "docker",
      "args": [
        "run", "-i", "--rm",
        "-v", "./logs:/app/logs",
        "-v", "./okta_results:/app/okta_results",
        "-e", "OKTA_CLIENT_ORGURL",
        "-e", "OKTA_API_TOKEN",
        "-e", "ENABLE_AGENT_MODE=true",
        "tako-mcp-server:stdio"
      ],
      "env": {
        "OKTA_CLIENT_ORGURL": "https://your-org.okta.com",
        "OKTA_API_TOKEN": "your_api_token"
      }
    }
  }
}

Docker (HTTP)

For HTTP transport with Docker:

docker run -p 8000:8000 \
  -v ./logs:/app/logs \
  -v ./okta_results:/app/okta_results \
  -e OKTA_CLIENT_ORGURL=https://your-org.okta.com \
  -e OKTA_API_TOKEN=your_api_token \
  -e MCP_BASE_URL=http://localhost:8000 \
  tako-mcp-server:http

Note: The server binds to 0.0.0.0:8000 inside the container (required for Docker networking), but MCP_BASE_URL controls what URL is reported to MCP clients.

🛠️ Available Tools

When in Basic MCP Mode, the following tools are available:

User Management

• okta_user_list - List users with filtering, search, and pagination
• okta_user_get - Get detailed user profile by ID or login
• okta_user_list_groups - List groups a user belongs to
• okta_user_list_applications - List applications assigned to a user
• okta_user_list_factors - List enrolled authentication factors

Group Operations

• okta_group_list - List groups with filtering and pagination
• okta_group_get - Get detailed group information
• okta_group_list_users - List members of a group
• okta_group_list_applications - List applications assigned to a group

Application Management

• okta_app_list - List applications with filtering
• okta_app_get - Get detailed application information
• okta_app_list_users - List users assigned to an application
• okta_app_list_groups - List groups assigned to an application

System Logs

• okta_log_get_events - Query system log events with advanced filtering

Policies & Network Zones

• okta_policy_list_rules - List rules for a specific policy
• okta_policy_get_rule - Get detailed policy rule configuration
• okta_network_list_zones - List network zones
• okta_network_get_zone - Get detailed network zone information

Utilities

• okta_datetime_now - Get current UTC timestamp for queries
• okta_datetime_parse_relative - Parse natural language time expressions (e.g., "24 hours ago")

In Agent Mode, these tools are hidden. The agent uses get_available_operations to discover them dynamically.

🔒 Security

Code Execution Sandbox

All generated Python code is validated before execution:

Data Privacy

• Okta data is sent to the AI model during queries
• Large result sets export to CSV; only summaries return to AI
• Auto-Cleanup: CSV files generated in HTTP mode are automatically deleted after 1 hour
• Ensure organizational policies permit AI processing of Okta data

🚨 Rate Limits

Step 1: Identify your Okta API rate limit percentage (we recommend setting it to 100% in the Okta Admin Console).

Step 2: Set OKTA_CONCURRENT_LIMIT in your .env file based on your Okta plan:

⚠️ Monitor for Rate Limit Warnings:

WARNING - Concurrent limit rate exceeded

If you see this frequently:

• Reduce your OKTA_CONCURRENT_LIMIT by 10-20%
• Cancel the sync and try a lower value
• Contact support@fctr.io if issues persist

🆘 Get Help

Before raising an issue, check:

1. 📝 Server configuration and .env file
2. 🔑 Okta API token permissions
3. 🔌 MCP client compatibility
4. 📊 Server logs in logs/ directory

Support Channels:

• 🐛 GitHub Issues - Bug reports and feature requests
• 📧 Email: support@fctr.io - General support
• 💬 Slack: dan@fctr.io - Quick questions

📄 License

Elastic License 2.0 - See .

✅ Use for internal purposes • ✅ Modify and distribute
❌ Hosted/managed service • ❌ Remove license notices

🌟 © 2025 Fctr Identity. Made with ❤️ for the Okta and AI communities.