How to Use the WorkOS MCP in Claude

Q: How do I check directory sync status using WorkOS and Claude Desktop?

You can use listdirectories to see all active Directory Sync instances. This gives you a quick overview of where your user data is coming from. It confirms which directories are currently feeding into the WorkOS platform.

Q: Where can I view records for multiple companies with WorkOS and Claude Desktop?

The listworkosorganizations tool lists every organization within your account. This is how you map out which business units are connected to the same central identity management system.

Q: Can I list all available groups with WorkOS and Claude Desktop?

Yes. You simply call listdirectorygroups. The tool gathers every group synced from a directory, making it easy for your agent to check permissions across the board.

Q: What happens if I need details on an Okta or Azure AD connection with WorkOS and Claude Desktop?

Use getdirectorydetails along with a directory ID. This retrieves specific metadata for that instance, letting you verify the health of your major identity provider connections.

Manage your enterprise identity and directories with Claude Desktop.

See Vinkius in Action

Works with every AI agent you already use

…and any MCP-compatible client

MCP Servers - Free for Subscribers

Connect WorkOS MCP to Claude Desktop

Create your Vinkius account to connect WorkOS to Claude Desktop and route execution through our secure gateway. The platform manages server hosting, runtime updates, and security layers. Configuration requires no manual server provisioning.

GDPR Free for Subscribers

Setup WorkOS with Claude Desktop

Ask AI about this MCP

ChatGPT

Claude

Perplexity

Get Organizational Details

Need to know specifics about an entire WorkOS account? Use `get_organization_details` to pull up all the metadata. You get key facts like billing info, associated domains, and organizational identifiers. This is crucial for setting up multi-region deployments or confirming which company instance you're working with before writing any code.

Sync Directory Information

Check what groups are synced from a specific directory. Calling `list_directory_groups` returns an exhaustive list of group names and IDs. This lets your agent verify if permissions were applied correctly across all necessary teams. If you need to see who belongs in those groups, the tool also gives access to `list_directory_users`, providing a roster of every synced user.

Handle SSO Connections

The `get_sso_connection_details` tool pulls all the necessary specs for an existing Single Sign-On connection. You get authentication parameters and endpoints right in your chat interface. This means you don't have to jump into a separate console just to confirm if the SSO link is still active or if its credentials changed.

Setup guide

Set up WorkOS MCP in Claude Web or Desktop

1

Open Claude Settings

Go to claude.ai, click your profile icon, then navigate to Customize → Connectors.
2

Add Custom Connector

Click the "+" button and select Add custom connector. Paste your Vinkius endpoint URL: https://edge.vinkius.com/[YOUR_TOKEN_HERE]/mcp Replace [YOUR_TOKEN_HERE] with your token from cloud.vinkius.com. For OAuth-protected servers, expand Advanced settings to add credentials.
3

Start a conversation

Open a new chat. The WorkOS MCP tools are available immediately — no restart needed.

Endpoint URL

https://edge.vinkius.com/[YOUR_TOKEN_HERE]/mcp

No configuration file needed — paste the URL directly in the Claude web interface.

Available on Free (1 connector), Pro, Max, Team, and Enterprise plans.

Prerequisites

Claude Desktop installed (macOS or Windows)
Active Vinkius subscription with a valid endpoint token

1

Open Claude Desktop Settings

Click the menu icon at the top-left corner, go to Settings → Developer → Edit Config. This opens claude_desktop_config.json in your default text editor.
2

Paste the WorkOS MCP configuration

Copy the JSON snippet on the right into the mcpServers object. Replace [YOUR_TOKEN_HERE] with your endpoint token from cloud.vinkius.com.
3

Restart Claude Desktop

Close and reopen the application. Claude needs a full restart to load new MCPs — refreshing a conversation is not enough.
4

Verify the connection

Open a new conversation. Click the 🔌 icon at the bottom of the message input. You should see tools listed under workos-mcp.

json

{
  "mcpServers": {
    "workos-mcp": {
      "url": "https://edge.vinkius.com/[YOUR_TOKEN_HERE]/mcp"
    }
  }
}

Get your connection token →

Independent Platform Disclaimer: Vinkius is an independent platform and is not affiliated with, endorsed by, sponsored by, verified by, or otherwise authorized by WorkOS. All third-party trademarks, logos, and brand names are the property of their respective owners. Their use on this website is strictly for informational purposes to identify service compatibility and interoperability.

Why Choose Vinkius

Vinkius connects your tools to AI with real-time monitoring and automatic cost savings — all from one dashboard.

Connect WorkOS now

Real-time monitoring

Live

visibility into every interaction

Connect your favorite tools to your AI and see exactly what's happening — every request, every response, in real time.

Built-in savings

60%

lower AI costs

Vinkius compresses data between your apps and your AI automatically. Lower bills every month — no configuration required.

Single dashboard

One

place for every integration

Every tool your AI connects to, managed from a single screen. One account, complete control.

Common questions about WorkOS MCP in Claude Desktop

You can use `list_directories` to see all active Directory Sync instances. This gives you a quick overview of where your user data is coming from. It confirms which directories are currently feeding into the WorkOS platform.

The `list_workos_organizations` tool lists every organization within your account. This is how you map out which business units are connected to the same central identity management system.

Yes. You simply call `list_directory_groups`. The tool gathers every group synced from a directory, making it easy for your agent to check permissions across the board.

Use `get_directory_details` along with a directory ID. This retrieves specific metadata for that instance, letting you verify the health of your major identity provider connections.

This server touches organization and user records. When working with sensitive directory information, always ensure your prompts are scoped only to the necessary IDs you need for the task at hand.

Use it with your favorite AI tools

Connect this server to Cursor, Claude, VS Code, and more.

OpenAI Agents SDK sdk-python

Google ADK sdk-python

Pydantic AI sdk-python

Vercel AI SDK sdk-typescript