Okta MCP Server (OAuth 2.1 Compliant)

An MCP (Model Context Protocol) server for Okta user management with full OAuth 2.1 compliance. This server provides tools for CRUD operations on Okta users and can be deployed to Railway or run locally with Docker.

Features

• create_user - Create a new Okta user
• list_users - List users with optional search filtering
• get_user - Get user details by ID or login
• update_user - Update user profile information
• delete_user - Deactivate and delete a user
• OAuth 2.1 Authentication - Industry-standard security with PKCE, Bearer tokens, and token introspection

Prerequisites

• Docker and Docker Compose
• Okta developer account with API access
• Okta OAuth 2.0 credentials (recommended) OR API token (legacy)

Getting Okta OAuth 2.0 Credentials (Recommended)

1. Log in to your Okta Admin Console
2. Navigate to Applications > Applications
3. Click Create App Integration
4. Select API Services (for machine-to-machine communication)
5. Give it a name (e.g., "MCP Server")
6. Grant scopes: okta.users.manage, okta.users.read
7. Save the Client ID and Client Secret

Alternative: Using API Token (Legacy)

1. Log in to your Okta Admin Console
2. Navigate to Security > API > Tokens
3. Click Create Token
4. Give it a name and copy the token value (you won't be able to see it again)

Note: OAuth 2.0 Client Credentials is recommended for better security and OAuth 2.1 compliance.

Local Development

1. Configure Environment

# Copy the example environment file
cp .env.example .env

# Edit .env with your credentials
# Option 1: OAuth 2.0 Client Credentials (Recommended)
# OKTA_DOMAIN=dev-xxxxx.okta.com
# OKTA_CLIENT_ID=0oaxxxxxxxxx
# OKTA_CLIENT_SECRET=xxxxxxxxxxxxxxxxxxxx
# DEVELOPMENT_MODE=true  # For VSCode testing

# Option 2: Legacy API Token
# OKTA_DOMAIN=dev-xxxxx.okta.com
# OKTA_API_TOKEN=00xxxxxxxxxxxxxxxxxx
# DEVELOPMENT_MODE=true  # For VSCode testing

2. Build and Run with Docker

# Build and start the server
docker-compose up --build

# The server will be available at http://localhost:8000

3. Test the Server

# Check server health (no auth required)
curl http://localhost:8000/health

# Check OAuth 2.1 discovery endpoint
curl http://localhost:8000/.well-known/oauth-authorization-server

# Test MCP endpoint (requires OAuth 2.1 Bearer token)
# First, obtain an access token from Okta using OAuth 2.1 flow with PKCE
# Then use it to call the MCP endpoint:
curl -X POST http://localhost:8000/mcp \
  -H "Authorization: Bearer YOUR_ACCESS_TOKEN" \
  -H "Content-Type: application/json" \
  -H "Accept: application/json, text/event-stream" \
  -d '{"jsonrpc": "2.0", "id": 1, "method": "initialize", "params": {"protocolVersion": "2024-11-05", "capabilities": {}, "clientInfo": {"name": "test", "version": "1.0.0"}}}'

4. Test with MCP Inspector

npx @anthropic/mcp-inspector http://localhost:8000/mcp

Railway Deployment

1. Push to GitHub

Push this repository to your GitHub account.

2. Deploy to Railway

1. Go to Railway
2. Click New Project > Deploy from GitHub repo
3. Select your repository
4. Railway will auto-detect the Dockerfile

3. Configure Environment Variables

In Railway dashboard, add these environment variables:

Recommended: OAuth 2.0 Client Credentials

Variable	Description
OKTA_DOMAIN	Your Okta domain (e.g., dev-12345.okta.com)
OKTA_CLIENT_ID	OAuth 2.0 Client ID from Okta
OKTA_CLIENT_SECRET	OAuth 2.0 Client Secret from Okta
OKTA_AUDIENCE	OAuth 2.1 audience (optional, default: api://default)

Alternative: Legacy API Token

Variable	Description
OKTA_DOMAIN	Your Okta domain (e.g., dev-12345.okta.com)
OKTA_API_TOKEN	Your Okta API token
OKTA_AUDIENCE	OAuth 2.1 audience (optional, default: api://default)

For VSCode Testing (Optional)

Variable	Description
DEVELOPMENT_MODE	Set to true to disable OAuth authentication

Railway automatically provides the PORT variable.

4. Get Your Server URL

After deployment, Railway provides a public URL:

https://okta-mcp-server-003-production.up.railway.app

Using with Claude Desktop

Add to your Claude Desktop MCP configuration (claude_desktop_config.json) with OAuth 2.1:

{
  "mcpServers": {
    "okta": {
      "url": "https://okta-mcp-server-003-production.up.railway.app/mcp",
      "oauth": {
        "authorizationUrl": "https://YOUR-OKTA-DOMAIN/oauth2/default/v1/authorize",
        "tokenUrl": "https://YOUR-OKTA-DOMAIN/oauth2/default/v1/token",
        "clientId": "YOUR_OKTA_CLIENT_ID",
        "clientSecret": "YOUR_OKTA_CLIENT_SECRET",
        "scopes": ["openid", "profile", "mcp:read", "mcp:write"]
      }
    }
  }
}

For local development:

{
  "mcpServers": {
    "okta": {
      "url": "http://localhost:8000/mcp",
      "oauth": {
        "authorizationUrl": "https://YOUR-OKTA-DOMAIN/oauth2/default/v1/authorize",
        "tokenUrl": "https://YOUR-OKTA-DOMAIN/oauth2/default/v1/token",
        "clientId": "YOUR_OKTA_CLIENT_ID",
        "clientSecret": "YOUR_OKTA_CLIENT_SECRET",
        "scopes": ["openid", "profile", "mcp:read", "mcp:write"]
      }
    }
  }
}

Note: OAuth 2.1 requires PKCE (Proof Key for Code Exchange) with S256 code challenge method. The client must support this requirement.

Using with VSCode

VSCode's MCP client doesn't natively support OAuth 2.1 flows. For VSCode integration, enable Development Mode:

Configuration

1. Set environment variable:

DEVELOPMENT_MODE=true

2. Configure VSCode MCP (.vscode/mcp.json):

{
  "servers": {
    "okta-mcp": {
      "url": "http://localhost:8000/mcp",
      "type": "http"
    }
  }
}

⚠️ Warning: Only use development mode for local testing. Never enable in production!

For detailed VSCode setup instructions, see VSCODE_INTEGRATION.md.

OAuth 2.1 Compliance

This server implements OAuth 2.1 security best practices:

✅ Security Features

• PKCE Required: S256 code challenge method mandatory for all authorization flows
• Bearer Token Authentication: Cryptographic JWT validation with RSA signatures
• Token Validation: Full verification of signature, expiration, issuer, and audience
• No Deprecated Flows: Implicit and password grants are not supported
• Token Introspection: RFC 7662 compliant endpoint at /token/introspect
• Discovery Endpoints: RFC 8414 compliant metadata at /.well-known/oauth-authorization-server

🔐 Authentication Flow

1. Client initiates authorization with PKCE (S256 code challenge)
2. User authenticates with Okta
3. Authorization code returned to client
4. Client exchanges code for access token (with code verifier)
5. Client uses Bearer token to access MCP endpoints
6. Server validates JWT signature, expiration, and claims

📋 Discovery Endpoints

• /.well-known/oauth-authorization-server - OAuth 2.1 server metadata
• /.well-known/openid-configuration - OpenID Connect discovery
• /.well-known/oauth-protected-resource - Protected resource metadata
• /health - Health check with OAuth 2.1 compliance info
• /token/introspect - Token introspection (RFC 7662)

For detailed information about OAuth 2.1 changes, see OAUTH_2.1_CHANGES.md.

API Reference

create_user

Create a new Okta user.

Parameters:

• email (required): User's email address
• first_name (required): User's first name
• last_name (required): User's last name
• login (optional): User's login (defaults to email)

list_users

List users with optional filtering.

Parameters:

• limit (optional): Maximum users to return (default: 20)
• search (optional): Search query for filtering

get_user

Get user by ID or login.

Parameters:

• user_id (required): User ID or login email

update_user

Update user profile.

Parameters:

• user_id (required): User ID or login email
• first_name (optional): New first name
• last_name (optional): New last name
• email (optional): New email address

delete_user

Deactivate and permanently delete a user.

Parameters:

• user_id (required): User ID or login email

Project Structure

okta-mcp-server/
├── src/
│   └── okta_mcp_server/
│       ├── __init__.py
│       ├── server.py          # MCP server with tools
│       └── okta_client.py     # Okta API wrapper
├── Dockerfile
├── docker-compose.yml
├── pyproject.toml
├── requirements.txt
├── .env.example
└── README.md

License

MIT