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.

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 20+ installed
Access to a PostgreSQL database (we recommend Neon for easy setup)

Install Dependencies

Start by installing the Better Auth plugin and PostgreSQL dependencies:

npm install @xmcp-dev/better-auth pg

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

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.

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:

-- 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
);

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:

# 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>

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 middleware.ts file in your xmcp app root directory and configure the Better Auth provider:

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 || "super-secret-key",
  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:

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

Google OAuth

To enable Google OAuth, you'll need to:

Go to the Google Cloud Console
Create a new project or select an existing one
Enable the Google+ API
Create OAuth 2.0 credentials
Set the authorized redirect URI to: http://localhost:3001/auth/callback/google (for development)

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

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:

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:

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

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

  return `Hello, ${name}! Your user id is ${session.userId}`;
}

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

Access the Login Page

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.

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.