### Start Development Server (Bash)

Source: https://github.com/basementstudio/xmcp/blob/main/examples/better-auth-nextjs/README.md

Starts the Next.js development server.

```bash
npm run dev
```

--------------------------------

### Install Dependencies (Bash)

Source: https://github.com/basementstudio/xmcp/blob/main/examples/better-auth-nextjs/README.md

Installs the necessary project dependencies using npm.

```bash
npm install
```

--------------------------------

### Run xmcp Server

Source: https://github.com/basementstudio/xmcp/blob/main/examples/clerk-http/README.md

Commands to run the xmcp server for development and production builds. Uses pnpm for package management.

```bash
# Development
pnpm dev

# Production
pnpm build
pnpm start
```

--------------------------------

### Installation Commands

Source: https://github.com/basementstudio/xmcp/blob/main/examples/with-nestjs/README.md

Commands to install dependencies and initialize environment variables.

```bash
# Install dependencies
pnpm install

# Copy environment variables
cp .env.example .env
```

--------------------------------

### Production Build and Start Commands

Source: https://github.com/basementstudio/xmcp/blob/main/examples/with-nestjs/README.md

Commands to build the application and start the production server.

```bash
# Build both XMCP and NestJS
pnpm build

# Start the server
pnpm start
```

--------------------------------

### Run Next.js Development Server

Source: https://github.com/basementstudio/xmcp/blob/main/apps/website/README.md

Commands to start the Next.js development server using different package managers. This allows for live reloading and development of the application. Ensure you have Node.js installed.

```bash
npm run dev
# or
yarn dev
# or
pnpm dev
# or
bun dev
```

--------------------------------

### Install Clerk Plugin for xmcp

Source: https://github.com/basementstudio/xmcp/blob/main/examples/clerk-http/README.md

Installs the necessary Clerk plugin for xmcp applications using npm. This is the first step to integrating Clerk authentication.

```bash
npm install @xmcp-dev/clerk
```

--------------------------------

### Initialize xmcp App with Vercel CLI

Source: https://github.com/basementstudio/xmcp/blob/main/apps/website/content/docs/deployment/vercel.mdx

Initialize a new xmcp application project using the Vercel CLI. This command clones the official xmcp example repository, setting up a basic project structure for you to start with. It requires Vercel CLI to be installed and authenticated.

```bash
vc init xmcp
```

--------------------------------

### Configure Multiple Transport Start Scripts

Source: https://github.com/basementstudio/xmcp/blob/main/apps/website/content/docs/getting-started/installation.mdx

Define separate start scripts in your package.json for different transport configurations (HTTP and STDIO). This allows you to easily run your production server with the specific transport you have configured.

```json
{
  "scripts": {
    "start:http": "node dist/http.js",
    "start:stdio": "node dist/stdio.js"
  }
}
```

--------------------------------

### Install @xmcp-dev/scalekit

Source: https://github.com/basementstudio/xmcp/blob/main/packages/plugins/scalekit/README.md

Install the scalekit package using npm or pnpm.

```bash
npm install @xmcp-dev/scalekit
# or
pnpm add @xmcp-dev/scalekit
```

--------------------------------

### Install JWT Library

Source: https://github.com/basementstudio/xmcp/blob/main/apps/website/content/docs/adapters/nestjs.mdx

Install the `jsonwebtoken` library and its types for JWT authentication.

```bash
npm install jsonwebtoken
npm install -D @types/jsonwebtoken
```

--------------------------------

### Install Commet Plugin with bun

Source: https://github.com/basementstudio/xmcp/blob/main/apps/website/content/docs/integrations/commet.mdx

Use this command to install the Commet plugin using bun.

```bash
bun add @xmcp-dev/commet
```

--------------------------------

### Install Scalekit Plugin

Source: https://github.com/basementstudio/xmcp/blob/main/apps/website/content/docs/integrations/scalekit.mdx

Install the Scalekit plugin using your preferred package manager.

```bash
pnpm i @xmcp-dev/scalekit
```

```bash
npm i @xmcp-dev/scalekit
```

