1# Better Auth Authentication
2 
3Setting up a self-hosted OAuth 2.1 authorization server with Better Auth.
4 
5**Learn more:** [Better Auth OAuth Provider Plugin](https://better-auth.com/docs/plugins/oauth-provider) · [Standalone starter template](https://github.com/mcp-use/mcp-oauth-better-auth-template) · [Runnable example](https://github.com/mcp-use/mcp-use/tree/main/libraries/typescript/packages/mcp-use/examples/server/oauth/better-auth)
6 
7> Covers the `@better-auth/oauth-provider` plugin. The older Better Auth MCP plugin is deprecated — for legacy users, see the [mcp-use adapter](https://better-auth.com/docs/plugins/mcp#framework-adapters).
8 
9---
10 
11## How It Works
12 
13Unlike WorkOS, Auth0, or Supabase, Better Auth runs **inside** your MCP server — your server *is* the OAuth 2.1 authorization server. Better Auth handles the full OAuth flow (authorization, token issuance, JWKS); mcp-use only verifies the resulting JWTs.
14 
15This means:
16- No external auth service required
17- You control the login and consent UX
18- Requires a database (SQLite, Postgres, etc.)
19- More setup than hosted providers
20 
21---
22 
23## Install
24 
25```bash
26npm install better-auth @better-auth/oauth-provider better-sqlite3
27```
28 
29---
30 
31## Setup
32 
33### 1. Configure Better Auth (`auth.ts`)
34 
35```typescript
36import { betterAuth } from "better-auth";
37import { jwt } from "better-auth/plugins";
38import { oauthProvider } from "@better-auth/oauth-provider";
39import Database from "better-sqlite3";
40 
41export const auth = betterAuth({
42  authURL: "http://localhost:3000",
43  basePath: "/api/auth",
44  secret: process.env.BETTER_AUTH_SECRET!,
45 
46  database: new Database("./sqlite.db"),
47 
48  socialProviders: {
49    github: {
50      clientId: process.env.GITHUB_CLIENT_ID!,
51      clientSecret: process.env.GITHUB_CLIENT_SECRET!,
52    },
53  },
54 
55  plugins: [
56    jwt(), // Required: signs and verifies access tokens
57    oauthProvider({
58      loginPage: "/sign-in",
59      consentPage: "/consent",
60      allowDynamicClientRegistration: true,
61      allowUnauthenticatedClientRegistration: true,
62      // Must include your MCP endpoint as a valid audience
63      validAudiences: ["http://localhost:3000/mcp"],
64      // Expose user profile claims in access token JWTs
65      customAccessTokenClaims: async ({ user }) => ({
66        email: user?.email,
67        name: user?.name,
68        picture: user?.image,
69      }),
70    }),
71  ],
72});
73```
74 
75### 2. Generate and migrate the database
76 
77```bash
78npx auth@latest generate
79npx auth@latest migrate
80```
81 
82### 3. Configure the MCP server (`server.ts`)
83 
84You need three things beyond the standard `MCPServer` setup:
851. Mount Better Auth routes (`/api/auth/**`)
862. Mount OAuth discovery endpoints with CORS headers (required for browser clients)
873. Mount login and consent pages
88 
89```typescript
90import { MCPServer, oauthBetterAuthProvider } from "mcp-use/server";
91import { auth } from "./auth.js";
92import {
93  oauthProviderAuthServerMetadata,
94  oauthProviderOpenIdConfigMetadata,
95} from "@better-auth/oauth-provider";
96 
97const server = new MCPServer({
98  name: "my-server",
99  version: "1.0.0",
100  oauth: oauthBetterAuthProvider({
101    authURL: "http://localhost:3000/api/auth",
102  }),
103});
104 
105// Mount Better Auth routes
106server.app.on(["GET", "POST"], "/api/auth/**", (c) => auth.handler(c.req.raw));
107 
108// OAuth discovery endpoints — CORS headers are required for browser clients (MCP Inspector)
109const corsHeaders = {
110  "Access-Control-Allow-Origin": "*",
111  "Access-Control-Allow-Methods": "GET",
112};
113const authServerMetadataHandler = oauthProviderAuthServerMetadata(auth, { headers: corsHeaders });
114server.app.get("/.well-known/oauth-authorization-server", (c) => authServerMetadataHandler(c.req.raw));
115server.app.get("/.well-known/oauth-authorization-server/api/auth", (c) => authServerMetadataHandler(c.req.raw));
116 
117const openIdConfigHandler = oauthProviderOpenIdConfigMetadata(auth, { headers: corsHeaders });
118server.app.get("/.well-known/openid-configuration", (c) => openIdConfigHandler(c.req.raw));
119server.app.get("/.well-known/openid-configuration/api/auth", (c) => openIdConfigHandler(c.req.raw));
120 
121await server.listen(3000);
122```
123 
124### 4. Add login and consent pages
125 
126Better Auth requires a `/sign-in` page and a `/consent` page mounted on the Hono app.
127 
128- **Sign-in page:** POST to `/api/auth/sign-in/social` with the provider name and `callbackURL: '/api/auth/oauth2/authorize' + queryString` (preserve the OAuth query params).
129- **Consent page:** POST to `/api/auth/oauth2/consent` with `{ accept: boolean, oauth_query: window.location.search.slice(1) }`.
130- Both must use `credentials: 'include'` on fetch calls.
131 
132See the [runnable example](https://github.com/mcp-use/mcp-use/tree/main/libraries/typescript/packages/mcp-use/examples/server/oauth/better-auth) for complete HTML/JS.
133 
134---
135 
136## Environment Variables
137 
138```bash
139# Better Auth secret (used for signing cookies and tokens)
140BETTER_AUTH_SECRET=your-secret-change-in-production
141 
142# Social provider credentials (GitHub shown — swap for any supported provider)
143# Set callback URL in provider dashboard to: http://localhost:3000/api/auth/callback/<provider>
144GITHUB_CLIENT_ID=your-github-client-id
145GITHUB_CLIENT_SECRET=your-github-client-secret
146```
147 
148Better Auth supports many social providers (GitHub, Google, Discord, etc.). See [Better Auth social providers docs](https://www.better-auth.com/docs/concepts/oauth) for the full list.
149 
150---
151 
152## Configuration Options
153 
154```typescript
155oauthBetterAuthProvider({
156  authURL: "https://yourapp.com/api/auth",  // Required: full URL including basePath
157  verifyJwt: process.env.NODE_ENV === "production",  // default: true
158  scopesSupported: ["openid", "profile", "email", "offline_access"],  // override advertised scopes
159  getUserInfo: (payload) => ({
160    userId: payload.sub as string,
161    email: payload.email as string,
162    name: payload.name as string,
163    roles: (payload.roles as string[]) || [],
164    permissions: (payload.permissions as string[]) || [],
165  }),
166})
167```
168 
169| Option | Type | Default | Description |
170|--------|------|---------|-------------|
171| `authURL` | `string` | env var | Better Auth base URL including `/api/auth` path |
172| `verifyJwt` | `boolean?` | `true` | Set `false` to skip JWT verification (**development only**) |
173| `scopesSupported` | `string[]?` | `["openid", "profile", "email", "offline_access"]` | Override advertised scopes |
174| `getUserInfo` | `function?` | built-in | Custom extraction of user info from JWT payload |
175 
176---
177 
178## Accessing user info in tools
179 
180```typescript
181server.tool(
182  { name: "get-user-info", description: "Get information about the authenticated user" },
183  async (_args, ctx) =>
184    object({
185      userId: ctx.auth.user.userId,
186      email: ctx.auth.user.email,
187      name: ctx.auth.user.name,
188      scopes: ctx.auth.scopes,
189      permissions: ctx.auth.permissions,
190    })
191);
192```
193 
194---
195 
196## Common Mistakes
197 
198- **Missing `validAudiences`** — Must include your MCP endpoint (e.g. `http://localhost:3000/mcp`) or JWT verification will fail with an audience mismatch.
199- **Missing CORS headers on discovery endpoints** — Browser clients like MCP Inspector require `Access-Control-Allow-Origin: *` on `/.well-known/*` routes.
200- **Skipping `jwt()` plugin** — Required for token signing; omitting it breaks token issuance.
201- **Wrong `authURL`** — `oauthBetterAuthProvider({ authURL })` must include the full basePath (e.g. `/api/auth`), not just the host.
202- **Missing `credentials: 'include'`** — Login and consent page fetch calls must include cookies or the session will be lost.
203 
204---
205 
206## Next Steps
207 
208- **Auth overview** → [overview.md](overview.md)
209- **WorkOS setup** → [workos.md](workos.md)
210- **Supabase setup** → [supabase.md](supabase.md)
211- **Keycloak setup** → [keycloak.md](keycloak.md)
212- **Build tools** → [../server/tools.md](../server/tools.md)
213