1# Authentication
2 
3Adding OAuth 2.0/2.1 authentication to your MCP server.
4 
5**Use for:** Protecting tools behind user authentication, accessing user identity in tool handlers, integrating with identity providers (Auth0, Better Auth, WorkOS, Supabase, Keycloak, Google, GitHub, Okta, Azure AD, and more).
6 
7> **Two integration modes.** Pick by whether your identity provider supports Dynamic Client Registration (DCR):
8> - **Remote auth** (`oauthAuth0Provider`, `oauthBetterAuthProvider`, `oauthKeycloakProvider`, `oauthSupabaseProvider`, `oauthWorkOSProvider`, `oauthCustomProvider`) — clients register and authenticate directly with the upstream provider; your server only verifies the resulting bearer token. Requires DCR on the upstream.
9> - **OAuth proxy** (`oauthProxy` + `jwksVerifier`) — your server holds pre-registered client credentials and mediates the token exchange. Use this for Google, GitHub, Okta, Azure AD, or any provider where you register the app in a dashboard and receive a fixed `clientId` / `clientSecret`.
10 
11---
12 
13## How It Works
14 
15Pass an OAuth provider to the `oauth` option on `MCPServer`:
16 
17```typescript
18import { MCPServer } from "mcp-use/server";
19 
20const server = new MCPServer({
21  name: "my-server",
22  version: "1.0.0",
23  oauth: yourProvider(),  // see provider-specific guides
24});
25```
26 
27This single property:
28- Protects all `/mcp/*` routes with bearer token authentication
29- Verifies tokens on every request (JWT + JWKS by default)
30- Sets up OAuth discovery endpoints (`/.well-known/oauth-authorization-server`, `/.well-known/openid-configuration`, `/.well-known/oauth-protected-resource`)
31- In proxy mode, also sets up `/register`, `/authorize`, and `/token` endpoints that mediate the upstream flow
32- Populates `ctx.auth` in all tool/resource/prompt handlers
33 
34---
35 
36## Accessing User Context
37 
38Every tool handler receives `ctx.auth` when OAuth is enabled:
39 
40```typescript
41server.tool(
42  {
43    name: "get-profile",
44    description: "Get the authenticated user's profile",
45  },
46  async (_args, ctx) =>
47    object({
48      userId: ctx.auth.user.userId,
49      email: ctx.auth.user.email,
50      name: ctx.auth.user.name,
51    })
52);
53```
54 
55### `ctx.auth` Shape
56 
57```typescript
58ctx.auth.user            // UserInfo object (see below)
59ctx.auth.accessToken     // Raw bearer token string
60ctx.auth.scopes          // string[] — parsed from JWT `scope` claim
61ctx.auth.permissions     // string[] — parsed from JWT `permissions` claim
62ctx.auth.payload         // Raw JWT payload (all claims, Record<string, unknown>)
63```
64 
65### `ctx.auth.user` (UserInfo)
66 
67All providers populate these base fields:
68 
69| Field | Type | Description |
70|-------|------|-------------|
71| `userId` | `string` | Unique user identifier (`sub` claim) |
72| `email` | `string?` | User's email |
73| `name` | `string?` | Display name |
74| `username` | `string?` | Username |
75| `nickname` | `string?` | Nickname |
76| `picture` | `string?` | Avatar URL |
77| `roles` | `string[]?` | User roles |
78| `permissions` | `string[]?` | User permissions |
79 
80Providers may add extra fields (e.g., WorkOS adds `organization_id`, Keycloak adds `username`, Supabase adds `aal`). Access them via `ctx.auth.user.organization_id` or `ctx.auth.payload` for raw claims.
81 
82### `ctx.auth.payload` (Raw Claims)
83 
84**Type:** `Record<string, unknown>` — values require explicit casts. Applies to **all providers** since `verifyToken` always returns `{ payload: Record<string, unknown> }`.
85 
86**Prefer typed accessors** (`ctx.auth.user.*`, `ctx.auth.scopes`, `ctx.auth.permissions`) over raw payload access. If your provider has non-standard claims, map them into typed `ctx.auth.user` fields via `getUserInfo` rather than casting in every tool handler:
87 
88```typescript
89// ✅ Preferred: map claims once in getUserInfo
90oauth: oauthCustomProvider({
91  // ...endpoints and verifyToken...
92  getUserInfo: (payload) => ({
93    userId: payload.sub as string,
94    email: payload.mail as string,
95    name: payload.display_name as string,
96    roles: (payload.groups as string[]) || [],
97  }),
98})
99 
100// Then access typed fields in tools:
101async (_args, ctx) => object({ email: ctx.auth.user.email })
102```
103 
104```typescript
105// ❌ Avoid: casting raw payload in every tool handler
106async (_args, ctx) => {
107  const exp = ctx.auth.payload.exp as number;  // unknown → number cast needed
108  return object({ expiresAt: new Date(exp * 1000).toISOString() });
109}
110```
111 
112If you must read raw claims (debugging or one-off provider-specific fields), cast explicitly:
113 
114```typescript
115const exp = ctx.auth.payload.exp as number | undefined;
116const customField = ctx.auth.payload.my_field as string;
117```
118 
119---
120 
121## Zero-Config Setup
122 
123All built-in remote-auth providers support zero-config via environment variables. Call the factory with no arguments and it reads from `MCP_USE_OAUTH_*` env vars:
124 
125```typescript
126oauth: oauthAuth0Provider()     // reads MCP_USE_OAUTH_AUTH0_*
127oauth: oauthWorkOSProvider()    // reads MCP_USE_OAUTH_WORKOS_*
128oauth: oauthSupabaseProvider()  // reads MCP_USE_OAUTH_SUPABASE_*
129oauth: oauthKeycloakProvider()  // reads MCP_USE_OAUTH_KEYCLOAK_*
130```
131 
132Or pass config explicitly to override env vars. See each provider's guide for available options.
133 
134`oauthProxy` and `oauthCustomProvider` have no zero-config mode — all endpoints must be passed explicitly.
135 
136---
137 
138## Available Providers
139 
140### Remote auth (DCR)
141 
142| Provider | Factory | Required Config | Guide |
143|----------|---------|-----------------|-------|
144| **Auth0** | `oauthAuth0Provider()` | `domain`, `audience` (env: `MCP_USE_OAUTH_AUTH0_DOMAIN`, `MCP_USE_OAUTH_AUTH0_AUDIENCE`) | [auth0.md](auth0.md) |
145| **Better Auth** | `oauthBetterAuthProvider({ authURL })` | `BETTER_AUTH_SECRET` | [better-auth.md](better-auth.md) |
146| **WorkOS** | `oauthWorkOSProvider()` | `subdomain` (env: `MCP_USE_OAUTH_WORKOS_SUBDOMAIN`) | [workos.md](workos.md) |
147| **Supabase** | `oauthSupabaseProvider()` | `projectId` (env: `MCP_USE_OAUTH_SUPABASE_PROJECT_ID`) | [supabase.md](supabase.md) |
148| **Keycloak** | `oauthKeycloakProvider()` | `serverUrl`, `realm` (env: `MCP_USE_OAUTH_KEYCLOAK_SERVER_URL`, `MCP_USE_OAUTH_KEYCLOAK_REALM`) | [keycloak.md](keycloak.md) |
149| **Custom (DCR)** | `oauthCustomProvider({ ... })` | `issuer`, endpoints, `verifyToken` | [custom.md](custom.md) |
150 
151### OAuth proxy (non-DCR)
152 
153| Use for | Factory | Guide |
154|---------|---------|-------|
155| Google, GitHub, Okta, Azure AD, Auth0 (non-EA), any pre-registered app | `oauthProxy({ ... })` + `jwksVerifier({ ... })` | [custom.md](custom.md#oauth-proxy-non-dcr-providers) |
156 
157---
158 
159## Making Authenticated API Calls
160 
161Use `ctx.auth.accessToken` to call your provider's API on behalf of the user:
162 
163```typescript
164server.tool(
165  { name: "fetch-data", description: "Fetch user data from API" },
166  async (_args, ctx) => {
167    const res = await fetch("https://api.example.com/me", {
168      headers: {
169        Authorization: `Bearer ${ctx.auth.accessToken}`,
170      },
171    });
172 
173    if (!res.ok) {
174      return error(`API call failed: ${res.status}`);
175    }
176 
177    return object(await res.json());
178  }
179);
180```
181 
182Provider-specific examples (Supabase, Keycloak, Auth0, etc.) live in each provider's guide.
183 
184---
185 
186## Common Mistakes
187 
188- **Wrong `ctx.auth` shape** — User info is nested: `ctx.auth.user.email`, not `ctx.auth.email`
189- **Using `oauthCustomProvider` for non-DCR providers** — For Google, GitHub, Okta, Azure AD, etc., use `oauthProxy` + `jwksVerifier` instead. `oauthCustomProvider` only works with providers that advertise a `registration_endpoint`.
190- **Custom `verifyToken` returning the wrong shape** — It must resolve to `{ payload: Record<string, unknown> }` or throw. The proxy surfaces `payload` to `getUserInfo` and to `ctx.auth`.
191- **Hardcoding provider credentials** — Use env vars; never commit secrets
192- **Skipping JWT verification in production** — `verifyJwt: false` is development only
193- **Throwing errors instead of returning `error()`** — Use the `error()` response helper for auth-related failures
194 
195---
196 
197## Next Steps
198 
199- **Auth0 setup** → [auth0.md](auth0.md)
200- **Better Auth setup** → [better-auth.md](better-auth.md)
201- **WorkOS setup** → [workos.md](workos.md)
202- **Supabase setup** → [supabase.md](supabase.md)
203- **Keycloak setup** → [keycloak.md](keycloak.md)
204- **Custom provider / OAuth proxy** → [custom.md](custom.md)
205- **Build tools** → [../server/tools.md](../server/tools.md)
206- **See examples** → [../patterns/common-patterns.md](../patterns/common-patterns.md)
207