# WorkOS MCP

> WorkOS connects your enterprise identity platform to your AI agent, letting you manage complex organizations, audit security logs, and monitor Single Sign-On (SSO) connections via natural chat. Use this MCP to handle directory sync status checks and user roster lookups without ever logging into the WorkOS dashboard.

## Overview
- **Category:** fort-knox
- **Price:** Free
- **Tags:** sso, saml, oidc, directory-sync, audit-logs, enterprise-ready, authentication

## Description

Managing an enterprise's identity infrastructure shouldn't feel like navigating a decade-old web portal. This MCP connects your WorkOS account to any AI agent, letting you treat your entire organization setup as just another conversation. Instead of clicking through multiple tabs to check if a directory sync is active or finding the unique ID for a specific tenant, you simply ask your agent. You can instantly list and audit all connected SSO services like SAML and OIDC links, or retrieve detailed metadata about any synced user group or organization. The Vinkius catalog makes it easy: connect once from your preferred AI client and gain full control over governance tasks—from creating new organizational records to streaming security audit logs—all through simple chat commands.

## Tools

### create_workos_organization
Creates a new organizational record by requiring the name and authorized domains.

### get_audit_log_events
Retrieves a stream of security events tracked within a specific organization.

### get_sso_connection_details
Fetches detailed information for one particular Single Sign-On connection.

### get_directory_details
Retrieves metadata about a specific directory instance, such as Okta or Azure AD connections.

### get_organization_details
Fetches detailed information for a given organization ID.

### list_sso_connections
Lists every active Single Sign-On connection configured across the account.

### list_directories
Provides a list of all currently running directory synchronization instances.

### list_directory_groups
Lists every group that has been synced from an external directory source.

### list_workos_organizations
Retrieves a comprehensive list of all organizations managed in the WorkOS account.

### list_directory_users
Lists every user that has been synced from an external directory source.

## Prompt Examples

**Prompt:** 
```
List all organizations in my WorkOS account.
```

**Response:** 
```
I found 5 organizations: 1. 'Acme Corp' (ID: org_01E...), 2. 'Global Tech' (ID: org_01F...), 3. 'Stark Industries' (ID: org_01G...), and 2 others. Which one would you like to see details for?
```

**Prompt:** 
```
Check the status of SSO connections for 'Acme Corp'.
```

**Response:** 
```
Acme Corp (org_01E...) has 2 active SSO connections: 1. Okta SAML (Status: ACTIVE, ID: conn_01H...) and 2. Azure AD OIDC (Status: ACTIVE, ID: conn_01I...). Both links are healthy and operational.
```

**Prompt:** 
```
List all users synced from the directory 'dir_01J...'.
```

**Response:** 
```
I found 120 users in directory dir_01J.... The most recently synced users are: 1. John Doe (john@acme.com), 2. Jane Smith (jane@acme.com), and 3. Robert Brown (robert@acme.com). Would you like to see the full roster or filter by group?
```

## Capabilities

### Audit Security Events
The agent streams detailed historical events, letting you monitor who accessed what and when across any organization.

### Manage Organization Structure
You can list all existing organizations or create new ones by specifying the name and authorized domains.

### Monitor SSO Health
The MCP lists all active Single Sign-On connections, allowing you to check the status of critical enterprise authentication links.

### Check Directory Sync Status
You get metadata and sync details for connected directories from providers like Okta or Azure AD.

### List User Rosters and Groups
The agent retrieves complete lists of users and groups synced into WorkOS from your external directory.

## Use Cases

### Investigating Unauthorized Access
A security team member needs to know if a particular client's account was accessed last month. Instead of manually building complex queries, they ask the agent to `get_audit_log_events` for that organization ID and immediately see the stream of access attempts.

### Pre-launch Governance Check
A Product Manager is launching a new enterprise feature. They first use `list_workos_organizations` to confirm every tenant is accounted for, then call `get_directory_details` on the primary directory ID to ensure sync readiness.

### Troubleshooting Sync Breakage
An engineer notices user groups are missing. They use `list_directories` to confirm which sync source is down, and then call `list_directory_groups` using the correct directory ID to verify group membership.

### Client Onboarding Setup
A support specialist needs to set up a new client. They use `create_workos_organization`, providing the necessary name and authorized domains, completing the initial setup in seconds.

## Benefits

- Audit logs: Instead of navigating through complex security dashboards to find an event, you ask for it. The agent streams detailed audit log events instantly.
- Directory Sync: You can check the metadata and status of all connected directory instances (like Okta or Azure AD) without clicking into each one individually.
- User Rosters: Needing a list of users? Use the MCP to pull complete user lists or specific group rosters from your synced directories, saving minutes of manual data compilation.
- SSO Management: Quickly get a full count and status update on all active Single Sign-On connections using `list_sso_connections`, keeping your authentication links healthy.
- Organization Mapping: When you're planning a new deployment, use the MCP to list all existing organizations or even create new ones with specific authorized domains.

## How It Works

The bottom line is that your AI agent becomes your identity administrator, eliminating the need to manually browse WorkOS dashboards.

1. Subscribe to this MCP on Vinkius, then provide your API Key.
2. Connect the credential to your preferred AI client (like Cursor or Claude).
3. Ask your agent a question, like 'List all organizations' or 'Check SSO status for Acme Corp', and get immediate answers.

## Frequently Asked Questions

**How do I list all organizations using WorkOS MCP?**
You use `list_workos_organizations` to get a complete roster of every tenant in your account. This is the fastest way to see how many organizational records you're dealing with.

**Can I check SSO connections status with WorkOS MCP?**
Yes, running `list_sso_connections` gives you a full list of all configured SAML and OIDC links. You can follow up by using `get_sso_connection_details` for deeper troubleshooting.

**What is the difference between listing users and groups in WorkOS MCP?**
Use `list_directory_users` when you need a roster of individual accounts (like John Doe). Use `list_directory_groups` if you only care about membership lists, such as 'IT Admin Group'.

**Does WorkOS MCP help with compliance auditing?**
Absolutely. You use `get_audit_log_events` to stream historical security data for any organization, which is crucial for proving who did what and when.

**How do I create a new organization record via the MCP?**
You run the `create_workos_organization` tool. You must provide both the desired name and the list of authorized domains to complete the process.