Integrating Better Auth with xmcp

Learn how to add robust authentication to your MCP server using Better Auth, the most comprehensive authentication framework for TypeScript.

Info

This guide shows how to add authentication using Better Auth and a PostgreSQL database. PostgreSQL is currently the only supported database provider for this plugin.

What You'll Build

By the end of this guide, you'll have:

A fully functional authentication system with email/password and OAuth
Session management integrated into your xmcp tools
A login/signup page

Prerequisites

Before starting, make sure you have:

An existing xmcp project
Node.js 22+ installed
Access to a PostgreSQL database (we recommend Neon for easy setup)

Install Dependencies

Start by installing the Better Auth plugin and PostgreSQL dependencies:

Shell

npm install @xmcp-dev/better-auth pg

You'll also need the PostgreSQL types as a development dependency:

Shell

npm install -D @types/pg

Set Up Your Database

Create a PostgreSQL database with the required schema. Better Auth requires specific tables for user management, sessions, and OAuth applications.

Database Setup

For a seamless experience, we recommend setting up your database on Neon using Vercel's storage integration.

Run the following SQL script to create the necessary tables:

SQL

-- User table for storing user information
CREATE TABLE "user" (
  "id" text NOT NULL PRIMARY KEY,
  "name" text NOT NULL,
  "email" text NOT NULL UNIQUE,
  "emailVerified" boolean NOT NULL,
  "image" text,
  "createdAt" timestamp NOT NULL,
  "updatedAt" timestamp NOT NULL
);

-- Session table for managing user sessions
CREATE TABLE "session" (
  "id" text NOT NULL PRIMARY KEY,
  "expiresAt" timestamp NOT NULL,
  "token" text NOT NULL UNIQUE,
  "createdAt" timestamp NOT NULL,
  "updatedAt" timestamp NOT NULL,
  "ipAddress" text,
  "userAgent" text,
  "userId" text NOT NULL REFERENCES "user" ("id")
);

-- Account table for OAuth and local authentication
CREATE TABLE "account" (
  "id" text NOT NULL PRIMARY KEY,
  "accountId" text NOT NULL,
  "providerId" text NOT NULL,
  "userId" text NOT NULL REFERENCES "user" ("id"),
  "accessToken" text,
  "refreshToken" text,
  "idToken" text,
  "accessTokenExpiresAt" timestamp,
  "refreshTokenExpiresAt" timestamp,
  "scope" text,
  "password" text,
  "createdAt" timestamp NOT NULL,
  "updatedAt" timestamp NOT NULL
);

-- Verification table for email verification and password resets
CREATE TABLE "verification" (
  "id" text NOT NULL PRIMARY KEY,
  "identifier" text NOT NULL,
  "value" text NOT NULL,
  "expiresAt" timestamp NOT NULL,
  "createdAt" timestamp,
  "updatedAt" timestamp
);

-- OAuth application table for OAuth provider functionality
CREATE TABLE "oauthApplication" (
  "id" text NOT NULL PRIMARY KEY,
  "name" text NOT NULL,
  "icon" text,
  "metadata" text,
  "clientId" text NOT NULL UNIQUE,
  "clientSecret" text,
  "redirectURLs" text NOT NULL,
  "type" text NOT NULL,
  "disabled" boolean,
  "userId" text,
  "createdAt" timestamp NOT NULL,
  "updatedAt" timestamp NOT NULL
);

-- OAuth access token table
CREATE TABLE "oauthAccessToken" (
  "id" text NOT NULL PRIMARY KEY,
  "accessToken" text NOT NULL UNIQUE,
  "refreshToken" text NOT NULL UNIQUE,
  "accessTokenExpiresAt" timestamp NOT NULL,
  "refreshTokenExpiresAt" timestamp NOT NULL,
  "clientId" text NOT NULL,
  "userId" text,
  "scopes" text NOT NULL,
  "createdAt" timestamp NOT NULL,
  "updatedAt" timestamp NOT NULL
);

-- OAuth consent table for managing user consent
CREATE TABLE "oauthConsent" (
  "id" text NOT NULL PRIMARY KEY,
  "clientId" text NOT NULL,
  "userId" text NOT NULL,
  "scopes" text NOT NULL,
  "createdAt" timestamp NOT NULL,
  "updatedAt" timestamp NOT NULL,
  "consentGiven" boolean NOT NULL
);

