WorkOS MCP Server

The WorkOS MCP server is a remote management Model Context Protocol server that lets MCP-compatible AI agents act on your WorkOS workspace. Once connected, your agent can read and change the same dashboard data you can (managing organizations, connections, users, branding, and more) by calling the WorkOS API on your behalf.

If you are instead building your own MCP server and want to secure it with OAuth, see AuthKit for MCP.

The MCP server acts as you: it inherits your dashboard role and can only do what your account is allowed to do. See Permissions for details.

Every client connects over streamable HTTP and authenticates with OAuth using WorkOS Connect. The first time you connect, your client opens a WorkOS consent screen where you sign in and approve access. After you approve, the agent is connected as your account.

Pick your client below for setup steps.

{
  "mcpServers": {
    "workos": {
      "serverUrl": "https://mcp.workos.com/mcp"
    }
  }
}

claude mcp add --transport http workos https://mcp.workos.com/mcp

codex mcp add workos --url https://mcp.workos.com/mcp
codex mcp get workos
codex mcp login workos
codex mcp list

[mcp_servers.workos]
url = "https://mcp.workos.com/mcp"

codex mcp get workos
codex mcp login workos
codex mcp list

{
  "mcpServers": {
    "workos": {
      "url": "https://mcp.workos.com/mcp"
    }
  }
}

{
  "mcpServers": {
    "workos": {
      "type": "http",
      "url": "https://mcp.workos.com/mcp"
    }
  }
}

{
  "mcp": {
    "workos": {
      "type": "remote",
      "url": "https://mcp.workos.com/mcp",
      "enabled": true
    }
  }
}

{
  "servers": {
    "workos": {
      "type": "http",
      "url": "https://mcp.workos.com/mcp"
    }
  }
}

{
  "mcpServers": {
    "workos": {
      "serverUrl": "https://mcp.workos.com/mcp"
    }
  }
}

{
  "context_servers": {
    "workos": {
      "source": "custom",
      "url": "https://mcp.workos.com/mcp"
    }
  }
}

If Codex reports MCP startup interrupted. The following servers were not initialized: workos, the server may be configured but not authenticated.

1. Run codex mcp get workos from the project where you expect the server to be available. If Codex cannot find it, check that you are in the intended repository and that Codex trusts the project, or use the user-global setup above.
2. Run codex mcp login workos and complete the WorkOS consent flow in your browser.
3. Run codex mcp list to verify the server endpoint and OAuth authentication type.
4. Restart Codex so the current session can initialize the authenticated server.

Run browser, credential-store, and certificate-sensitive authentication commands from your normal host shell. An authentication failure that occurs only inside an isolated agent environment does not prove that the WorkOS MCP server is unavailable.

If authentication succeeds but WorkOS access remains disabled, ask a team admin to check the WorkOS MCP controls in the team authentication settings.

The MCP server never grants more access than you already have.

When you connect, the agent authenticates as your dashboard account and assumes your exact role and permissions. Every operation runs through the same access controls that govern the dashboard, so the agent can only read and change what you can. A member without admin rights can’t use the agent to perform admin-only actions, and a read-only role can’t make any changes at all.

The agent works against one environment at a time, so it can’t accidentally change the wrong one. It defaults to a sandbox environment and only operates on production when you direct it to. Switching to production never escalates your access. The agent can only reach environments you already have access to in the dashboard, and your team’s admins can block production entirely.

Irreversible operations, like deleting an organization, connection, or directory, aren’t executed on the first attempt. Instead, the agent receives a description of exactly what the operation will destroy and must explicitly confirm before it runs. This gives you a chance to review the consequences, so a single ambiguous prompt can’t wipe out data.

Values like API keys and client secrets are stripped from responses before they ever reach the agent, so they can’t leak into its context or be echoed back in a chat transcript. Stripping only applies to returned values, so the agent can still set a secret value you provide without being able to read existing ones back.

Team admins can restrict or completely disable MCP access for the whole team from the team authentication settings page. Three settings can be toggled independently, and all are enabled by default:

• Enable: Allow this team to access the WorkOS dashboard over MCP. Turning this off disables MCP for the team entirely, which also disables the two settings below.

• Allow production access: Allow agents to access production environments. When off, MCP can only reach sandbox environments. This never escalates anyone’s permissions: agents can still only reach production for members who already have production access in the dashboard.

• Allow write access: Allow agents to perform write operations. When off, MCP is restricted to read-only operations.

Connect an agent and describe what you want in plain language. The agent discovers the right operations and runs them for you. Here are a few examples.

Brand your sign-in page from a screenshot

Here’s a screenshot of our marketing site. Make our AuthKit sign-in page match its overall aesthetic.

Debug a sign-in problem

Help me understand why org_123 is having trouble signing in with SSO.

Onboard a new customer

Set up a new organization for Acme Corp and invite everyone in acme_employees.csv.

Understand your users

Show me recent suspicious sign-in attempts and where they came from.

Manage a user

Invite bob@example.com to org_123 as an admin.

Audit your configuration

List every organization with a draft SSO connection, and flag any directories that haven’t synced in 24 hours.

Stream audit logs

Set up a Datadog audit log stream for our production environment.

These are just starting points. Try to give agents tasks that you typically do in the dashboard.

Some dashboard capabilities are intentionally unavailable over MCP.

• No impersonation. The dashboard’s user impersonation isn’t exposed to agents, and mutations are blocked on impersonated sessions. An agent always acts as you. It can’t act as one of your users.

• Not every dashboard action. The agent works with the operations WorkOS has enabled for MCP (managing organizations, connections, users, branding, and more), but the most sensitive actions are intentionally left out. It can’t change the MCP access settings that govern its own access, mint or rotate credentials such as API keys, OAuth client secrets, and signing certificates, or delete your WorkOS team.

• One team at a time. The agent is scoped to the team you authenticate with. It can’t read or change resources belonging to another team.