xmcp

https://xmcp.dev/docs
Admin
xmcp is a TypeScript framework for building and deploying MCP server, featuring file system routing,...
Tokens:32,347
Snippets:432
Trust Score:7.3
Update:6 months ago
Show doc for...
Tokens:
Raw
### CLI installation prompts

Source: https://xmcp.dev/docs/getting-started/installation

Example of the interactive prompts displayed during the scaffolding process.

```text
? What is your project named? (my-xmcp-app)
? Select a template: (Use arrow keys)
❯ Default (Standard MCP server)
  MCP App (React widgets for ext-apps)
```

```text
? Select a package manager: (Use arrow keys)
❯ npm 
  yarn 
  pnpm 
  bun
? Select the transport you want to use: (Use arrow keys)
❯ HTTP (runs on a server) 
  STDIO (runs on the user's machine)
? Select components to initialize: (Press <space> to select, <a> to toggle all, <i> to invert selection, and <enter> to proceed)
❯◉ Tools
 ◉ Prompts
 ◉ Resources
```

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

### Polar Plugin Setup and Configuration

Source: https://xmcp.dev/docs/integrations/polar

Instructions on how to install and configure the Polar plugin, including setting up products on Polar and initializing the PolarProvider.

```APIDOC
## Installation

Install the Polar plugin using pnpm:

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

## Polar Setup

Before integrating, set up your product on Polar:
1. Create a new product.
2. Add the **License Key** benefit.
3. (Optional) Add a **Meter Credit** benefit.

## Configuration

Initialize the Polar provider with your configuration details. The `license-key` header is required for all requests.

### Configuration Options

```typescript
interface Configuration {
  type?: "production" | "sandbox";
  token: string;
  organizationId: string;
  productId: string;
}
```

- `type`: Environment type (`production` or `sandbox`). Defaults to `production`.
- `token`: Polar authentication token.
- `organizationId`: Your Polar organization ID.
- `productId`: Your Polar product ID.

### Initialization Example

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

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

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

### HTTP Client Configuration Example

Source: https://xmcp.dev/docs/core-concepts/external-clients

An example of how to configure an HTTP client, including setting an API key via an environment variable.

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

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

### STDIO Client Configuration Examples

Source: https://xmcp.dev/docs/core-concepts/external-clients

Examples of configuring STDIO clients, including simple npm packages, packages with arguments, custom commands, and environment variables.

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

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

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

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

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

### Resource URI path example

Source: https://xmcp.dev/docs/core-concepts/resources

Example of a file path that maps to a specific resource URI.

```text
src/resources/(users)/[userId]/profile.ts
```

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

### Initialize xmcp

Source: https://xmcp.dev/docs/adapters/nextjs

Run this command in your project directory to start the xmcp initialization process.

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

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

### Complete Example: Validation and Usage Tracking

Source: https://xmcp.dev/docs/integrations/polar

A full example demonstrating the integration of license validation and usage tracking within a protected tool.

```APIDOC
## Example

Here's a complete example integrating license validation and usage tracking:

```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";
}
```
```

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

### Install dependencies manually

Source: https://xmcp.dev/docs/getting-started/installation

Install the required xmcp and zod packages using pnpm.

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

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

### Install Commet Plugin with pnpm

Source: https://xmcp.dev/docs/integrations/commet

Install the Commet plugin using pnpm. Ensure you have Node.js and pnpm installed.

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

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

### Example Server Execution Command

Source: https://xmcp.dev/docs/discoverability/smithery

Shows how Smithery translates schema fields into command-line arguments for stdio servers.

```bash
your-server --api-key=sk-xxx --model=gpt-4
```

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

### Install x402 plugin

Source: https://xmcp.dev/docs/integrations/x402

Use your preferred package manager to add the x402 dependency.

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

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

### Complete Example: Protected Tool

Source: https://xmcp.dev/docs/integrations/polar

A full example integrating license validation and usage tracking for a protected tool. This ensures only valid license holders can execute the tool and tracks their usage.

```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";
}
```

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

### Run local development environment

Source: https://xmcp.dev/docs/deployment/cloudflare

Start the xmcp watcher and Wrangler dev server simultaneously for local testing.

```bash
pnpm dev
```

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

### Install Clerk Plugin

Source: https://xmcp.dev/docs/integrations/clerk

Command to install the Clerk plugin dependency.

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

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

### Get User Details

Source: https://xmcp.dev/docs/integrations/clerk

Example tool implementation using getUser to retrieve authenticated user information.

```typescript
import type { ToolMetadata } from "xmcp";
import { getUser } from "@xmcp-dev/clerk";

