1# Custom & OAuth Proxy Authentication
2 
3Two factories cover everything that isn't a built-in provider:
4 
5- **`oauthCustomProvider`** — for identity providers that support **Dynamic Client Registration (DCR)** and advertise a `registration_endpoint` in their OAuth metadata. MCP clients register themselves directly with the upstream; your server only verifies tokens.
6- **`oauthProxy`** — for providers **without DCR** (Google, GitHub, Okta, Azure AD, standard Auth0 apps, etc.). You register an app in the provider's dashboard, pass the fixed `clientId` / `clientSecret` here, and your server mediates the token exchange.
7 
8> Picking between them: if your provider lists a `registration_endpoint` at `https://<provider>/.well-known/oauth-authorization-server`, use `oauthCustomProvider`. Otherwise use `oauthProxy`.
9 
10---
11 
12## `oauthCustomProvider` (DCR)
13 
14Use this when your identity provider supports DCR and advertises a `registration_endpoint`. Clients discover the endpoints and register themselves against the upstream.
15 
16```typescript
17import { MCPServer, oauthCustomProvider, object } from "mcp-use/server";
18import { jwtVerify, createRemoteJWKSet } from "jose";
19 
20const JWKS = createRemoteJWKSet(
21  new URL("https://auth.example.com/.well-known/jwks.json")
22);
23 
24const server = new MCPServer({
25  name: "my-server",
26  version: "1.0.0",
27  oauth: oauthCustomProvider({
28    issuer: "https://auth.example.com",
29    authEndpoint: "https://auth.example.com/oauth/authorize",
30    tokenEndpoint: "https://auth.example.com/oauth/token",
31 
32    async verifyToken(token) {
33      const result = await jwtVerify(token, JWKS, {
34        issuer: "https://auth.example.com",
35        audience: "your-audience",
36      });
37      return { payload: result.payload as Record<string, unknown> };
38    },
39 
40    getUserInfo(payload) {
41      return {
42        userId: payload.sub as string,
43        email: payload.email as string | undefined,
44        name: payload.name as string | undefined,
45        roles: (payload.roles as string[]) || [],
46      };
47    },
48  }),
49});
50 
51server.tool(
52  { name: "whoami", description: "Get authenticated user info" },
53  async (_args, ctx) =>
54    object({
55      userId: ctx.auth.user.userId,
56      email: ctx.auth.user.email,
57    })
58);
59 
60server.listen();
61```
62 
63### Configuration Options
64 
65```typescript
66oauthCustomProvider({
67  // Required: OAuth endpoints
68  issuer: "https://auth.example.com",
69  authEndpoint: "https://auth.example.com/oauth/authorize",
70  tokenEndpoint: "https://auth.example.com/oauth/token",
71 
72  // Required: must return { payload: Record<string, unknown> } or throw
73  async verifyToken(token) {
74    const { payload } = await jwtVerify(token, JWKS, { issuer: "..." });
75    return { payload: payload as Record<string, unknown> };
76  },
77 
78  // Optional
79  jwksUrl: "https://auth.example.com/.well-known/jwks.json",  // advertised in discovery metadata
80  userInfoEndpoint: "https://auth.example.com/userinfo",
81  scopesSupported: ["openid", "profile", "email"],
82  grantTypesSupported: ["authorization_code", "refresh_token"],
83  audience: "your-api-identifier",
84  getUserInfo: (payload) => ({
85    userId: payload.sub as string,
86    email: payload.email as string | undefined,
87    name: payload.name as string | undefined,
88  }),
89})
90```
91 
92| Option | Type | Required | Description |
93|--------|------|----------|-------------|
94| `issuer` | `string` | Yes | OAuth issuer URL |
95| `authEndpoint` | `string` | Yes | Authorization endpoint |
96| `tokenEndpoint` | `string` | Yes | Token endpoint |
97| `verifyToken` | `(token: string) => Promise<{ payload: Record<string, unknown> }>` | Yes | Token verification function |
98| `jwksUrl` | `string?` | No | JWKS endpoint advertised in discovery metadata |
99| `userInfoEndpoint` | `string?` | No | User info endpoint URL |
100| `scopesSupported` | `string[]?` | No | Default: `["openid", "profile", "email"]` |
101| `grantTypesSupported` | `string[]?` | No | Default: `["authorization_code", "refresh_token"]` |
102| `audience` | `string?` | No | Audience for JWT verification |
103| `getUserInfo` | `(payload) => UserInfo` | No | Custom user info extraction |
104 
105### Default Claim Extraction
106 
107Without `getUserInfo`, the provider extracts standard OIDC claims automatically:
108 
109| Field | Extracted From |
110|-------|---------------|
111| `userId` | `sub`, `user_id`, or `id` |
112| `email` | `email` |
113| `name` | `name` |
114| `username` | `username` or `preferred_username` |
115| `nickname` | `nickname` |
116| `picture` | `picture` or `avatar_url` |
117| `roles` | `roles` (if array) |
118| `permissions` | `permissions` (if array) |
119| `scopes` | Parsed from `scope` string |
120 
121Override if your provider uses non-standard claim names:
122 
123```typescript
124getUserInfo: (payload) => ({
125  userId: payload.user_id as string,
126  email: payload.mail as string,
127  name: payload.display_name as string,
128  roles: (payload.groups as string[]) || [],
129})
130```
131 
132---
133 
134## `oauthProxy` (non-DCR providers)
135 
136Use this for providers that don't support DCR — Google, GitHub, Okta, Azure AD, standard Auth0 Regular Web Apps, and anything else where you register an app in a dashboard and receive a fixed `clientId` / `clientSecret`.
137 
138The proxy flow:
139 
140```
141Client → /register  → MCP server returns the pre-registered client_id
142Client → /authorize → MCP server redirects to upstream /authorize
143Upstream → redirect → authorization code returned to the client
144Client → /token     → MCP server injects clientId + clientSecret, forwards to upstream
145Upstream → token    → returned to the client
146Client → /mcp/...   → MCP server verifies bearer via verifyToken()
147```
148 
149### `jwksVerifier` helper
150 
151Use `jwksVerifier` to build a standard JWT+JWKS `verifyToken`. It handles signature verification, issuer checking, and optional audience validation. Pair it with `oauthProxy` for any JWT-based provider.
152 
153```typescript
154import { oauthProxy, jwksVerifier } from "mcp-use/server";
155 
156oauthProxy({
157  // ...
158  verifyToken: jwksVerifier({
159    jwksUrl: "https://<provider>/.well-known/jwks.json",
160    issuer: "https://<provider>/",
161    audience: "your-audience",  // optional — enforces `aud` claim
162  }),
163})
164```
165 
166> `verifyToken` — whether from `jwksVerifier` or handwritten — **must resolve to `{ payload: Record<string, unknown> }`** or throw. The proxy surfaces `payload` to `getUserInfo` and to `ctx.auth.payload`.
167 
168For non-JWT providers (GitHub opaque tokens), write your own `verifyToken` that calls the provider's API — see [GitHub](#github-opaque-tokens) below.
169 
170### `oauthProxy` Options
171 
172| Option | Type | Required | Description |
173|--------|------|----------|-------------|
174| `authEndpoint` | `string` | Yes | Upstream authorization endpoint |
175| `tokenEndpoint` | `string` | Yes | Upstream token endpoint |
176| `issuer` | `string` | Yes | Token issuer (used in metadata and enforced by `jwksVerifier`) |
177| `clientId` | `string` | Yes | Pre-registered OAuth client ID |
178| `clientSecret` | `string?` | No | Client secret (omit for public clients) |
179| `verifyToken` | `VerifyToken` | Yes | Token verification — use `jwksVerifier()` or a custom function |
180| `scopes` | `string[]?` | No | Scopes to request. Default: `["openid", "email", "profile"]` |
181| `grantTypes` | `string[]?` | No | Default: `["authorization_code", "refresh_token"]` |
182| `extraAuthorizeParams` | `Record<string, string>?` | No | Extra query params on `/authorize` (e.g. `access_type`, `audience`, `prompt`) |
183| `getUserInfo` | `(payload) => UserInfo` | No | Custom user info extraction from the verified payload |
184 
185---
186 
187## Provider Examples (`oauthProxy`)
188 
189### Google
190 
191```typescript
192oauth: oauthProxy({
193  authEndpoint: "https://accounts.google.com/o/oauth2/v2/auth",
194  tokenEndpoint: "https://oauth2.googleapis.com/token",
195  issuer: "https://accounts.google.com",
196  clientId: process.env.GOOGLE_CLIENT_ID!,
197  clientSecret: process.env.GOOGLE_CLIENT_SECRET!,
198  scopes: ["openid", "email", "profile"],
199  extraAuthorizeParams: { access_type: "offline" },
200  verifyToken: jwksVerifier({
201    jwksUrl: "https://www.googleapis.com/oauth2/v3/certs",
202    issuer: "https://accounts.google.com",
203    audience: process.env.GOOGLE_CLIENT_ID!,
204  }),
205})
206```
207 
208### Okta
209 
210```typescript
211const oktaDomain = process.env.OKTA_DOMAIN!;  // e.g. "https://dev-123.okta.com"
212 
213oauth: oauthProxy({
214  authEndpoint: `${oktaDomain}/oauth2/default/v1/authorize`,
215  tokenEndpoint: `${oktaDomain}/oauth2/default/v1/token`,
216  issuer: `${oktaDomain}/oauth2/default`,
217  clientId: process.env.OKTA_CLIENT_ID!,
218  clientSecret: process.env.OKTA_CLIENT_SECRET,
219  scopes: ["openid", "email", "profile"],
220  verifyToken: jwksVerifier({
221    jwksUrl: `${oktaDomain}/oauth2/default/v1/keys`,
222    issuer: `${oktaDomain}/oauth2/default`,
223  }),
224})
225```
226 
227### Azure AD (Microsoft Entra ID)
228 
229```typescript
230const tenantId = process.env.AZURE_TENANT_ID!;
231const base = `https://login.microsoftonline.com/${tenantId}/v2.0`;
232 
233oauth: oauthProxy({
234  authEndpoint: `${base}/oauth2/v2.0/authorize`,
235  tokenEndpoint: `${base}/oauth2/v2.0/token`,
236  issuer: base,
237  clientId: process.env.AZURE_CLIENT_ID!,
238  clientSecret: process.env.AZURE_CLIENT_SECRET,
239  scopes: ["openid", "profile", "email"],
240  verifyToken: jwksVerifier({
241    jwksUrl: "https://login.microsoftonline.com/common/discovery/v2.0/keys",
242    issuer: base,
243    audience: process.env.AZURE_CLIENT_ID!,
244  }),
245})
246```
247 
248### Auth0 (Regular Web App, no Early Access)
249 
250For Auth0 with a standard Regular Web App (no DCR Early Access), use the proxy. See [auth0.md](auth0.md) for the full guide.
251 
252```typescript
253const domain = process.env.AUTH0_DOMAIN!;
254const audience = process.env.AUTH0_AUDIENCE ?? "";
255 
256oauth: oauthProxy({
257  authEndpoint: `https://${domain}/authorize`,
258  tokenEndpoint: `https://${domain}/oauth/token`,
259  issuer: `https://${domain}/`,
260  clientId: process.env.AUTH0_CLIENT_ID!,
261  clientSecret: process.env.AUTH0_CLIENT_SECRET,
262  scopes: ["openid", "email", "profile"],
263  extraAuthorizeParams: { audience },
264  verifyToken: jwksVerifier({
265    jwksUrl: `https://${domain}/.well-known/jwks.json`,
266    issuer: `https://${domain}/`,
267    audience,
268  }),
269})
270```
271 
272### GitHub (opaque tokens)
273 
274GitHub uses non-JWT opaque tokens. Use a custom `verifyToken` that calls the GitHub API instead of `jwksVerifier`:
275 
276```typescript
277oauth: oauthProxy({
278  authEndpoint: "https://github.com/login/oauth/authorize",
279  tokenEndpoint: "https://github.com/login/oauth/access_token",
280  issuer: "https://github.com",
281  clientId: process.env.GITHUB_CLIENT_ID!,
282  clientSecret: process.env.GITHUB_CLIENT_SECRET!,
283  scopes: ["read:user", "user:email"],
284 
285  // GitHub uses opaque tokens — validate by calling the API
286  async verifyToken(token) {
287    const res = await fetch("https://api.github.com/user", {
288      headers: {
289        Authorization: `Bearer ${token}`,
290        "User-Agent": "my-mcp-server",
291      },
292    });
293    if (!res.ok) throw new Error("Invalid GitHub token");
294    const user = await res.json();
295    return { payload: { sub: String(user.id), ...user } };
296  },
297 
298  getUserInfo(payload) {
299    return {
300      userId: payload.sub as string,
301      username: payload.login as string | undefined,
302      name: payload.name as string | undefined,
303      email: payload.email as string | undefined,
304      picture: payload.avatar_url as string | undefined,
305    };
306  },
307})
308```
309 
310---
311 
312## Accessing user info in tools
313 
314```typescript
315server.tool(
316  { name: "get-user-info", description: "Get authenticated user info" },
317  async (_args, ctx) =>
318    object({
319      userId: ctx.auth.user.userId,
320      email: ctx.auth.user.email,
321      name: ctx.auth.user.name,
322      scopes: ctx.auth.scopes,
323    })
324);
325```
326 
327---
328 
329## Common Mistakes
330 
331- **Using `oauthCustomProvider` for Google / GitHub / Okta / Azure AD** — those don't support DCR. Use `oauthProxy` instead.
332- **`verifyToken` returning the wrong shape** — must resolve to `{ payload: Record<string, unknown> }` or throw. Returning `jwtVerify`'s raw result doesn't satisfy this in TypeScript — cast explicitly: `return { payload: result.payload as Record<string, unknown> }`.
333- **Forgetting `audience` for JWT verification** — most providers issue per-client tokens; without `audience` in `jwksVerifier`, tokens from other clients could be accepted.
334- **Missing `extraAuthorizeParams`** — Google needs `access_type: "offline"` for refresh tokens; Auth0 needs `audience` to issue JWT access tokens instead of opaque ones.
335 
336---
337 
338## Resources
339 
340- [`jose` library](https://github.com/panva/jose) — JWT verification primitives (already a dependency of `mcp-use`)
341- [OAuth 2.1 Specification](https://oauth.net/2.1/)
342- [OIDC Specification](https://openid.net/specs/openid-connect-core-1_0.html)
343- [Runnable Auth0 proxy example](https://github.com/mcp-use/mcp-use/tree/main/libraries/typescript/packages/mcp-use/examples/server/oauth/auth0-proxy)
344 
345---
346 
347## Next Steps
348 
349- **Auth overview** → [overview.md](overview.md)
350- **Auth0 setup** → [auth0.md](auth0.md)
351- **WorkOS setup** → [workos.md](workos.md)
352- **Supabase setup** → [supabase.md](supabase.md)
353- **Keycloak setup** → [keycloak.md](keycloak.md)
354- **Build tools** → [../server/tools.md](../server/tools.md)
355