Info

The schema generation through Better Auth's CLI is not supported yet, so you'll need to run this SQL manually.

Configure Environment Variables

Create a .env file in your xmcp app root directory with the following variables:

Shell

# Database connection string
DATABASE_URL=postgresql://<username>:<password>@<host>:<port>/<database>

# Better Auth configuration
BETTER_AUTH_SECRET=<your-secret-key>
BETTER_AUTH_BASE_URL=<your-app-base-url>

# Optional: OAuth provider credentials
GOOGLE_CLIENT_ID=<your-google-client-id>
GOOGLE_CLIENT_SECRET=<your-google-client-secret>

Security Note

Make sure to generate a strong, random secret for BETTER_AUTH_SECRET. This is used to sign JWT tokens and should be kept secure.

Add the Auth Middleware

Create a src/middleware.ts file and configure the Better Auth provider:

TypeScript

import { betterAuthProvider } from "@xmcp-dev/better-auth";
import { Pool } from "pg";

export default betterAuthProvider({
  database: new Pool({
    connectionString: process.env.DATABASE_URL,
  }),
  baseURL: process.env.BETTER_AUTH_BASE_URL || "http://127.0.0.1:3001",
  secret: process.env.BETTER_AUTH_SECRET!,
  providers: {
    emailAndPassword: {
      enabled: true,
    },
    google: {
      clientId: process.env.GOOGLE_CLIENT_ID || "",
      clientSecret: process.env.GOOGLE_CLIENT_SECRET || "",
    },
  },
});

Configuration Options:

database: Must be a valid PostgreSQL Pool instance
baseURL: Your app's base URL for generating OAuth callback URLs
secret: Secret key for signing JWT tokens
providers: Configuration for authentication providers

Configure Auth Providers

Better Auth supports multiple authentication methods. You can enable email/password authentication, OAuth providers, or both.

Email and Password Authentication

To enable email and password authentication:

TypeScript

export default betterAuthProvider({
  // ... other config
  providers: {
    emailAndPassword: {
      enabled: true,
    },
  },
});

Google OAuth

To enable Google OAuth, you'll need to:

Create a Web application OAuth client in the Google Cloud Console, following Better Auth’s Google setup.
Configure the consent screen and any required test users.
Set the authorized redirect URI to ${BETTER_AUTH_BASE_URL}/auth/callback/google, matching this xmcp plugin’s configured base URL exactly. For the configuration above, use http://127.0.0.1:3001/auth/callback/google.

TypeScript

export default betterAuthProvider({
  // ... other config
  providers: {
    google: {
      clientId: process.env.GOOGLE_CLIENT_ID,
      clientSecret: process.env.GOOGLE_CLIENT_SECRET,
    },
  },
});

Info

For production, make sure to update the redirect URI to match your domain: https://yourdomain.com/auth/callback/google

Combined Providers

You can enable both authentication methods:

TypeScript

export default betterAuthProvider({
  // ... other config
  providers: {
    emailAndPassword: {
      enabled: true,
    },
    google: {
      clientId: process.env.GOOGLE_CLIENT_ID,
      clientSecret: process.env.GOOGLE_CLIENT_SECRET,
    },
  },
});

Access Sessions in Your Tools

Use the getBetterAuthSession function to access the current user session in your xmcp tools:

TypeScript

import { getBetterAuthSession } from "@xmcp-dev/better-auth";

export default async function getUserProfile() {
  const session = await getBetterAuthSession();

  return `Your user id is ${session.userId}`;
}

Warning

The getBetterAuthSession function will throw an error if called outside of a betterAuthProvider middleware.

The login page will be available at http://host:port/auth/sign-in and is automatically generated by the config you passed to the provider function. It is also the same page for signing up.

Run the Better Auth HTTP example and see the integration reference for the current setup. Set a generated BETTER_AUTH_SECRET before starting; do not use a shared fallback secret.

Conclusion

You've now added authentication to your MCP server! Next time you establish a connection to the MCP server, you'll be prompted to authenticate.

Integrating Better Auth with xmcp

One framework to rule them all