FastMCP-based Okta MCP Server for querying and managing Okta organizations through Model Context Protocol
The Fctr Okta MCP Server provides a mixed-quality toolkit. Strengths: clear tool names with action verbs (read_, get_, okta_), comprehensive descriptions (mostly 150-500 chars), and detailed parameter documentation with SCIM syntax examples. Weaknesses: tool definitions are inferred from docstrings rather than explicitly registered schemas (only `meta_tools.py` excerpt shown; actual registration in `app_tools.py`, `group_tools.py`, `log_tools.py` not visible), making it impossible to verify input schemas for 8 of 12 tools; no structured output schemas documented; error handling lacks actionable recovery guidance; sample data hints suggest tools return 3-result samples but implementation details hidden. The visible meta_tools.py shows proper @mcp.tool() decorators with tag and annotation support, but the critical tool definitions in okta/*.py files are not provided in source code, forcing conservative scoring on those 8 tools.
**CALL THIS FIRST!** Start here to discover what Okta API operations are available. This is your entry point for the Okta API workflow: 1. Call this to see available operations 2. Call get_operation_details() for specific operations you need 3. Call get_code_generation_prompt() to get code template 4. Generate Python code using client.make_request() 5. Call execute_code() to test and execute Returns list of available Okta API operations like 'user.list', 'group.get', etc. Returns operation names like 'user.list', 'group.get', etc. Use this to discover what operations are available before querying details.
Generate code template and best practices for your Okta query.
Get detailed schema for a specific Okta API operation. Returns endpoint, method, parameters, and usage examples. OKTA DOMAIN KNOWLEDGE YOU MUST APPLY: User Status Values: - ACTIVE: Can authenticate (default filter unless user asks otherwise) - STAGED: Not activated yet - PROVISIONED: Provisioned but not activated - PASSWORD_RESET/PASSWORD_EXPIRED: Password issues - LOCKED_OUT: Failed login attempts - SUSPENDED: Temporarily suspended - DEPROVISIONED: Deleted Default Filters (apply unless user specifies otherwise): - Users: status eq "ACTIVE" - Applications: status eq "ACTIVE" Essential Fields by Entity (ALWAYS include): - Users: id, email, login, firstName, lastName, status - Groups: id, name, description, type - Applications: id, label, name, status, signOnMode - DO NOT include timestamp fields unless explicitly requested SCIM Filter Syntax (for 'search' parameter): - Operators: eq, sw, co, gt, lt, ge, le, pr, and, or, not - Examples: status eq "ACTIVE", profile.email sw "admin@" - CRITICAL: Cannot mix 'q' (simple search) with 'search' (SCIM filter) Default Sorting: - Users: profile.lastName ascending - Groups: name ascending - Applications: label ascending NEXT STEP: Use this info with get_code_generation_prompt() to generate Python code. Returns endpoint, HTTP method, parameters, filters, and usage example. Call this after selecting operations from get_available_operations().
Input schemas not visible for 8 of 12 tools (okta_* tools). Docstring-inferred definitions only. Cannot verify JSON Schema types, constraints, or parameter validation.
No output schemas documented. Tools return 'SAMPLE DATA (3 results) + endpoint metadata' but response structure not specified. LLMs cannot plan downstream calls without knowing return field names and types.
Error handling absent or not documented. Tools reference 'call execute_code()' and 'generate Python code' but no guidance on what errors are returned, how to classify them (retryable, user-fixable, fatal), or what recovery actions exist.
Inferred effective spec: <=2025-11-25.
| Scored | Grade | Overall | Spec posture | Rubric |
|---|---|---|---|---|
| 2026-09-22 | D | 50 | <=2025-11-25 | v2 |
| 2026-03-09 | F | 46 | - | v1 |
**CALL read_system_instructions() FIRST!** Get detailed information about a specific application by its ID. ## Path Parameters - **appId** (String, Required): The unique ID of the application. ## Query Parameters - **expand** (String, Optional): Embed user assignment with 'user/{userId}'. ## Response Fields - **id**: Application's unique identifier - **name**: Application type name - **label**: Human-readable application name - **status**: Application status (ACTIVE, INACTIVE) - **created**: When application was created - **lastUpdated**: When application was last modified - **signOnMode**: Authentication mode (SAML_2_0, OPENID_CONNECT, etc.) - **features**: List of enabled features - **settings**: Application-specific settings - **credentials**: Authentication credentials configuration - **visibility**: Visibility settings (auto-submit, hide links) - **accessibility**: Accessibility settings ## SignOn Modes - **BOOKMARK**: Simple bookmark app - **BASIC_AUTH**: Basic authentication - **BROWSER_PLUGIN**: Browser plugin-based auth - **SECURE_PASSWORD_STORE**: Stored password app - **SAML_2_0**: SAML 2.0 federation - **WS_FEDERATION**: WS-Federation - **OPENID_CONNECT**: OIDC authentication - **AUTO_LOGIN**: Automatic login ## Common Use Cases - Get application details before modifications - Verify application configuration - Review authentication settings - Check credentials configuration
IMPORTANT: Call read_system_instructions() FIRST before using this tool! Returns SAMPLE DATA (3 results) + endpoint metadata for code generation. This is NOT the final answer - you must generate Python code for full results. Lists all applications in the organization with optional filtering. ## Query Parameters - **q**: Simple search matching application label (startsWith). - **filter**: SCIM filter for advanced filtering on status, user.id, group.id, credentials.signing.kid. - **limit**: Results per page (max: 200, default: 20). - **after**: Pagination cursor for next page. - **expand**: Embed additional data like user assignment status. - **includeNonDeleted**: Include soft-deleted applications. ## Filter Examples - Active apps: `filter=status eq "ACTIVE"` - Inactive apps: `filter=status eq "INACTIVE"` - Apps assigned to user: `filter=user.id eq "00ub0oNGTSWTBKOLGLNR"` - Apps assigned to group: `filter=group.id eq "00g1emaKYZTWRYYRRTSK"` - Apps with specific signing key: `filter=credentials.signing.kid eq "SIMcCQNY3uwXoW3y0vf6VxiBb5n9pf8L2fK8d-FIbm4"` ## Response Fields - **id**: Application's unique identifier - **name**: Application type name (e.g., 'oidc_client', 'saml_2_0') - **label**: Human-readable application name - **status**: Application status (ACTIVE, INACTIVE) - **created**: When application was created - **lastUpdated**: When application was last modified - **signOnMode**: Authentication mode (SAML_2_0, OPENID_CONNECT, etc.) - **features**: List of enabled features - **visibility**: Visibility settings - **credentials**: Authentication credentials configuration ## Application Status Values - **ACTIVE**: Application is active and accessible - **INACTIVE**: Application is disabled - **DELETED**: Application is soft-deleted (with includeNonDeleted) ## Common Use Cases - Inventory all applications - Find apps by name - Audit inactive applications - Find apps assigned to specific user/group
**CALL read_system_instructions() FIRST!** Returns SAMPLE DATA (3 results) + endpoint metadata for code generation. This is NOT the final answer - you must generate Python code for full results. Lists users assigned to a specific application. ## Path Parameters - **appId** (String, Required): The unique ID of the application. ## Query Parameters - **q**: Simple search matching user profile (firstName, lastName, email). - **after**: Pagination cursor for next page. - **limit**: Results per page (max: 200, default: 20). ## Response Fields - **id**: User's unique identifier - **status**: User status in application (ACTIVE, STAGED, etc.) - **created**: When assignment was created - **lastUpdated**: When assignment was last updated - **scope**: OKTA (Okta-managed) or IMPORT (imported from app) - **credentials**: User credentials for the application - **profile**: User profile information (firstName, lastName, email, login) ## Common Use Cases - List users assigned to an application - Find user assignments for license auditing - Verify user access to specific applications
Get the current date and time in UTC, formatted for Okta API usage. Returns current UTC timestamp in ISO 8601 format with microseconds and Z suffix, suitable for Okta API date parameters and filtering. ## Buffer Hours Use buffer_hours to get times in the past (negative) or future (positive): - buffer_hours=0: Current time - buffer_hours=-24: 24 hours ago - buffer_hours=-168: 1 week ago (7*24 hours) - buffer_hours=24: 24 hours from now ## Output Format Returns timestamp in format: YYYY-MM-DDTHH:MM:SS.ffffffZ Example: 2024-06-23T14:30:15.123456Z ## Use Cases - Log event filtering: since="2024-06-22T00:00:00.000Z" - User creation filters: lastUpdated gt "timestamp" - Application audit queries with time ranges - Policy rule time-based conditions Perfect for constructing Okta API queries that require precise timestamps.
Parse natural language time expressions into Okta API-compatible timestamps. Converts human-readable time expressions into ISO 8601 formatted timestamps with microseconds, suitable for Okta API queries and filtering. ## Supported Expressions - Relative times: "2 days ago", "1 week ago", "3 months ago" - Named times: "yesterday", "last week", "last month" - Precise times: "1 hour ago", "30 minutes ago" - Period boundaries: "beginning of today", "end of yesterday" - Week/month boundaries: "start of this week", "end of last month" ## Output Format Returns timestamp in format: YYYY-MM-DDTHH:MM:SS.ffffffZ Example: 2024-06-21T00:00:00.000000Z ## Common Use Cases - Log queries: 'since=parse_relative_time("24 hours ago")' - User filters: 'lastUpdated gt parse_relative_time("1 week ago")' - Application activity: 'created after parse_relative_time("yesterday")' - Policy rule conditions with time-based criteria Perfect for constructing Okta audit queries and date-based filters: Example: filter='eventType eq "user.authentication.auth" and published gt "parsed_timestamp"'
**CALL read_system_instructions() FIRST!** Get detailed information about a specific group by its ID. ## Path Parameters - **groupId** (String, Required): The unique ID of the group. ## Response Fields - **id**: Group's unique identifier - **created**: When the group was created - **lastUpdated**: When the group was last modified - **lastMembershipUpdated**: When membership was last changed - **type**: Group type (OKTA_GROUP, APP_GROUP, BUILT_IN) - **profile.name**: Group display name - **profile.description**: Group description - **_embedded**: Additional data if expand parameter used ## Group Types - **OKTA_GROUP**: Groups managed within Okta - **APP_GROUP**: Groups synced from applications (AD, LDAP, etc.) - **BUILT_IN**: System groups like "Everyone" ## Common Use Cases - Get group details before modifications - Verify group exists - Check group type and metadata - Audit group information
IMPORTANT: Call read_system_instructions() FIRST before using this tool! Returns SAMPLE DATA (3 results) + endpoint metadata for code generation. This is NOT the final answer - you must generate Python code for full results. Lists all groups in the organization. With expand=stats, provides member counts in single call (replaces list-group-members count queries). With expand=app, includes assigned application details for APP_GROUP types (replaces list-assigned-apps-for-group calls). Use for group management, membership analysis, access governance, and organizational structure reviews. ## Query Parameters - **search**: Most powerful method using SCIM expressions for optimal search performance. Searches profile attributes (prefix with `profile.`), system properties (id, type, created, lastUpdated, lastMembershipUpdated), and source.id for APP_GROUP types. - **filter**: SCIM expressions for limited system properties only: id, type, lastUpdated, lastMembershipUpdated. - **q**: Simple search matching group name property only. Default limit 300 results, pagination not supported. - **expand**: Include metadata - `stats` (user count) or `app` (application details for APP_GROUP). - **limit**: Number of results per page (max: 10000, recommended: ≤200). - **after**: Pagination cursor for next page (not available with search queries). - **sortBy**: Sort field for search queries only. - **sortOrder**: Sort direction `asc` or `desc` (search queries only, requires sortBy). ## Parameter Usage Notes - **CRITICAL**: Use `search` for profile attributes, use `filter` for limited system properties only - mixing causes errors. - Search and pagination are mutually exclusive - search queries cannot use `after` parameter. - Query parameter (`q`) has 300 result limit, no pagination support. - Use `expand=stats` to get member counts without additional API calls. - Use `expand=app` for APP_GROUP types to get application assignments in single call. ## Search Examples - Group Type: `search=type eq "OKTA_GROUP"` or `search=type eq "APP_GROUP"` - Profile Attributes: `search=profile.name eq "Engineering Team"` - Time-based: `search=lastMembershipUpdated gt "2024-01-01T00:00:00.000Z"` - Source Application: `search=source.id eq "0oa2v0el0gP90aqjJ0g7"` (APP_GROUP only) - Complex: `search=type eq "APP_GROUP" and created lt "2024-01-01T00:00:00.000Z"` - Name Contains: `search=profile.name co "Sales"` (partial matching) - Name Starts With: `search=profile.samAccountName sw "West Coast"` ## Filter Examples - System Properties: `filter=type eq "OKTA_GROUP"` - Multiple Criteria: `filter=type eq "OKTA_GROUP" and lastUpdated gt "2024-01-01T00:00:00.000Z"` ## Important Notes - The `co` operator only works with profile.name and profile.description - other attributes must use `eq` or `sw`. - All SCIM expressions must be URL encoded. - Search uses eventually consistent datasource - may not reflect latest changes immediately. - Default Everyone group not returned for users with group admin role.
**CALL read_system_instructions() FIRST!** Get Okta system log events with comprehensive filtering. Returns detailed log events from Okta system logs including authentication, user management, application access, policy changes, and administrative actions. ## Time Parameters - **since**: Start time in ISO 8601 format - **until**: End time in ISO 8601 format - Use `okta_datetime_parse_relative` tool: "24 hours ago", "7 days ago", "1 week ago", "now" - Use `okta_datetime_now` tool: Get current UTC time with optional buffer_hours offset ## Filter Parameter Uses Okta expression language for precise event filtering: - `eventType eq "user.authentication.auth"` - Authentication events - `eventType eq "user.lifecycle.create"` - User creation events - `eventType eq "user.lifecycle.activate"` - User activation events - `eventType eq "user.lifecycle.suspend"` - User suspension events - `eventType eq "application.lifecycle.create"` - App creation events - `outcome.result eq "SUCCESS"` - Successful events only - `outcome.result eq "FAILURE"` - Failed events only - `actor.id eq "user_id"` - Events by specific user - `target.id eq "target_id"` - Events targeting specific resource ## Common Event Types - `user.authentication.auth` - User login attempts - `user.authentication.sso` - SSO authentication - `user.session.start` - Session initiation - `user.session.end` - Session termination - `user.lifecycle.create` - User creation - `user.lifecycle.activate` - User activation - `user.lifecycle.suspend` - User suspension - `user.lifecycle.deactivate` - User deactivation - `application.user_membership.add` - App assignment - `application.user_membership.remove` - App removal - `group.user_membership.add` - Group membership addition - `group.user_membership.remove` - Group membership removal - `policy.lifecycle.create` - Policy creation - `policy.lifecycle.update` - Policy modification ## Search Parameter (q) Free-text search across event data: - Search for usernames, email addresses, application names - Search for IP addresses, client information - Search for error messages or specific text in events ## Example Filters - Authentication failures: `eventType eq "user.authentication.auth" and outcome.result eq "FAILURE"` - User lifecycle changes: `eventType sw "user.lifecycle"` - Application events: `eventType sw "application"` - Admin actions: `actor.type eq "User" and eventType sw "policy"` - Specific user activity: `actor.alternateId eq "[email protected]"` Returns SAMPLE DATA (3 results) + endpoint metadata for code generation. You MUST generate Python code to get actual results - see read_system_instructions().
**CALL THIS FIRST BEFORE USING ANY okta_* TOOLS!** Returns critical system instructions for how to use the Okta API tools correctly. The okta_* tools return sample data, but you MUST generate Python code for actual queries.
Tools return 3-result samples only, not full results. Descriptions state 'SAMPLE DATA (3 results) + endpoint metadata for code generation' and 'This is NOT the final answer - you must generate Python code'. This breaks the tool abstraction, the LLM must write and execute code to get real answers, not use the tool directly.
Complex SCIM filter syntax and Okta domain knowledge embedded in descriptions (user status values, default filters, essential fields, sorting rules). This places reasoning burden on the LLM instead of making the tool self-contained. E.g., okta_group_list description is 500+ chars of Okta-specific knowledge.
Parameter 'mode' in get_code_generation_prompt has no enum constraint or clear values documented ('agent' vs 'direct' mentioned but format unclear). Parameter descriptions lack format examples for complex filters like SCIM expressions.
No documented pagination pattern. okta_app_list, okta_app_list_users, okta_group_list accept 'after' cursor and 'limit' but no 'total_count' or '_links.next' metadata shown in output schema. LLMs cannot plan iteration without knowing when pagination ends.