1# Auth0 Authentication
2 
3Setting up OAuth with Auth0. Two modes depending on whether you have access to Auth0's DCR feature:
4 
5- **DCR (built-in)** → use `oauthAuth0Provider`. Requires Auth0's Early Access program.
6- **OAuth proxy** → use `oauthProxy` + `jwksVerifier` with a standard Auth0 Regular Web App. No Early Access required.
7 
8**Learn more:** [Auth0 MCP Authorization Guide](https://auth0.com/ai/docs/mcp/get-started/authorization-for-your-mcp-server) · [Standalone starter template](https://github.com/mcp-use/mcp-oauth-auth0-template) · [Runnable DCR example](https://github.com/mcp-use/mcp-use/tree/main/libraries/typescript/packages/mcp-use/examples/server/oauth/auth0) · [Runnable proxy example](https://github.com/mcp-use/mcp-use/tree/main/libraries/typescript/packages/mcp-use/examples/server/oauth/auth0-proxy)
9 
10---
11 
12## Mode 1: DCR (`oauthAuth0Provider`)
13 
14Auth0's built-in DCR feature is currently in **Early Access**. MCP clients register and authenticate directly with Auth0. To use this, join Auth0's Early Access program — see the [Auth0 MCP Authorization Guide](https://auth0.com/ai/docs/mcp/get-started/authorization-for-your-mcp-server).
15 
16### Setup
17 
181. **Auth0 Dashboard → Settings → Advanced** — enable **Resource Parameter Compatibility Profile**.
192. Promote connections to domain-level so third-party clients (like MCP Inspector) can use them:
20   ```bash
21   auth0 api get connections
22   auth0 api patch connections/YOUR_CONNECTION_ID --data '{"is_domain_connection": true}'
23   ```
243. Create an API with the `rfc9068_profile_authz` token dialect (this adds `permissions` to the access token):
25   ```bash
26   auth0 api post resource-servers --data '{
27     "identifier": "https://your-api.example.com",
28     "name": "MCP Tools API",
29     "signing_alg": "RS256",
30     "token_dialect": "rfc9068_profile_authz",
31     "enforce_policies": true,
32     "scopes": [{"value": "read:data", "description": "Read data"}]
33   }'
34   ```
35 
36### Quick Start
37 
38```typescript
39import { MCPServer, oauthAuth0Provider, object } from "mcp-use/server";
40 
41const server = new MCPServer({
42  name: "my-server",
43  version: "1.0.0",
44  oauth: oauthAuth0Provider(),  // reads MCP_USE_OAUTH_AUTH0_DOMAIN + _AUDIENCE
45});
46 
47server.tool(
48  { name: "whoami", description: "Get authenticated user info" },
49  async (_args, ctx) =>
50    object({
51      userId: ctx.auth.user.userId,
52      email: ctx.auth.user.email,
53      permissions: ctx.auth.permissions,
54    })
55);
56 
57server.listen();
58```
59 
60With a `.env` file:
61 
62```bash
63MCP_USE_OAUTH_AUTH0_DOMAIN=your-tenant.auth0.com
64MCP_USE_OAUTH_AUTH0_AUDIENCE=https://your-api.example.com
65```
66 
67### Configuration Options
68 
69Zero-config (reads from env vars):
70 
71```typescript
72oauth: oauthAuth0Provider()
73```
74 
75Explicit config:
76 
77```typescript
78oauth: oauthAuth0Provider({
79  domain: "your-tenant.auth0.com",
80  audience: "https://your-api.example.com",
81  verifyJwt: process.env.NODE_ENV === "production",  // default: true
82  scopesSupported: ["openid", "profile", "email", "offline_access"],
83})
84```
85 
86| Option | Type | Default | Description |
87|--------|------|---------|-------------|
88| `domain` | `string` | env var | Auth0 tenant domain (e.g. `your-tenant.auth0.com`) |
89| `audience` | `string` | env var | Auth0 API identifier |
90| `verifyJwt` | `boolean?` | `true` | Set `false` to skip JWT verification (**development only**) |
91| `scopesSupported` | `string[]?` | `["openid", "profile", "email", "offline_access"]` | Override advertised scopes |
92 
93---
94 
95## Mode 2: OAuth Proxy (`oauthProxy`)
96 
97Use a standard Auth0 **Regular Web Application** — no Early Access required. Your server mediates the token exchange using pre-registered credentials.
98 
99### Setup
100 
1011. **Auth0 Dashboard → Applications → Create Application** — choose **Regular Web Application**.
1022. Under **Allowed Callback URLs**, add your MCP client's redirect URI (e.g. `http://localhost:3000/inspector/oauth/callback`).
1033. Copy the **Client ID** and **Client Secret**.
1044. **APIs → Create API** — set an identifier (e.g. `https://my-mcp-api/`), leave signing as RS256. This is required so Auth0 issues **JWT** access tokens instead of opaque tokens.
105 
106### Quick Start
107 
108```typescript
109import { MCPServer, oauthProxy, jwksVerifier, object } from "mcp-use/server";
110 
111const domain = process.env.AUTH0_DOMAIN!;
112const audience = process.env.AUTH0_AUDIENCE ?? "";
113 
114const server = new MCPServer({
115  name: "my-server",
116  version: "1.0.0",
117  oauth: oauthProxy({
118    authEndpoint: `https://${domain}/authorize`,
119    tokenEndpoint: `https://${domain}/oauth/token`,
120    issuer: `https://${domain}/`,
121    clientId: process.env.AUTH0_CLIENT_ID!,
122    clientSecret: process.env.AUTH0_CLIENT_SECRET,
123    scopes: ["openid", "email", "profile"],
124    extraAuthorizeParams: { audience },  // required for JWT access tokens
125    verifyToken: jwksVerifier({
126      jwksUrl: `https://${domain}/.well-known/jwks.json`,
127      issuer: `https://${domain}/`,
128      audience,
129    }),
130  }),
131});
132 
133server.tool(
134  { name: "whoami", description: "Get authenticated user info" },
135  async (_args, ctx) =>
136    object({
137      userId: ctx.auth.user.userId,
138      email: ctx.auth.user.email,
139      scopes: ctx.auth.scopes,
140    })
141);
142 
143server.listen();
144```
145 
146With a `.env` file:
147 
148```bash
149AUTH0_DOMAIN=your-tenant.us.auth0.com
150AUTH0_CLIENT_ID=<from Regular Web App>
151AUTH0_CLIENT_SECRET=<from Regular Web App>
152AUTH0_AUDIENCE=https://my-mcp-api/
153```
154 
155> **Why `extraAuthorizeParams: { audience }`?** Without the `audience` parameter on `/authorize`, Auth0 issues opaque access tokens (no JWT, can't be verified locally). The audience turns it into a standard JWT signed by your API.
156 
157See [custom.md](custom.md) for full `oauthProxy` options.
158 
159---
160 
161## Accessing user info in tools
162 
163```typescript
164server.tool(
165  { name: "get-user-info", description: "Get authenticated user info" },
166  async (_args, ctx) =>
167    object({
168      userId: ctx.auth.user.userId,
169      email: ctx.auth.user.email,
170      name: ctx.auth.user.name,
171      nickname: ctx.auth.user.nickname,
172      picture: ctx.auth.user.picture,
173      permissions: ctx.auth.permissions,
174      scopes: ctx.auth.scopes,
175    })
176);
177```
178 
179---
180 
181## Permissions
182 
183Auth0 includes permissions directly in the access token when you use the `rfc9068_profile_authz` token dialect. Check them in tool callbacks:
184 
185```typescript
186server.tool(
187  {
188    name: "delete-document",
189    description: "Delete a document (requires delete:documents)",
190  },
191  async ({ documentId }, ctx) => {
192    if (!ctx.auth.permissions?.includes("delete:documents")) {
193      return error("Forbidden: delete:documents permission required");
194    }
195 
196    await db.documents.delete({ id: documentId });
197    return text("Document deleted");
198  }
199);
200```
201 
202---
203 
204## Which mode should I use?
205 
206| | DCR (`oauthAuth0Provider`) | Proxy (`oauthProxy`) |
207|---|---|---|
208| Requires Early Access | Yes | No |
209| MCP clients self-register | Yes | No (single pre-registered app) |
210| Your server mediates `/token` | No | Yes |
211| Best for | Multi-client public MCP servers | Private/internal MCP servers |
212 
213If you aren't on the Auth0 DCR Early Access, use the proxy.
214 
215---
216 
217## Next Steps
218 
219- **Auth overview** → [overview.md](overview.md)
220- **Custom providers + OAuth proxy reference** → [custom.md](custom.md)
221- **WorkOS setup** → [workos.md](workos.md)
222- **Build tools** → [../server/tools.md](../server/tools.md)
223