```bash
yarn add @xmcp-dev/scalekit
```

```bash
bun add @xmcp-dev/scalekit
```

--------------------------------

### Environment Variables Setup (.env)

Source: https://github.com/basementstudio/xmcp/blob/main/examples/auth0-http/README.md

This snippet shows the necessary environment variables for configuring the Auth0 M2M client and the application's base URL. Ensure 'DOMAIN', 'AUDIENCE', 'CLIENT_ID', and 'CLIENT_SECRET' are replaced with your Auth0 tenant credentials and 'BASE_URL' matches your application's address.

```bash
# Credentials
DOMAIN=your-tenant.auth0.com
AUDIENCE=http://127.0.0.1:3001/
CLIENT_ID=your-m2m-client-id
CLIENT_SECRET=your-m2m-client-secret

# App configuration
BASE_URL=http://127.0.0.1:3001
```

--------------------------------

### HTTP Client Example with API Key

Source: https://github.com/basementstudio/xmcp/blob/main/apps/website/content/docs/core-concepts/external-clients.mdx

Example of an HTTP client configuration using an environment variable for an API key.

```typescript
{
  context: {
    url: "https://mcp.context7.com/mcp",
    headers: [
      { name: "CONTEXT7_API_KEY", env: "CONTEXT7_API_KEY" },
    ],
  },
}
```

--------------------------------

### Start Development Server (Bash)

Source: https://github.com/basementstudio/xmcp/blob/main/packages/create-xmcp-app/templates/mcp-apps/default/README.md

Starts the development server for the project using npm. This command enables HTTP transport, facilitating local development and testing of the widgets.

```bash
npm run dev

```

--------------------------------

### Install x402 plugin

Source: https://github.com/basementstudio/xmcp/blob/main/packages/plugins/x402/README.md

Command to install the x402 package via pnpm.

```bash
pnpm add @xmcp-dev/x402
```

--------------------------------

### Install Commet Plugin with yarn

Source: https://github.com/basementstudio/xmcp/blob/main/apps/website/content/docs/integrations/commet.mdx

Use this command to install the Commet plugin using yarn.

```bash
yarn add @xmcp-dev/commet
```

--------------------------------

### Install Commet Plugin with pnpm

Source: https://github.com/basementstudio/xmcp/blob/main/apps/website/content/docs/integrations/commet.mdx

Use this command to install the Commet plugin using pnpm.

```bash
pnpm i @xmcp-dev/commet
```

--------------------------------

### Generated Client Usage Example

Source: https://github.com/basementstudio/xmcp/blob/main/packages/cli/README.md

This example shows how to import and use the generated clients from the `client.index.ts` file. Ensure the server or package is available.

```typescript
import { generatedClients } from "./generated/client.index";

await generatedClients.client1.greet({ name: "World" });
await generatedClients.client2.randomNumber();
```

--------------------------------

### Install Commet Plugin with npm

Source: https://github.com/basementstudio/xmcp/blob/main/apps/website/content/docs/integrations/commet.mdx

Use this command to install the Commet plugin using npm.

```bash
npm i @xmcp-dev/commet
```

--------------------------------

### Complete Example: Protected Tool with Polar Integration

Source: https://github.com/basementstudio/xmcp/blob/main/apps/website/content/docs/integrations/polar.mdx

A full example demonstrating how to initialize the Polar provider, validate a license key, track tool usage, and execute tool logic only if the license is valid.

```typescript
import { PolarProvider } from "@xmcp-dev/polar";
import { headers } from "xmcp/headers";

export const polar = PolarProvider.getInstance({
  type: "production",
  token: process.env.POLAR_TOKEN,
  organizationId: process.env.POLAR_ORGANIZATION_ID,
  productId: process.env.POLAR_PRODUCT_ID,
});

export default async function protectedTool() {
  const licenseKey = headers()["license-key"];

  const response = await polar.validateLicenseKey(licenseKey, {
    name: "tool_call_event",
    metadata: { tool_name: "protectedTool", calls: 1 },
  });

  if (!response.valid) {
    return response.message;
  }

  // Your tool logic here
  return "Tool executed successfully";
}
```

