1# Clerk Authentication
2 
3Setting up OAuth with Clerk. DCR mode only — MCP clients register themselves directly with Clerk via Dynamic Client Registration; the MCP server only verifies the resulting JWTs against Clerk's JWKS.
4 
5**Learn more:** [Clerk OAuth Docs](https://clerk.com/docs/guides/configure/auth-strategies/oauth/how-clerk-implements-oauth) · [Runnable example](https://github.com/mcp-use/mcp-use/tree/main/libraries/typescript/packages/mcp-use/examples/server/oauth/clerk)
6 
7---
8 
9## Quick Start
10 
11```typescript
12import { MCPServer, oauthClerkProvider, object } from "mcp-use/server";
13 
14const server = new MCPServer({
15  name: "my-server",
16  version: "1.0.0",
17  oauth: oauthClerkProvider(),
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
36# Development:  https://[verb-noun-##].clerk.accounts.dev
37# Production:   https://clerk.[YOUR_APP_DOMAIN].com
38MCP_USE_OAUTH_CLERK_FRONTEND_API_URL=https://verb-noun-42.clerk.accounts.dev
39```
40 
41That's it. JWT verification, OAuth discovery, and `.well-known` passthrough are handled automatically.
42 
43---
44 
45## Setup
46 
471. Sign up at [clerk.com](https://clerk.com) and create an application.
482. **Clerk Dashboard → Configure → OAuth Applications** — enable **Dynamic Client Registration**. This is required for MCP clients to self-register.
493. **Clerk Dashboard → Configure → API Keys** — copy the **Frontend API URL** (shown in the `.env.local` quickstart).
50   - Development example: `https://verb-noun-42.clerk.accounts.dev`
51   - Production example: `https://clerk.yourdomain.com`
52 
53---
54 
55## Environment Variables
56 
57| Variable | Required | Description |
58|----------|----------|-------------|
59| `MCP_USE_OAUTH_CLERK_FRONTEND_API_URL` | Yes | Clerk Frontend API URL (e.g. `https://verb-noun-42.clerk.accounts.dev`) |
60 
61---
62 
63## Configuration Options
64 
65Zero-config (reads from env vars):
66 
67```typescript
68oauth: oauthClerkProvider()
69```
70 
71Explicit config (overrides env vars):
72 
73```typescript
74oauth: oauthClerkProvider({
75  frontendApiUrl: "https://verb-noun-42.clerk.accounts.dev",
76  verifyJwt: process.env.NODE_ENV === "production",  // default: true
77})
78```
79 
80| Option | Type | Default | Description |
81|--------|------|---------|-------------|
82| `frontendApiUrl` | `string` | env var | Clerk Frontend API URL |
83| `verifyJwt` | `boolean?` | `true` | Set `false` to skip JWT verification (**development only**) |
84 
85---
86 
87## User Context
88 
89Clerk populates these fields on `ctx.auth.user`:
90 
91| Field | Type | Source |
92|-------|------|--------|
93| `userId` | `string` | `sub` claim |
94| `email` | `string?` | `email` claim |
95| `name` | `string?` | `name` claim |
96| `roles` | `string[]?` | `roles` claim |
97| `permissions` | `string[]?` | `permissions` claim |
98 
99### Organization Context
100 
101Clerk includes the active organization on the JWT payload. The fields are non-standard, so cast off `ctx.auth.user`:
102 
103```typescript
104server.tool(
105  { name: "get-organization-info", description: "Get the active organization" },
106  async (_args, ctx) => {
107    const { org_id, org_role, org_slug } = ctx.auth.user as {
108      org_id?: string;
109      org_role?: string;
110      org_slug?: string;
111    };
112 
113    if (!org_id) {
114      return error("No active organization. Select one in Clerk first.");
115    }
116 
117    return object({ org_id, org_role, org_slug });
118  }
119);
120```
121 
122---
123 
124## Common Mistakes
125 
126- **DCR not enabled** — If MCP Inspector stalls at the registration step, confirm **Dynamic Client Registration** is enabled in Clerk Dashboard → Configure → OAuth Applications. Without DCR, there is no `client_id` for MCP clients to obtain.
127- **Wrong Frontend API URL** — Must be the full URL (with `https://`), not just the subdomain.
128- **Skipping JWT verification in production** — `verifyJwt: false` is development only.
129 
130---
131 
132## Next Steps
133 
134- **Auth overview** → [overview.md](overview.md)
135- **Auth0 setup** → [auth0.md](auth0.md)
136- **WorkOS setup** → [workos.md](workos.md)
137- **Build tools** → [../server/tools.md](../server/tools.md)
138