MCP

Add the MCP plugin to your auth configuration and specify the login page path.

```ts title="auth.ts"
import { betterAuth } from "better-auth";
import { mcp } from "better-auth/plugins"; // [!code highlight]

export const auth = betterAuth({
    plugins: [
        mcp({ // [!code highlight]
            loginPage: "/sign-in" // path to your login page // [!code highlight]
        }) // [!code highlight]
    ]
});
```

<Callout>
  This doesn't have a client plugin, so you don't need to make any changes to your authClient.
</Callout>

Run the migration or generate the schema to add the necessary fields and tables to the database.

<Tabs items={["migrate", "generate"]}>
  <Tab value="migrate">
    ```package-install
    npx auth migrate
    ```
  </Tab>

  <Tab value="generate">
    ```package-install
    npx auth generate
    ```
  </Tab>
</Tabs>

The MCP plugin uses the same schema as the OIDC Provider plugin. See the [OIDC Provider Schema](/docs/plugins/oidc-provider#schema) section for details.

import { oAuthDiscoveryMetadata } from "better-auth/plugins";
import { auth } from "../../../lib/auth";

export const GET = oAuthDiscoveryMetadata(auth);

import { oAuthProtectedResourceMetadata } from "better-auth/plugins";
import { auth } from "@/lib/auth";

export const GET = oAuthProtectedResourceMetadata(auth);

import { auth } from "@/lib/auth";
import { createMcpHandler } from "@vercel/mcp-adapter";
import { withMcpAuth } from "better-auth/plugins";
import { z } from "zod";

const handler = withMcpAuth(auth, (req, session) => {
    // session contains the access token record with scopes and user ID
    return createMcpHandler(
        (server) => {
            server.tool(
                "echo",
                "Echo a message",
                { message: z.string() },
                async ({ message }) => {
                    return {
                        content: [{ type: "text", text: `Tool echo: ${message}` }],
                    };
                },
            );
        },
        {
            capabilities: {
                tools: {
                    echo: {
                        description: "Echo a message",
                    },
                },
            },
        },
        {
            redisUrl: process.env.REDIS_URL,
            basePath: "/api",
            verboseLogs: true,
            maxDuration: 60,
        },
    )(req);
});

export { handler as GET, handler as POST, handler as DELETE };

import { auth } from "@/lib/auth";
import { createMcpHandler } from "@vercel/mcp-adapter";
import { z } from "zod";

const handler = async (req: Request) => {
     // session contains the access token record with scopes and user ID
    const session = await auth.api.getMcpSession({
        headers: req.headers
    })
    if(!session){
        //this is important and you must return 401
        return new Response(null, {
            status: 401
        })
    }
    return createMcpHandler(
        (server) => {
            server.tool(
                "echo",
                "Echo a message",
                { message: z.string() },
                async ({ message }) => {
                    return {
                        content: [{ type: "text", text: `Tool echo: ${message}` }],
                    };
                },
            );
        },
        {
            capabilities: {
                tools: {
                    echo: {
                        description: "Echo a message",
                    },
                },
            },
        },
        {
            redisUrl: process.env.REDIS_URL,
            basePath: "/api",
            verboseLogs: true,
            maxDuration: 60,
        },
    )(req);
}

export { handler as GET, handler as POST, handler as DELETE };

Point it at your Better Auth server's URL (the same `baseURL` + `basePath` from your auth config):

```ts title="mcp-server.ts"
import { createMcpAuthClient } from "better-auth/plugins/mcp/client" // [!code highlight]

const mcpAuth = createMcpAuthClient({ // [!code highlight]
    authURL: "http://localhost:3000/api/auth" // [!code highlight]
}) // [!code highlight]
```

Use the `handler` wrapper for Web Standard `Request`/`Response` (works with Deno, Bun, Cloudflare Workers, etc.):

```ts title="mcp-server.ts"
const handler = mcpAuth.handler(async (req, session) => { // [!code highlight]
    // session.userId, session.scopes, session.clientId
    return new Response(JSON.stringify({
        jsonrpc: "2.0",
        result: { userId: session.userId },
        id: 1
    }))
}) // [!code highlight]

Deno.serve(handler)
```

MCP clients need to discover your OAuth server. Mount these at the root of your MCP server:

```ts title="mcp-server.ts"
const discovery = mcpAuth.discoveryHandler() // [!code highlight]
const protectedResource = mcpAuth.protectedResourceHandler("http://localhost:4000") // [!code highlight]

// GET /.well-known/oauth-authorization-server → proxied from Better Auth
// GET /.well-known/oauth-protected-resource → points MCP clients to Better Auth
```

These proxy and cache the metadata from your Better Auth server, so MCP clients can discover the authorization, token, and registration endpoints automatically.

const app = new Hono()
const { middleware, discoveryRoutes } = mcpAuthHono({ // [!code highlight]
    authURL: "http://localhost:3000/api/auth" // [!code highlight]
}) // [!code highlight]

// Mount OAuth discovery endpoints (required by MCP spec)
discoveryRoutes(app, "http://localhost:4000") // [!code highlight]

// Protect MCP routes
app.use("/mcp/*", middleware) // [!code highlight]

app.post("/mcp", (c) => {
    const session = c.get("mcpSession") // [!code highlight]
    // session.userId, session.scopes, etc.
})
```

const app = express()
const mcpAuth = createMcpAuthClient({ // [!code highlight]
    authURL: "http://localhost:3000/api/auth" // [!code highlight]
}) // [!code highlight]

app.use("/mcp", mcpAuth.middleware()) // [!code highlight]

app.post("/mcp", (req, res) => {
    const session = req.mcpSession // [!code highlight]
    // session.userId, session.scopes, etc.
})
```

const auth = mcpAuthOfficial({ // [!code highlight]
    authURL: "http://localhost:3000/api/auth" // [!code highlight]
}) // [!code highlight]

const mcpServer = new McpServer({ name: "my-server", version: "1.0.0" })
const app = express() // your HTTP framework

app.post("/mcp", auth.handler(async (req, session) => { // [!code highlight]
    const transport = new StreamableHTTPServerTransport({
        sessionIdGenerator: () => crypto.randomUUID()
    })
    await mcpServer.connect(transport)
    return transport.handleRequest(req)
}))
```

```ts title="mcp-server.ts"
import { MCPServer } from "mcp-use/server"
import { mcpAuthMcpUse } from "better-auth/plugins/mcp/client/adapters" // [!code highlight]

const server = new MCPServer({
    name: "my-server",
    version: "1.0.0",
    oauth: mcpAuthMcpUse({ // [!code highlight]
        authURL: "http://localhost:3000/api/auth" // [!code highlight]
    }) // [!code highlight]
})
```