--------------------------------

### Define and Implement a Prompt in TypeScript

Source: https://github.com/basementstudio/xmcp/blob/main/apps/website/content/blog/v0.3.0-release.mdx

This example illustrates the creation of a prompt, which serves as a pre-defined message template for guiding LLM interactions. It highlights the structural similarity to tools but emphasizes differences in metadata and return types. Prompts are user-controlled and do not execute logic, unlike tools.

```typescript
import { z } from "zod";
import { type InferSchema, type PromptMetadata } from "xmcp";

// Define the schema for prompt parameters
export const schema = {
  code: z.string().describe("The code to review"),
};

// Define prompt metadata
export const metadata: PromptMetadata = {
  name: "review-code",
  title: "Review Code",
  description: "Review code for best practices and potential issues",
  role: "user",
};

// Prompt implementation
export default function reviewCode({ code }: InferSchema<typeof schema>) {
  return {
    type: "text",
    text: `Please review this code for:
      - Code quality and best practices
      - Potential bugs or security issues
      - Performance optimizations
      - Readability and maintainability

      Code to review:
      ```
      ${code}
      ``` `,
  };
}
```

--------------------------------

### Development Server Command

Source: https://github.com/basementstudio/xmcp/blob/main/examples/with-nestjs/README.md

Start the development server with hot reload for both XMCP and NestJS.

```bash
pnpm dev
```

--------------------------------

### Install Better Auth Plugin for xmcp

Source: https://github.com/basementstudio/xmcp/blob/main/apps/website/content/blog/everything-we-shipped-so-far.mdx

Installs the Better Auth plugin required for authentication in xmcp. This command-line instruction is the first step in integrating authentication.

```bash
npm install @xmcp-dev/better-auth
```

--------------------------------

### Install xmcp CLI

Source: https://github.com/basementstudio/xmcp/blob/main/apps/website/content/docs/adapters/express.mdx

Install the xmcp CLI to integrate it into your Express project. This command initializes xmcp within your project directory.

```bash
npx init-xmcp@latest
```

--------------------------------

### Scaffolding with CLI

Source: https://github.com/basementstudio/xmcp/blob/main/packages/cli/README.md

Use these commands to create starter files for xmcp tools, resources, or prompts, following project conventions.

```bash
npx @xmcp-dev/cli create tool get-weather
```

```bash
npx @xmcp-dev/cli create tool weather-widget --preset react
```

```bash
npx @xmcp-dev/cli create resource app-config
```

```bash
npx @xmcp-dev/cli create prompt review-code
```

--------------------------------

### STDIO Client Configuration Examples

Source: https://github.com/basementstudio/xmcp/blob/main/apps/website/content/docs/core-concepts/external-clients.mdx

Illustrates various ways to configure STDIO clients, from simple npm package execution to custom commands with arguments and environment variables.

```typescript
// Simple npm package
{
  npm: "@playwright/mcp"
}
```

```typescript
// With arguments
{
  npm: "@playwright/mcp",
  npmArgs: ["--browser", "chromium"]
}
```

```typescript
// Custom command
{
  command: "bunx",
  args: ["-y", "@upstash/context7-mcp"]
}
```

```typescript
// With environment variables
{
  npm: "@some/mcp-server",
  env: {
    DEBUG: "true",
    LOG_LEVEL: "verbose"
  }
}
```

--------------------------------

### Install Dependencies with pnpm

Source: https://github.com/basementstudio/xmcp/blob/main/examples/cloudflare-workers/README.md

Installs project dependencies using the pnpm package manager. This is a prerequisite for building and running the Cloudflare Worker.

```bash
pnpm install
```

--------------------------------

### Run STDIO Server

Source: https://github.com/basementstudio/xmcp/blob/main/examples/polar-http/README.md

Starts the STDIO server for the built project. Use npm, yarn, or pnpm.

```bash
npm run start-stdio
# or
yarn start-stdio
# or
pnpm start-stdio
```