// Define tool metadata
export const metadata: ToolMetadata = {
  name: "get-user-info",
  description: "Get user details",
};

// Tool implementation
export default async function getUserInfo(): Promise<string>  {
  const user = await getUser();

  return JSON.stringify(user, null, 2);
}
```

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

### Install WorkOS Plugin

Source: https://xmcp.dev/docs/integrations/workos

Use pnpm to install the WorkOS package for your project.

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

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

### Install Polar Plugin

Source: https://xmcp.dev/docs/integrations/polar

Install the Polar plugin using pnpm. Ensure you have Node.js and pnpm installed.

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

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

### Initialize xmcp Project with Vercel CLI

Source: https://xmcp.dev/docs/deployment/vercel

Initialize a new xmcp project using Vercel CLI. This command clones the xmcp example repository.

```bash
vc init xmcp
```

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

### Configure package.json scripts

Source: https://xmcp.dev/docs/getting-started/installation

Define development, build, and production start scripts in your package.json file.

```json
{
  "scripts": {
    "dev": "xmcp dev",
    "build": "xmcp build",
    "start": "node dist/[transport].js"
  }
}
```

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

### Configure multiple transport scripts

Source: https://xmcp.dev/docs/getting-started/installation

Example of package.json scripts configured to support both HTTP and STDIO transports.

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

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

### Example of Prompt Loading Error Log (Empty File)

Source: https://xmcp.dev/docs/core-concepts/prompts

This log output shows the warning message generated when xmcp encounters an empty prompt file during startup.

```log
[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
```

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

### Install Auth0 Plugin with pnpm

Source: https://xmcp.dev/docs/integrations/auth0

Use this command to install the Auth0 plugin for your MCP server using pnpm.

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

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

### Install Better Auth and PostgreSQL Dependencies

Source: https://xmcp.dev/docs/integrations/better-auth

Use pnpm to install the necessary packages for Better Auth and PostgreSQL, including TypeScript types.

```bash
pnpm i @xmcp-dev/better-auth pg
pnpm i -D @types/pg
```

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

### Install Tailwind CSS

Source: https://xmcp.dev/docs/core-concepts/css

Install the necessary Tailwind CSS dependencies using your preferred package manager.

```bash
pnpm add -D tailwindcss @tailwindcss/postcss
```

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

### Tool Loading Error Logs

Source: https://xmcp.dev/docs/core-concepts/tools

Examples of console output when tool files are empty or missing a default export.

```text
[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
```

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

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

### Install JWT Dependencies

Source: https://xmcp.dev/docs/adapters/nestjs

Required packages for implementing JWT authentication.

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

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

### Resource loading error logs

Source: https://xmcp.dev/docs/core-concepts/resources

Example console output when a resource file is empty or missing a default export.

```text
[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
```

```text
[xmcp] Failed to load resource file: src/resources/(drafts)/latest.ts
   -> File does not export a default resource handler.
```

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

### Deploy xmcp Project with Vercel CLI

Source: https://xmcp.dev/docs/deployment/vercel

Use this command to deploy your xmcp project. Ensure Vercel CLI is installed and you are in your project directory.

```bash
vc deploy
```

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

### Bootstrap New xmcp Project for Alpic

Source: https://xmcp.dev/docs/deployment/alpic

Use this command to clone the xmcp template repository and set up zero-configuration deployment to Alpic. This is the recommended way to start a new project.

```bash
npx @alpic/cli bootstrap
```

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

### Retrieve Organization via Clerk SDK

Source: https://xmcp.dev/docs/integrations/clerk

Example tool implementation using getClient to access the full Clerk Backend SDK.

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

export default async function getOrganization() {
  const session = getSession();
  const clerk = getClient();

  if (!session.organizationId) {
    return "User is not in an organization";
  }

  const org = await clerk.organizations.getOrganization({
    organizationId: session.organizationId,
  });

  return JSON.stringify(org, null, 2);
}
```

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

### Define a tool with schema and metadata

Source: https://xmcp.dev/docs/core-concepts/tools

A complete example of a tool file including Zod schema, metadata, and the default handler function.

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

// Define the schema for tool parameters
export const schema = {
  name: z.string().describe("The name of the user to greet"),
};

// Define tool metadata
export const metadata = {
  name: "greet",
  description: "Greet the user",
  annotations: {
    title: "Greet the user",
    readOnlyHint: true,
    destructiveHint: false,
    idempotentHint: true,
  },
};

// Tool implementation
export default async function greet({ name }: InferSchema<typeof schema>) {
  return `Hello, ${name}!`;
}
```

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

### Define a Tool for XMCP

Source: https://xmcp.dev/docs

Example of defining a tool with input schema and metadata for an XMCP server. This tool fetches weather information.

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

export const schema = {
  location: z.string().describe("City name"),
};

export const metadata = {
  name: "get-weather",
  description: "Get current weather for a location",
};

export default async function getWeather({
  location
}: InferSchema<typeof schema>) {
  // Your implementation here
  return `Weather in ${location}: 72°F, Sunny`;
}
```

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

### Example of Prompt Loading Error Log (Missing Default Export)

Source: https://xmcp.dev/docs/core-concepts/prompts

This log output shows the warning message generated when xmcp encounters a prompt file that does not export a default handler during startup.

```log
[xmcp] Failed to load prompt file: src/prompts/draft.ts
   -> File does not export a default prompt handler.
```

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

### Testing with curl

Source: https://xmcp.dev/docs/adapters/nestjs

Provides examples of how to test MCP endpoints using curl, with and without authentication.

```APIDOC
## Testing with curl

### Description
Examples of how to test MCP endpoints using curl, demonstrating requests with and without authentication.

### Request Examples

#### Without authentication (if `required: false`)
```bash
curl -X POST http://localhost:3000/mcp \
  -H "Content-Type: application/json" \
  -d '{"jsonrpc":"2.0","method":"tools/list","id":1}'
```

#### With authentication
```bash
curl -X POST http://localhost:3000/mcp \
  -H "Content-Type: application/json" \
  -H "Authorization: Bearer <your-jwt-token>" \
  -d '{"jsonrpc":"2.0","method":"tools/list","id":1}'
```
```

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

### Using Generated Clients in TypeScript

Source: https://xmcp.dev/docs/core-concepts/external-clients

Import and use the generated clients to interact with MCP services. This example shows how to call the 'getLibraryDocs' tool.

```typescript
import { InferSchema, type ToolMetadata } from "xmcp";
import { generatedClients } from "../generated/client.index";
import { z } from "zod";

export const schema = {
  libraryName: z.string().describe("The name of the library"),
};

export const metadata: ToolMetadata = {
  name: "get-library-docs",
  description: "Get documentation for a library",
};

export default async function handler({
  libraryName,
}: InferSchema<typeof schema>) {
  const docs = await generatedClients.context.getLibraryDocs({
    context7CompatibleLibraryID: libraryName,
  });
  return (docs.content as any)[0].text;
}
```

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

### Greet User with Clerk Identity

Source: https://xmcp.dev/docs/integrations/clerk

Example tool implementation using getSession to access the authenticated user's ID.

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

// Define the schema for tool parameters
export const schema = {
  name: z.string().describe("The name of the user to greet"),
};

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

// Tool implementation
export default function greet({ name }: InferSchema<typeof schema>): string {
  const session = getSession();

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

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

### Create Interactive Widget with React Component Handler

Source: https://xmcp.dev/docs/core-concepts/tools

Return React components for interactive, composable widgets. XMCP renders the component to HTML and generates a widget resource automatically. Ensure `.tsx` file extension and install React dependencies.

```typescript
import { type ToolMetadata } from "xmcp";
import { useState } from "react";

export const metadata: ToolMetadata = {
  name: "interactive-todo",
  description: "Interactive todo list widget",
  _meta: {
    ui: {
      prefersBorder: true,
    },
  },
};

export default function InteractiveTodo() {
  const [todos, setTodos] = useState<string[]>([]);
  const [input, setInput] = useState("");

  const addTodo = () => {
    if (input.trim()) {
      setTodos([...todos, input]);
      setInput("");
    }
  };

  return (
    <div>
      <h2>Todo List</h2>
      <input
        type="text"
        value={input}
        onChange={(e) => setInput(e.target.value)}
        placeholder="Add a todo..."
      />
      <button onClick={addTodo}>Add</button>
      <ul>
        {todos.map((todo, idx) => (
          <li key={idx}>{todo}</li>
        ))}
      </ul>
    </div>
  );
}
```

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

### Scaffold a new project

Source: https://xmcp.dev/docs/getting-started/installation

Use the CLI tool to initialize a new xmcp project with a template.

```bash
npx create-xmcp-app@latest
```

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

### Create a New XMCP App

Source: https://xmcp.dev/docs

Use this command to initialize a new XMCP project. It prompts for project name, package manager, transport protocol, and components.

```bash
$npx create-xmcp-app@latest
```
? What is your project named? my-server
? Select a package manager: pnpm
? Select the transport you want to use: HTTP (runs on a server)
? Select components to initialize:
  ◉ Tools
  ◉ Prompts
  ◉ Resources

✔ Creating a new xmcp app in ...
✔ Your xmcp app is ready

Next steps:
  cd my-server
  pnpm dev

```
```

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

### Initialize a new xmcp project for Cloudflare

Source: https://xmcp.dev/docs/deployment/cloudflare

Use the --cloudflare flag with the create-xmcp-app tool to bootstrap a project with necessary Wrangler configurations.

```bash
npx create-xmcp-app@latest my-xmcp-app --cloudflare
```

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

### Set up the x402 provider

Source: https://xmcp.dev/docs/integrations/x402

Initialize the provider in your middleware to handle payment configurations.

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

export default x402Provider({
  wallet: process.env.X402_WALLET!,
  defaults: {
    price: 0.01,
    network: "base-sepolia",
  },
});
```

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

### CLI Scaffolding Commands

Source: https://xmcp.dev/docs/core-concepts/tools

Commands to generate starter files for tools, resources, and prompts.

```bash
xmcp create tool my-tool
```

```bash
xmcp create resource my-resource
```

```bash
xmcp create prompt my-prompt
```

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

### Initialization Prompts

Source: https://xmcp.dev/docs/adapters/nextjs

The prompts displayed during the initialization process to define directory paths.

```text
? Tools directory path: (tools)
? Prompts directory path: (prompts)
? Resources directory path: (resources)
? Route directory path: (app/mcp)
```

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

### Configure environment variables

Source: https://xmcp.dev/docs/integrations/x402

Define the wallet address and optional facilitator URL in your .env file.

```text
X402_WALLET=0x...

# Optional: Custom facilitator URL (defaults to https://x402.org/facilitator)
X402_FACILITATOR=https://x402.org/facilitator
```

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

### Configure XMCP Adapter

Source: https://xmcp.dev/docs/adapters/nestjs

Sets up the adapter configuration in the application root.

```typescript
import { type XmcpConfig } from "xmcp";

const config: XmcpConfig = {
  http: true,
  experimental: {
    adapter: "nestjs",
  },
};

export default config;
```

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

### Get User Details

Source: https://xmcp.dev/docs/integrations/workos

Fetch full user information using the getUser helper function.

```typescript
import type { ToolMetadata } from "xmcp";
import { getUser } from "@xmcp-dev/workos";

// Define tool metadata
export const metadata: ToolMetadata = {
  name: "get-user-info",
  description: "Get user details"
};

// Tool implementation
export default async function getUserInfo(): Promise<string> {
  const user = await getUser();
  return JSON.stringify(user, null, 2);
}
```

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

### Define MCP Route Handler

Source: https://xmcp.dev/docs/adapters/nextjs

Export the xmcpHandler as GET and POST methods in your Next.js route file.

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

export { xmcpHandler as GET, xmcpHandler as POST };
```

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

### Configure Build and Dev Scripts

Source: https://xmcp.dev/docs/adapters/express

Update your package.json scripts to include xmcp commands for development and building.

```json
{
  "scripts": {
    "dev": "xmcp dev & existing-build-command",
    "build": "xmcp build && existing-build-command"
  }
}
```

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

### Basic XMCP Project Structure

Source: https://xmcp.dev/docs/getting-started/project-structure

Illustrates the default directory layout for an XMCP project, including source files, build output, and configuration.

```tree
my-project/
├── src/
│   ├── middleware.ts   # Middleware for http request/response processing
│   └── tools/          # Tool files are auto-discovered here
│       ├── greet.ts
│       ├── search.ts
│   └── prompts/          # Prompt files are auto-discovered here
│       ├── review-code.ts
│       ├── team-greeting.ts
│   └── resources/      # Resource files are auto-discovered here
│       ├── (config)/app.ts
│       ├── (users)/[userId]/profile.ts
├── dist/               # Built output (generated)
├── package.json
├── tsconfig.json
└── xmcp.config.ts       # Configuration file for xmcp
```

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

### Set up WorkOS Provider

Source: https://xmcp.dev/docs/integrations/workos

Initialize the WorkOS provider in your middleware file using environment variables.

```typescript
import { workosProvider } from "@xmcp-dev/workos";

export default workosProvider({
  apiKey: process.env.WORKOS_API_KEY!,
  clientId: process.env.WORKOS_CLIENT_ID!,
  authkitDomain: process.env.WORKOS_AUTHKIT_DOMAIN!,
  baseURL: process.env.BASE_URL!,
});
```

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

### Configure Environment Variables

Source: https://xmcp.dev/docs/integrations/workos

Define the required WorkOS credentials and base URL in your .env file.

```text
WORKOS_API_KEY=sk_...
WORKOS_CLIENT_ID=client_...
WORKOS_AUTHKIT_DOMAIN=yourcompany.authkit.app

BASE_URL=http://127.0.0.1:3001
```

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

### Run the xmcp Client Generator

Source: https://xmcp.dev/docs/core-concepts/external-clients

Execute the xmcp CLI generator from your project root to create client files. This command reads from src/clients.ts and writes to src/generated/.

```bash
npx @xmcp-dev/cli generate
```

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

### Get Organization Memberships

Source: https://xmcp.dev/docs/integrations/workos

Access the full WorkOS SDK via getClient to perform advanced operations like listing organization memberships.

```typescript
import { type ToolMetadata } from "xmcp";
import { getSession, getClient } from "@xmcp-dev/workos";

export const metadata: ToolMetadata = {
  name: "get-my-memberships",
  description: "Returns the user's organization memberships using the WorkOS SDK directly"
};

export default async function getMyMemberships(): Promise<string> {
  const session = getSession();
  const client = getClient();

  // Use the WorkOS SDK to fetch organization memberships
  const memberships = await client.userManagement.listOrganizationMemberships({
    userId: session.userId,
  });

  if (memberships.data.length === 0) {
    return "You are not a member of any organizations.";
  }

  return JSON.stringify(memberships.data, null, 2);
}
```

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

### Add xmcp Handler to Express App

Source: https://xmcp.dev/docs/adapters/express

Import and use the xmcpHandler in your Express routes to handle requests. This should be added to your existing server setup.

```typescript
import { xmcpHandler } from "path/to/.xmcp/adapter";

app.get("/mcp", xmcpHandler);

app.post("/mcp", xmcpHandler);
```

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

### Deploy XMCP Server with Vercel

Source: https://xmcp.dev/docs

Command to deploy your XMCP server to Vercel. Shows a sample deployment summary.

```bash
$vc deploy
```
Vercel CLI 37.0.0
Inspect: https://vercel.com/...
Production: https://my-server.vercel.app

Deployment Summary:
  • Environment: Production
  • Region: iad1
  • Build Time: 12s
  • Status: Ready

Your MCP server is live!
```
```

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

### Publish Stdio Server via CLI

Source: https://xmcp.dev/docs/discoverability/smithery

Use the Smithery CLI to publish a stdio-based server to the marketplace.

```bash
smithery mcp publish --name @your-org/your-server --transport stdio
```

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

### Get Customer Billing Portal URL

Source: https://xmcp.dev/docs/integrations/commet

Retrieve the customer's billing portal URL for managing subscriptions. This function requires access to the XMCP client and customer ID.

```typescript
import type { ToolMetadata } from "xmcp";
import { getClient, getCustomerId } from "@xmcp-dev/commet";

export const metadata: ToolMetadata = {
  name: "manage-billing",
  description: "Get the customer's billing portal link",
};

export default async function manageBilling(): Promise<string> {
  const client = getClient();
  const customerId = getCustomerId();
  const response = await client.customer(customerId).portal.getUrl();

  if (!response.success || !response.data) {
    return "Unable to retrieve billing portal.";
  }

  return `Manage your subscription: ${response.data.portalUrl}`;
}
```

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

### Set up Clerk Provider

Source: https://xmcp.dev/docs/integrations/clerk

Initialize the Clerk provider in the middleware file.

```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!
});
```

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

### Track Usage for AI Generate Tool

Source: https://xmcp.dev/docs/integrations/commet

Track metered usage for the 'ai_generate' feature. This example reports 1 unit per call, suitable for AI token consumption or similar metered features.

```typescript
import { z } from "zod";
import type { InferSchema, ToolMetadata } from "xmcp";
import { getClient, getCustomerId } from "@xmcp-dev/commet";

export const schema = {
  prompt: z.string().describe("The prompt to generate content from"),
};

export const metadata: ToolMetadata = {
  name: "ai_generate",
  description: "Generate content with AI, tracks 1 unit per call",
};

export default async function aiGenerate({
  prompt,
}: InferSchema<typeof schema>) {
  const client = getClient();
  const customerId = getCustomerId();

  const { data } = await client.customer(customerId).features.check("ai_generate");

  if (!data?.allowed) {
    return "Your plan does not include this feature.";
  }

  await client.usage.track({
    feature: "ai_generate",
    customerId,
    value: 1,
  });

  return `Generated content for: "${prompt}"
```

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

### Greet User with Auth0 Identity

Source: https://xmcp.dev/docs/integrations/auth0

Use `getAuthInfo()` to access the authenticated user's session data, including their name and Auth0 user ID. This tool requires no special setup beyond standard XMCP configuration.

```typescript
import {
  z,
  InferSchema,
  ToolMetadata,
} from "xmcp";
import { getAuthInfo } from "@xmcp-dev/auth0";

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 Auth0 identity",
};

export default function greet({ name }: InferSchema<typeof schema>): string {
  const authInfo = getAuthInfo();
  const displayName = authInfo.user.name ?? name ?? "there";
  return `Hello, ${displayName}! Your Auth0 user ID is ${authInfo.user.sub}`;
}
```

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

### Configure Better Auth Environment Variables

Source: https://xmcp.dev/docs/integrations/better-auth

Set up essential environment variables for database connection, Better Auth secret, and base URL. Optional variables for OAuth providers are also included.

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

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

### STDIO Client Configuration

Source: https://xmcp.dev/docs/core-concepts/external-clients

Configure STDIO clients to spawn local processes that communicate via standard input/output. Suitable for local development.

```APIDOC
## STDIO Clients (local servers)

STDIO clients spawn local processes that communicate via standard input/output.

```typescript
type StdioClientConfig = {
  name?: string; // Optional, defaults to object key
  type?: "stdio"; // Optional, inferred from npm/command
  command?: string; // Command to run (e.g., "npx", "bunx", "node")
  args?: string[]; // Command arguments
  npm?: string; // npm package to run via npx
  npmArgs?: string[]; // Arguments to pass to npm package
  env?: Record<string, string>; // Environment variables
  cwd?: string; // Working directory
  stderr?: "pipe" | "inherit" | "ignore"; // Stderr handling
};
```

### Examples

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

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

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

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

The npm package will be installed automatically if it is not already installed in your project.
```

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

### Running the Generator

Source: https://xmcp.dev/docs/core-concepts/external-clients

Execute the xmcp CLI to generate TypeScript clients from your `clients.ts` configuration.

```APIDOC
## Running the Generator

Run the generator from your project root:

```bash
npx @xmcp-dev/cli generate
```

This reads from `src/clients.ts` and writes generated clients to `src/generated/`.

**Options:**
  * `-o, --out <path>` - Output directory (default: `src/generated`)
  * `-c, --clients <path>` - Clients file path (default: `src/clients.ts`)
```

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

### Configure Build Scripts

Source: https://xmcp.dev/docs/adapters/nextjs

Update your package.json scripts to include xmcp build and dev processes.

```json
{
  "scripts": {
    "dev": "xmcp dev & next dev",
    "build": "xmcp build && next build"
  }
}
```

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

### Create PostgreSQL Tables for Better Auth

Source: https://xmcp.dev/docs/integrations/better-auth

Run this SQL script to set up the required tables in your PostgreSQL database for user management, sessions, and OAuth.

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

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

### Configure x402 middleware

Source: https://xmcp.dev/docs/guides/monetization

Set global payment defaults for the x402 provider to handle crypto payment requirements.

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

export default x402Provider({
  wallet: process.env.X402_WALLET,
  defaults: {
    price: 0.01,
    currency: "USDC",
    network: "base",
  },
});
```

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

### Initialize Better Auth Provider in Middleware

Source: https://xmcp.dev/docs/integrations/better-auth

Set up the Better Auth middleware in your xmcp app, configuring the PostgreSQL database connection, base URL, secret, and authentication providers.

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

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

### Configure Custom Directories for xmcp

Source: https://xmcp.dev/docs/configuration/custom-directories

Set custom paths for tools, prompts, and resources in your `xmcp.config.ts` file. If not specified, default paths are used.

```typescript
const config: XmcpConfig = {
  paths: {
    tools: "src/tools",
    prompts: "src/prompts",
    resources: "src/resources",
  },
};

export default config;
```

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

### Configure Environment Variables

Source: https://xmcp.dev/docs/integrations/clerk

Required environment variables for Clerk integration in the project root .env file.

```text
CLERK_SECRET_KEY=sk_...
CLERK_DOMAIN=your-app.clerk.accounts.dev

BASE_URL=http://127.0.0.1:3001
```

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

### Accessing Auth Info in Tools

Source: https://xmcp.dev/docs/adapters/nestjs

Demonstrates how to access authentication and client information within MCP tools.

```APIDOC
## Accessing Auth Info in Tools

### Description
Auth info is available in tools via the `extra` argument, allowing access to authenticated user and client details.

### Example Usage (whoami.ts)
```typescript
import { type ToolMetadata, type ToolExtraArguments } from "xmcp";

export const schema = {};

export const metadata: ToolMetadata = {
  name: "whoami",
  description: "Returns information about the authenticated user",
};

export default async function whoami(
  _args: unknown,
  extra: ToolExtraArguments
) {
  const authInfo = extra.authInfo;
  const clientInfo = extra.clientInfo;

  if (!authInfo) {
    return "Not authenticated";
  }

  return JSON.stringify(
    {
      clientId: authInfo.clientId,
      scopes: authInfo.scopes,
      clientName: clientInfo?.name,
      clientVersion: clientInfo?.version,
    },
    null,
    2
  );
}
```
```

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

### Configure STDIO transport for local development

Source: https://xmcp.dev/docs/getting-started/connecting

Use this JSON configuration to connect to an MCP server via STDIO, requiring an absolute path to the server's entry point.

```json
{
  "mcpServers": {
    "my-project": {
      "command": "node",
      "args": ["/ABSOLUTE/PATH/TO/my-project/dist/stdio.js"]
    }
  }
}
```

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

### Build Cloudflare Workers bundle

Source: https://xmcp.dev/docs/deployment/cloudflare

Generate the worker.js bundle and Wrangler configuration using either pnpm or the xmcp CLI.

```bash
pnpm build
# or
xmcp build --cf
```

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

### Define standard CSS styles

Source: https://xmcp.dev/docs/core-concepts/css

Create a global CSS file to define standard styles for your components.

```css
.title {
  font-size: 2rem;
  font-weight: bold;
}
```

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

### Implement 'whoami' Tool

Source: https://xmcp.dev/docs/adapters/nestjs

This tool retrieves and returns authenticated user information, including client ID, scopes, and client details, from the `extra` arguments. Ensure `authInfo` is present before accessing its properties.

```typescript
import { type ToolMetadata, type ToolExtraArguments } from "xmcp";

export const schema = {};

export const metadata: ToolMetadata = {
  name: "whoami",
  description: "Returns information about the authenticated user",
};

export default async function whoami(
  _args: unknown,
  extra: ToolExtraArguments
) {
  const authInfo = extra.authInfo;
  const clientInfo = extra.clientInfo;

  if (!authInfo) {
    return "Not authenticated";
  }

  return JSON.stringify(
    {
      clientId: authInfo.clientId,
      scopes: authInfo.scopes,
      clientName: clientInfo?.name,
      clientVersion: clientInfo?.version,
    },
    null,
    2
  );
}
```

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

### Initialize Polar Provider

Source: https://xmcp.dev/docs/integrations/polar

Initialize the Polar provider with your environment configuration. Use 'sandbox' or 'production' for the type and provide necessary tokens and IDs.

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

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

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

### Configure Server Name and Description

Source: https://xmcp.dev/docs/configuration/server-info

Set the display name and description for your MCP server. These fields are used in the MCP initialize response.

```typescript
const config: XmcpConfig = {
  template: {
    name: "My MCP Server",
    description: "A server that does amazing things.",
  },
};
```

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

### Troubleshooting

Source: https://xmcp.dev/docs/adapters/nestjs

Common troubleshooting steps for issues related to MCP module generation and TypeScript path resolution.

```APIDOC
## Troubleshooting

### Cannot find module '@xmcp/adapter'

#### Description
This error occurs when the `.xmcp` directory hasn't been generated yet.

#### Solution
Run `npx xmcp build` before starting your NestJS application.

### TypeScript path resolution errors

#### Description
If TypeScript can't resolve `@xmcp/*` imports.

#### Solution
1. Ensure `tsconfig.json` has the path mapping:
   ```json
   {
     "compilerOptions": {
       "paths": {
         "@xmcp/*": ["./.xmcp/*"]
       }
     }
   }
   ```
2. Ensure `.xmcp` is included in the `include` array in `tsconfig.json`:
   ```json
   {
     "include": ["src/**/*", "xmcp-env.d.ts", ".xmcp/**/*"]
   }
   ```
```

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

### Connect MCP to Alpic

Source: https://xmcp.dev/docs/deployment/alpic

This action connects your MCP to Alpic, enabling deployment. Ensure you have created an account on app.alpic.ai and connected your GitHub account.

```bash
npx @alpic/cli connect-mcp
```

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

### Configure Home Page

Source: https://xmcp.dev/docs/configuration/server-info

Customize the HTML page served at the root endpoint. Can be an inline HTML string or a path to an HTML file.

```typescript
const config: XmcpConfig = {
  template: {
    // Option 1: Inline HTML
    homePage: "<html><body><h1>Welcome!</h1></body></html>",

    // Option 2: Path to an HTML file (relative to project root)
    // homePage: "src/home.html",
  },
};
```

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

### Define CSS Modules

Source: https://xmcp.dev/docs/core-concepts/css

Create a CSS module file with the .module.css extension for scoped styles.

```css
.container {
  padding: 2rem;
}

.title {
  font-size: 2rem;
  font-weight: bold;
}
```

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

### Home Page Configuration

Source: https://xmcp.dev/docs/configuration/server-info

Customize the HTML page served at the root ('/') endpoint of your HTTP server.

```APIDOC
## Home Page Configuration

### Description
Customize the HTML content served at the `/` endpoint of your HTTP server.

### Configuration File
`xmcp.config.ts`

### Code Example (Inline HTML)
```typescript
const config: XmcpConfig = {
  template: {
    homePage: "<html><body><h1>Welcome!</h1></body></html>",
  },
};
```

### Code Example (HTML File Path)
```typescript
const config: XmcpConfig = {
  template: {
    homePage: "src/home.html",
  },
};
```

Note: If `homePage` is not provided, xmcp serves a default landing page displaying the server name and description.
```

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

### Return Simple String or Number Value

Source: https://xmcp.dev/docs/core-concepts/tools

Return strings or numbers directly for simple responses. XMCP automatically wraps them in the proper format.

```typescript
export default async function calculate() {
  return "Result: 42"; // or return 42;
}
```

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

### Monetize a tool with custom pricing

Source: https://xmcp.dev/docs/integrations/x402

Wrap tool functions with the paid decorator to enforce payment requirements.

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

export default paid(
  { price: 0.05 },
  async function analyze({ data }) {
    // Tool logic here
    return `Analysis complete for: ${data}`;
  }
);
```

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

// This tool costs 0.10 USDC per call
export default paid(
  { price: 0.10 },
  async function premiumAnalysis({ data }) {
    // Premium tool logic
    return `Premium analysis complete for: ${data}`;
  }
);
```

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

// This tool uses the provider's default price,
// or 0.01 USDC if no default is configured
export default paid(async function basicTool({ input }) {
  return `Processed: ${input}`;
});
```

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

### Configure API Key Auth Middleware

Source: https://xmcp.dev/docs/authentication/api-key

Use apiKeyAuthMiddleware to enable API key authentication. If headerName is not provided, it defaults to 'x-api-key'.

```typescript
import { apiKeyAuthMiddleware, type Middleware } from "xmcp";

const middleware: Middleware = [
  apiKeyAuthMiddleware({
    headerName: "x-api-key",
    apiKey: "12345",
  }),
  // ... other middlewares
];

export default middleware;
```

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

### Set up Auth0 Provider in middleware.ts

Source: https://xmcp.dev/docs/integrations/auth0

Configure the auth0Provider in your middleware.ts file to handle authentication. Ensure all required environment variables are set.

```typescript
import { auth0Provider } from "@xmcp-dev/auth0";

export default auth0Provider({
  domain: process.env.DOMAIN!,
  audience: process.env.AUDIENCE!,
  baseURL: process.env.BASE_URL!,
  clientId: process.env.CLIENT_ID!,
  clientSecret: process.env.CLIENT_SECRET!,
});
```

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

### Using the MCP Server Search Tool

Source: https://xmcp.dev/docs/guides/xmcp-mcp-server

The MCP server exposes a 'search' tool that agents can use automatically. You can search by a query string or retrieve a specific page using its ID.

```javascript
// Search by query
search({ query: "how to configure transports" });
```

```javascript
// Get specific page by ID
search({ id: "configuration/transports" });
```
Tokens:
Raw