1# WorkOS Authentication
2 
3Setting up OAuth with WorkOS AuthKit. DCR mode only — MCP clients register themselves directly with WorkOS; the MCP server just verifies the resulting tokens.
4 
5**Learn more:** [WorkOS AuthKit MCP docs](https://workos.com/docs/authkit/mcp) · [Standalone starter template](https://github.com/mcp-use/mcp-oauth-workos-template) · [Runnable example](https://github.com/mcp-use/mcp-use/tree/main/libraries/typescript/packages/mcp-use/examples/server/oauth/workos)
6 
7---
8 
9## Quick Start
10 
11```typescript
12import { MCPServer, oauthWorkOSProvider, object } from "mcp-use/server";
13 
14const server = new MCPServer({
15  name: "my-server",
16  version: "1.0.0",
17  oauth: oauthWorkOSProvider(),
18});
19 
20server.tool(
21  { name: "whoami", description: "Get authenticated user info" },
22  async (_args, ctx) =>
23    object({
24      userId: ctx.auth.user.userId,
25      email: ctx.auth.user.email,
26      name: ctx.auth.user.name,
27    })
28);
29 
30server.listen();
31```
32 
33With a `.env` file:
34 
35```bash
36MCP_USE_OAUTH_WORKOS_SUBDOMAIN=your-company.authkit.app
37```
38 
39That's it. JWT verification, OAuth discovery, and `.well-known` passthrough are handled automatically.
40 
41---
42 
43## Setup
44 
451. Sign up at the [WorkOS Dashboard](https://dashboard.workos.com/) and create a project.
462. **Connect → Configuration** — enable **Dynamic Client Registration**.
473. **Configuration → Redirects** — add your MCP client redirect URI (e.g. `http://localhost:3000/callback`).
484. Copy the full AuthKit domain from **Domains → AuthKit Domain** (e.g. `your-company.authkit.app` — including `.authkit.app`, not just `your-company`).
49 
50---
51 
52## Environment Variables
53 
54| Variable | Required | Description |
55|----------|----------|-------------|
56| `MCP_USE_OAUTH_WORKOS_SUBDOMAIN` | Yes | Full AuthKit domain (e.g. `my-company.authkit.app`) |
57 
58> If you also need to call the WorkOS Management API from a tool handler, store the API key in any env var you like (e.g. `WORKOS_API_KEY`) and read it inside the tool. It's **not** part of the OAuth provider config anymore.
59 
60---
61 
62## Configuration Options
63 
64Zero-config (reads from env vars):
65 
66```typescript
67oauth: oauthWorkOSProvider()
68```
69 
70Explicit config (overrides env vars):
71 
72```typescript
73oauth: oauthWorkOSProvider({
74  subdomain: "my-company.authkit.app",
75  verifyJwt: process.env.NODE_ENV === "production",  // default: true
76  scopesSupported: ["email", "offline_access", "openid", "profile"],  // override advertised scopes
77})
78```
79 
80| Option | Type | Default | Description |
81|--------|------|---------|-------------|
82| `subdomain` | `string` | env var | Full AuthKit domain (e.g., `my-company.authkit.app`) |
83| `verifyJwt` | `boolean?` | `true` | Set `false` to skip JWT verification (**development only**) |
84| `scopesSupported` | `string[]?` | `["email", "offline_access", "openid", "profile"]` | Override advertised scopes |
85 
86---
87 
88## User Context
89 
90WorkOS populates these fields on `ctx.auth.user`:
91 
92| Field | Type | Source |
93|-------|------|--------|
94| `userId` | `string` | `sub` claim |
95| `email` | `string?` | `email` claim |
96| `name` | `string?` | `name` claim |
97| `username` | `string?` | `preferred_username` claim |
98| `picture` | `string?` | `picture` claim |
99| `roles` | `string[]?` | `roles` claim |
100| `permissions` | `string[]?` | `permissions` claim |
101| `email_verified` | `boolean?` | `email_verified` claim |
102| `organization_id` | `string?` | `org_id` claim — multi-tenant org ID |
103| `sid` | `string?` | Session ID |
104 
105### Role-Based Access
106 
107```typescript
108server.tool(
109  { name: "admin-action", description: "Admin-only operation" },
110  async (_args, ctx) => {
111    if (!ctx.auth.user.roles?.includes("admin")) {
112      return error("Forbidden: admin role required");
113    }
114 
115    // ... admin logic
116    return text("Done");
117  }
118);
119```
120 
121### Multi-Tenant Filtering
122 
123Scope queries to the authenticated user's organization:
124 
125```typescript
126server.tool(
127  { name: "get-documents", description: "Get documents for the authenticated org" },
128  async (_args, ctx) => {
129    // Custom claims come back as `unknown` — narrow before use
130    const orgId = ctx.auth.user.organization_id as string | undefined;
131    if (!orgId) return error("Organization context required");
132 
133    const documents = await db.documents.findMany({
134      where: { organizationId: orgId },
135    });
136 
137    return object(documents);
138  }
139);
140```
141 
142---
143 
144## Making WorkOS API Calls
145 
146Use a WorkOS API key (not the user's access token) for management API calls:
147 
148```typescript
149const WORKOS_API_KEY = process.env.WORKOS_API_KEY;
150 
151server.tool(
152  { name: "get-workos-user", description: "Fetch user profile from WorkOS" },
153  async (_args, ctx) => {
154    if (!WORKOS_API_KEY) return error("WorkOS API key not configured");
155 
156    const res = await fetch(
157      `https://api.workos.com/user_management/users/${ctx.auth.user.userId}`,
158      {
159        headers: {
160          Authorization: `Bearer ${WORKOS_API_KEY}`,
161          "Content-Type": "application/json",
162        },
163      }
164    );
165 
166    if (!res.ok) return error(`WorkOS API failed: ${res.status}`);
167    return object(await res.json());
168  }
169);
170```
171 
172---
173 
174## Example `.env`
175 
176```bash
177# Required: Full AuthKit domain (WorkOS Dashboard → Domains → AuthKit Domain)
178MCP_USE_OAUTH_WORKOS_SUBDOMAIN=my-company.authkit.app
179 
180# Optional: WorkOS API key if you call the Management API from tools
181WORKOS_API_KEY=sk_test_...
182```
183 
184---
185 
186## Troubleshooting
187 
188### Redirect URI Mismatch
189 
190If you get a redirect URI error during OAuth, add your client's callback URL to WorkOS:
191 
1921. WorkOS Dashboard → **Developer** → **Redirects**
1932. Click **Edit redirect URIs** and add the one the client expects (e.g. `http://localhost:3000/oauth/callback`).
194 
195Changes may take a few minutes to propagate.
196 
197### DCR Not Registering
198 
199If the MCP Inspector stalls at the registration step, double-check that **Dynamic Client Registration** is enabled in WorkOS Dashboard → **Connect → Configuration**. Without DCR enabled, there's no pre-configured `client_id` for the Inspector to use.
200 
201---
202 
203## Next Steps
204 
205- **Auth overview** → [overview.md](overview.md)
206- **Supabase setup** → [supabase.md](supabase.md)
207- **Auth0 setup** → [auth0.md](auth0.md)
208- **Build tools** → [../server/tools.md](../server/tools.md)
209