--------------------------------

### Set Up Database Schema (Bash)

Source: https://github.com/basementstudio/xmcp/blob/main/examples/better-auth-nextjs/README.md

Generates the database schema using the Better Auth CLI. This output needs to be manually applied or managed with an ORM.

```bash
npx @better-auth/cli generate
```

--------------------------------

### Register xmcp Handler with Fastify

Source: https://github.com/basementstudio/xmcp/blob/main/apps/website/content/docs/adapters/fastify.mdx

Install Fastify and register the xmcpHandler on your Fastify server. The GET route is required for SSE clients.

```bash
npm install fastify
```

```typescript
import Fastify from "fastify";
import { xmcpHandler } from "@xmcp/adapter";

const app = Fastify({ logger: false });

app.post("/mcp", xmcpHandler);
app.get("/mcp", xmcpHandler); // required for SSE / streaming clients

await app.listen({ port: 3000 });
```

--------------------------------

### GET /.well-known/oauth-protected-resource

Source: https://github.com/basementstudio/xmcp/blob/main/examples/auth0-http/README.md

Retrieves resource metadata for MCP clients, used for OAuth authentication configuration.

```APIDOC
## GET /.well-known/oauth-protected-resource

### Description
Retrieves resource metadata for MCP clients. This endpoint is crucial for clients to understand how to authenticate with the server using OAuth.

### Method
GET

### Endpoint
`/.well-known/oauth-protected-resource`

### Parameters
#### Query Parameters
None

#### Path Parameters
None

### Request Body
None

### Response
#### Success Response (200)
- **metadata** (object) - Contains information about the protected resources and authentication methods.

#### Response Example
```json
{
  "metadata": {
    "issuer": "https://your-tenant.auth0.com/",
    "authorization_endpoint": "https://your-tenant.auth0.com/authorize",
    "token_endpoint": "https://your-tenant.auth0.com/oauth/token",
    "jwks_uri": "https://your-tenant.auth0.com/.well-known/jwks.json",
    "response_types_supported": [
      "code"
    ],
    "subject_types_supported": [
      "public"
    ],
    "scopes_supported": [
      "openid",
      "profile",
      "email",
      "tool:greet",
      "tool:whoami"
    ],
    "audience": "http://localhost:3001/"
  }
}
```
```

--------------------------------

### CLI Usage Examples

Source: https://github.com/basementstudio/xmcp/blob/main/packages/cli/README.md

These commands demonstrate how to generate typed clients and scaffold xmcp primitives using the CLI.

```bash
npx @xmcp-dev/cli generate [options]
```

```bash
npx @xmcp-dev/cli create <tool|resource|prompt> [name] [options]
```

--------------------------------

### Configure Server Instructions

Source: https://github.com/basementstudio/xmcp/blob/main/apps/website/content/docs/configuration/server-info.mdx

Provide guidance to LLM clients on how to use the server effectively. This is sent in the MCP initialize response.

```typescript
const config: XmcpConfig = {
  template: {
    name: "My MCP Server",
    instructions:
      "Always call get-user before calling update-user. " +
      "Use list-items with pagination for large datasets. " +
      "The search tool supports fuzzy matching by default.",
  },
};
```

--------------------------------

### Accessing User Session

Source: https://github.com/basementstudio/xmcp/blob/main/packages/plugins/better-auth/README.md

Demonstrates how to retrieve the current user's session information within your application tools using the `getBetterAuthSession` function.

```APIDOC
## Access the session in your tools

### Description
Use the `getBetterAuthSession` function to retrieve the current user's session data. This function will throw an error if called outside of a `betterAuthProvider` middleware context.

### Method
Function Call

### Endpoint
N/A (Function within application code)

### Parameters
None

### Request Example
```ts
import { getBetterAuthSession } from "@xmcp-dev/better-auth";

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

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

### Response
#### Success Response (Session Object)
- **userId** (string) - The unique identifier for the authenticated user.

#### Response Example
```json
{
  "userId": "user-12345"
}
```

