Manage WorkOS organizations, users, SSO connections, directories, and AuthKit branding through the WorkOS API.
Also known as workos/skills, mcp
- Stars
- 46
- Tools
- 5
- Downloads, 30 days
- —
- Latest version
- 1.0.0
- Last commit
- Nov 2, 2026
- License
- MIT
What is WorkOS MCP?
WorkOS manages WorkOS organizations, users, SSO connections, directories, and AuthKit branding through the WorkOS API. It exposes 5 tools, such as whoami, list_operations, query.
Summary generated from the project's README
About WorkOS MCP server
Managing WorkOS organizations, users, and SSO connections through an AI agent is possible with this remote MCP server. It allows developers to control workspace settings, directory sync, AuthKit branding, and webhooks by calling the WorkOS API directly from their preferred AI client. The server runs as a hosted service and uses OAuth 2.1 with Dynamic Client Registration, meaning you do not need to paste any API keys to get started.
Users can connect via the WorkOS CLI to target agents like Claude Code, Codex, or Cursor. It is also compatible with GitHub Copilot, VS Code, Claude Desktop, and ChatGPT by adding the remote server URL. The agent inherits your specific dashboard role, ensuring it can only perform actions permitted by your account. For safety, the server defaults to a sandbox environment and requires explicit confirmation for irreversible operations like deleting an organization or connection.
What you can do with it
- 1Provisioning new organizationsAsk the agent to create a new organization and invite a group of users from a file.
- 2Troubleshooting SSO issuesUse the agent to investigate why a specific organization is experiencing sign-in difficulties.
- 3Updating AuthKit brandingRequest the agent to modify your sign-in page appearance to match a specific design.
- 4Auditing directory synchronizationIdentify organizations with draft connections or directories that have failed to sync recently.
Written from the project's README. Every use case is checked against a quote from it.
How to install WorkOS MCP
Formats verified 10 Nov 2026Add to CursorAdd to GooseInstall WorkOS MCP in Claude Code
$ claude mcp add --transport http mcp https://mcp.workos.com/mcpInstall WorkOS MCP in Cursor
~/.cursor/mcp.json
{
"mcpServers": {
"mcp": {
"url": "https://mcp.workos.com/mcp"
}
}
}Install WorkOS MCP in VS Code
.vscode/mcp.json
{
"servers": {
"mcp": {
"type": "http",
"url": "https://mcp.workos.com/mcp"
}
}
}Install WorkOS MCP in VS Code CLI
$ code --add-mcp '{"name":"mcp","type":"http","url":"https://mcp.workos.com/mcp"}'Install WorkOS MCP in Codex
$ codex mcp add mcp --url https://mcp.workos.com/mcpInstall WorkOS MCP in Codex config.toml
~/.codex/config.toml
[mcp_servers.mcp] url = "https://mcp.workos.com/mcp"
Install WorkOS MCP in Gemini CLI
$ gemini mcp add -s user --transport http mcp https://mcp.workos.com/mcpInstall WorkOS MCP in Gemini settings.json
~/.gemini/settings.json
{
"mcpServers": {
"mcp": {
"url": "https://mcp.workos.com/mcp",
"type": "http"
}
}
}WorkOS MCP tools 5
Detected from the READMEwhoamilist_operationsquerymutatesetup_account
| whoami | — | |
| list_operations | — | |
| query | — | |
| mutate | — | |
| setup_account | — |
Automated checks
Ran Nov 12, 2026Full report →Passed our automated checks. That is not a security audit: read the code and give the server the narrowest access it needs. How checks work
- Source repository linked and reachablePass
- Open source license (OSI)Pass
- Commit or release in the last yearPass
- Package name not close to a popular packageNot checked
- Remote endpoint uses HTTPSPass
- Destructive tools are labelledPass
- No hidden instructions to the modelPass
- No critical advisory in the package or its dependenciesNot checked
README
View on GitHubWorkOS MCP Server
Manage your WorkOS workspace with AI agents. The WorkOS MCP server is a remote Model Context Protocol server. Any MCP client can use it to manage organizations, users, SSO connections, directories, branding, and more, by calling the WorkOS API on your behalf.
- Server URL:
https://mcp.workos.com/mcp - Transport: Streamable HTTP
- Auth: OAuth 2.1 with Dynamic Client Registration (WorkOS Connect). No API keys to paste.
- Docs: https://workos.com/docs/mcp
This folder holds the registry metadata (server.json) for the server. The
server runs as a hosted service at WorkOS. Its source is not published here.
The rest of this repository holds WorkOS skills for AI coding agents.
The server acts as you. It inherits your WorkOS dashboard role and can only do what your account can do.
Connect a client
The first time you connect, your client opens a WorkOS consent screen. Sign in and approve access. After that the agent is connected as your account.
WorkOS CLI (Claude Code, Codex, Cursor)
workos mcp install
The CLI detects installed clients. Use --agent claude-code, --agent codex,
or --agent cursor to target one. workos mcp status shows what is installed
and signed in.
GitHub Copilot / VS Code
Add the server to .vscode/mcp.json:
{
"servers": {
"workos": {
"type": "http",
"url": "https://mcp.workos.com/mcp"
}
}
}
Start the server from the mcp.json editor, or run MCP: List Servers from
the Command Palette.
Claude Code
claude mcp add --transport http workos https://mcp.workos.com/mcp
Use /mcp inside Claude Code to check status or sign in again.
Cursor
Add to ~/.cursor/mcp.json (global) or .cursor/mcp.json (per project):
{
"mcpServers": {
"workos": { "url": "https://mcp.workos.com/mcp" }
}
}
Open Settings → MCP and click Login next to WorkOS.
Codex CLI
codex mcp add workos --url https://mcp.workos.com/mcp
codex mcp login workos
Claude Desktop, ChatGPT
Open Settings → Connectors, click Add custom connector, name it
WorkOS, and enter https://mcp.workos.com/mcp.
Other clients
Add a remote MCP server with the URL https://mcp.workos.com/mcp. Setup steps
for Antigravity, Factory, Goose, OpenCode, Windsurf, and Zed are in the
docs.
Tools
| Tool | What it does |
|---|---|
whoami |
Returns your identity, role, and the environments you can reach. |
list_operations |
Lists the WorkOS operations available to the agent, with parameters. |
query |
Runs a read-only operation from the catalog, such as listing organizations or users. |
mutate |
Runs a write operation from the catalog, such as creating an organization or inviting a user. |
setup_account |
Provisions a WorkOS workspace for a first-time user. |
Operations cover organizations, users, SSO connections, Directory Sync, AuthKit branding, webhooks, feature flags, and more.
Example prompts
- "Set up a new organization for Acme Corp and invite everyone in
acme_employees.csv." - "Help me understand why
org_123is having trouble signing in with SSO." - "Invite
bob@example.comtoorg_123as an admin." - "List every organization with a draft SSO connection, and flag any directories that haven't synced in 24 hours."
- "Here's a screenshot of our marketing site. Make our AuthKit sign-in page match it."
- "Set up a Datadog audit log stream for our production environment."
Permissions and safety
- Role inheritance. The agent runs every operation through the same access controls as the dashboard. A read-only role cannot make changes.
- Environment scope. The agent works in one environment at a time. It defaults to a sandbox environment and only touches production when you say so.
- Destructive confirmation. Irreversible operations, such as deleting an organization, connection, or directory, return a description of what will be destroyed and require an explicit confirmation step before they run.
- Secrets. API keys, client secrets, and similar values are stripped from responses before they reach the agent.
- Admin controls. Team admins can disable MCP access, block production access, or make MCP read-only for the whole team from the team authentication settings.
Limitations
- No user impersonation.
- The most sensitive dashboard actions are not exposed: changing MCP access settings, minting or rotating credentials, and deleting your WorkOS team.
- One team at a time. The agent is scoped to the team you authenticate with.
Support
- Docs: https://workos.com/docs/mcp
- Support: support@workos.com
- Status: https://status.workos.com
Listings
server.json here is the source of truth for the com.workos/mcp entry in the
MCP Registry. Other directories are
tracked in LISTINGS.md.
WorkOS MCP questions
How do I add WorkOS MCP to Claude Code?
Run claude mcp add --transport http mcp https://mcp.workos.com/mcp in your terminal. Add --scope user to make it available in every project.
How do I add WorkOS MCP to Cursor?
Open ~/.cursor/mcp.json and add the server under mcpServers, using the Cursor config shown in the install section above.
What tools does WorkOS MCP provide?
It exposes 5 tools, including whoami, list_operations, query, mutate, setup_account.
How does the WorkOS MCP server authenticate?
It uses OAuth 2.1 with Dynamic Client Registration through WorkOS Connect, so you sign in through a consent screen instead of pasting API keys.
What permissions does the WorkOS MCP agent have?
The agent acts as your account and inherits your dashboard role, so a read-only role cannot make changes. It works in one environment at a time and defaults to a sandbox.
What can the WorkOS MCP server do?
It runs read-only and write operations covering organizations, users, SSO connections, Directory Sync, AuthKit branding, webhooks, and feature flags.
Does WorkOS MCP require confirmation for destructive actions?
Yes, irreversible operations like deleting an organization, connection, or directory return a description of what will be destroyed and require explicit confirmation first.