#### Error Response
Throws an error if `getBetterAuthSession` is called outside of `betterAuthProvider` middleware.
```

--------------------------------

### Run HTTP Server

Source: https://github.com/basementstudio/xmcp/blob/main/examples/polar-http/README.md

Starts the HTTP server for the built project. Use npm, yarn, or pnpm.

```bash
npm run start-http
# or
yarn start-http
# or
pnpm start-http
```

--------------------------------

### Run Development Server

Source: https://github.com/basementstudio/xmcp/blob/main/examples/polar-http/README.md

Starts the MCP server for development. Use npm, yarn, or pnpm.

```bash
npm run dev
# or
yarn dev
# or
pnpm dev
```

--------------------------------

### Get User Session in Tool

Source: https://github.com/basementstudio/xmcp/blob/main/apps/website/content/docs/integrations/scalekit.mdx

Access the authenticated user's session within your xmcp tools using the getSession function. This example shows how to greet a user using their name or user ID.

```typescript
import { z } from "zod";
import { type InferSchema, type ToolMetadata } from "xmcp";
import { getSession } from "@xmcp-dev/scalekit";

export const schema = {
  name: z.string().optional().describe("The name of the user to greet"),
};

export const metadata: ToolMetadata = {
  name: "greet",
  description: "Greet the user with their Scalekit identity",
};

export default function greet({ name }: InferSchema<typeof schema>): string {
  const session = getSession();
  const displayName = name ?? session.userId;
  return `Hello, ${displayName}! Your user ID is ${session.userId}`;
}
```

--------------------------------

### Authentication Providers Configuration

Source: https://github.com/basementstudio/xmcp/blob/main/packages/plugins/better-auth/README.md

This section details how to configure different authentication providers, including email/password and Google OAuth, by setting specific properties in the configuration object.

```APIDOC
## Authentication Providers Configuration

### Description
Configure authentication providers by setting properties within the `providers` object.

### Method
Configuration

### Endpoint
N/A (Configuration Object)

### Parameters
#### Request Body
- **providers** (object) - Required - Configuration object for authentication providers
  - **providers.emailAndPassword** (boolean) - Optional - Set to `true` to enable email/password authentication
  - **providers.google** (object) - Optional - Google OAuth configuration object
    - **providers.google.clientId** (string) - Required if using Google - Google OAuth client ID from Google Cloud Console
    - **providers.google.clientSecret** (string) - Required if using Google - Google OAuth client secret from Google Cloud Console

### Request Example
#### Email and Password Provider
```ts
const config: BetterAuthConfig = {
  ...config, // your existing config
  providers: {
    emailAndPassword: true,
  },
};
```

#### Google Provider
```ts
const config: BetterAuthConfig = {
  ...config, // your existing config
  providers: {
    google: {
      clientId: "your-client-id",
      clientSecret: "your-client-secret",
    },
  },
};
```

#### Combined Providers
```ts
const config: BetterAuthConfig = {
  ...config, // your existing config
  providers: {
    emailAndPassword: true,
    google: {
      clientId: "your-client-id",
      clientSecret: "your-client-secret",
    },
  },
};
```

### Response
N/A (Configuration applies to application setup)

### Notes
- Google OAuth credentials can be found in the [Google Cloud Console](https://console.cloud.google.com/apis/dashboard).
- Set redirect URLs in Google Cloud Console > Credentials > Authorized redirect URIs to `http://host:port/auth/callback/google` for local development or `https://example.com/auth/callback/google` for production.
- The login page is automatically generated at `http://host:port/auth/sign-in`.
```

--------------------------------

### Run Development Server with npm

Source: https://github.com/basementstudio/xmcp/blob/main/examples/auth-nextjs/README.md

Use this command to start the Next.js development server using npm. Open http://localhost:3000 in your browser to view the application.

```bash
npm run dev
```

--------------------------------

### Prompt Loading Error: Empty File

Source: https://github.com/basementstudio/xmcp/blob/main/apps/website/content/docs/core-concepts/prompts.mdx

This example demonstrates the console output when xmcp encounters an empty prompt file during startup. The system skips such files with a warning.

```text
[xmcp] Failed to load prompt file: src/prompts/draft.ts
   -> File is empty.
[xmcp] 1 prompt skipped due to empty files or missing default exports
```

--------------------------------

### Configure Clerk Middleware in xmcp

Source: https://github.com/basementstudio/xmcp/blob/main/examples/clerk-http/README.md

Sets up the middleware for Clerk authentication in an xmcp application. It requires Clerk secret key, domain, and base URL from environment variables.

```typescript
import { clerkProvider } from "@xmcp-dev/clerk";

export default clerkProvider({
  secretKey: process.env.CLERK_SECRET_KEY!,
  clerkDomain: process.env.CLERK_DOMAIN!,
  baseURL: process.env.BASE_URL!,
});
```

--------------------------------

### Enable Email/Password Authentication

Source: https://github.com/basementstudio/xmcp/blob/main/examples/better-auth-http/README.md

Enables the email and password authentication provider by setting the `emailAndPassword` property to `true` in the configuration object. This is a simple boolean flag to activate the provider.

```typescript
const config: BetterAuthConfig = {
  ...config, // your existing config
  providers: {
    emailAndPassword: true,
  },
};
```

--------------------------------

### Run Development Server with Bun

Source: https://github.com/basementstudio/xmcp/blob/main/examples/auth-nextjs/README.md

Use this command to start the Next.js development server using Bun. Open http://localhost:3000 in your browser to view the application.

```bash
bun dev
```

--------------------------------

### Access Authentication Session

Source: https://github.com/basementstudio/xmcp/blob/main/examples/better-auth-http/README.md

Retrieves the current authentication session using the `getBetterAuthSession` function. This function is intended for use within a `betterAuthProvider` middleware and will throw an error if called outside of it.

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

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

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

--------------------------------

### Log: Empty Tool File

Source: https://github.com/basementstudio/xmcp/blob/main/apps/website/content/docs/core-concepts/tools.mdx

Startup logs this message when a tool file is empty and skipped.

```txt
[xmcp] Failed to load tool file: src/tools/draft.ts
   -> File is empty.
[xmcp] 1 tool skipped due to empty files or missing default exports
```

--------------------------------

### Combine Email/Password and Google OAuth Providers

Source: https://github.com/basementstudio/xmcp/blob/main/examples/better-auth-http/README.md

Demonstrates how to enable and configure both the email/password and Google OAuth providers simultaneously within the authentication configuration. This allows users to choose their preferred login method.

```typescript
const config: BetterAuthConfig = {
  ...config, // your existing config
  providers: {
    emailAndPassword: true,
    google: {
      clientId: "your-client-id",
      clientSecret: "your-client-secret",
    },
  },
};
```

--------------------------------

### Configure Google OAuth Provider

Source: https://github.com/basementstudio/xmcp/blob/main/examples/better-auth-http/README.md

Configures the Google OAuth provider by setting the `google` property to an object containing `clientId` and `clientSecret`. These credentials are required for Google authentication and can be obtained from the Google Cloud Console.

```typescript
const config: BetterAuthConfig = {
  ...config, // your existing config
  providers: {
    google: {
      clientId: "your-client-id",
      clientSecret: "your-client-secret",
    },
  },
};
```

--------------------------------

### Create PostgreSQL Tables for Better Auth (SQL)

Source: https://github.com/basementstudio/xmcp/blob/main/examples/better-auth-http/README.md

SQL script to create the necessary tables in a PostgreSQL database for Better Auth. This includes tables for users, sessions, accounts, verification, and OAuth-related data.

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

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

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

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

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

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

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

```

--------------------------------

### Configure Better Auth Middleware (TypeScript)

Source: https://github.com/basementstudio/xmcp/blob/main/packages/plugins/better-auth/README.md

Sets up the Better Auth middleware for an xmcp application using PostgreSQL. It configures database connection, base URL, secret, and authentication providers like email/password and Google OAuth.

```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:3002",
  secret: process.env.BETTER_AUTH_SECRET || "super-secret-key",
  providers: {
    emailAndPassword: true,
    google: {
      clientId: process.env.GOOGLE_CLIENT_ID || "",
      clientSecret: process.env.GOOGLE_CLIENT_SECRET || "",
    },
  },
});
```

--------------------------------

### Access Authenticated User Session and Profile in xmcp Tools

Source: https://github.com/basementstudio/xmcp/blob/main/examples/clerk-http/README.md

Demonstrates how to retrieve the authenticated user's session and full profile information within xmcp tools using Clerk's helper functions. Requires the `@xmcp-dev/clerk` package.

```typescript
import { getSession, getUser } from "@xmcp-dev/clerk";

export default async function myTool() {
  // Get session data
  const session = getSession();
  console.log(session.userId);
  console.log(session.organizationId);

  // Get full user profile
  const user = await getUser();
  console.log(user.firstName);
  console.log(user.emailAddresses[0]?.emailAddress);
}
```

--------------------------------

### Implement a Paid Tool with x402 in TypeScript

Source: https://github.com/basementstudio/xmcp/blob/main/apps/website/content/docs/guides/monetization.mdx

Marks a tool as requiring payment using the `paid()` wrapper from the x402 library. This example shows how to define a specific price for the tool and the asynchronous function that executes the tool's logic.

```typescript
import { paid } from "@xmcp-dev/x402";

export default paid(
  { price: 0.05 },
  async function paidTool({ input }) {
    return `Processed: ${input}`;
  }
);
```

--------------------------------

### Configure Better Auth Middleware (TypeScript)

Source: https://github.com/basementstudio/xmcp/blob/main/examples/better-auth-http/README.md

Sets up the Better Auth middleware for an xmcp application using a PostgreSQL database. It configures authentication providers like email/password and Google, and defines essential parameters such as database connection, base URL, and secret.

```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:3002",
  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 || "",
    },
  },
});
```

--------------------------------

### Resource loading error logs

Source: https://github.com/basementstudio/xmcp/blob/main/apps/website/content/docs/core-concepts/resources.mdx

Example output logs when xmcp encounters empty files or missing default exports during startup.

```txt
[xmcp] Failed to load resource file: src/resources/(drafts)/latest.ts
   -> File is empty.
[xmcp] 1 resource skipped due to empty files or missing default exports
```

--------------------------------

### Run Development Server with pnpm

Source: https://github.com/basementstudio/xmcp/blob/main/examples/auth-nextjs/README.md

Use this command to start the Next.js development server using pnpm. Open http://localhost:3000 in your browser to view the application.

```bash
pnpm dev
```

--------------------------------

### Install xmcp Dependencies Manually

Source: https://github.com/basementstudio/xmcp/blob/main/apps/website/content/docs/getting-started/installation.mdx

Manually install the xmcp package and its peer dependency zod using various package managers. Ensure you have Node.js 20 or later installed.

```pnpm
pnpm i xmcp zod@^3.25.76
```

```npm
npm i xmcp zod@^3.25.76
```

```yarn
yarn add xmcp zod@^3.25.76
```

```bun
bun add xmcp zod@^3.25.76
```

--------------------------------

### Log: Missing Default Export

Source: https://github.com/basementstudio/xmcp/blob/main/apps/website/content/docs/core-concepts/tools.mdx

Startup logs this message when a tool file exists but does not export a default handler.

```txt
[xmcp] Failed to load tool file: src/tools/draft.ts
   -> File does not export a default tool handler.
```

--------------------------------

### Install Polar package

Source: https://github.com/basementstudio/xmcp/blob/main/packages/plugins/polar/README.md

Installs the @xmcp-dev/polar dependency via npm.

```bash
npm install @xmcp-dev/polar
```

--------------------------------

### Run Development Server with Yarn

Source: https://github.com/basementstudio/xmcp/blob/main/examples/auth-nextjs/README.md

Use this command to start the Next.js development server using Yarn. Open http://localhost:3000 in your browser to view the application.

```bash
yarn dev
```