Usage with Polar | xmcp Documentation

For the complete documentation index, see llms.txt. Markdown variants of every page are available by appending .md to the URL.

Overview

The Polar plugin enables you to add paywalls with license key validation and track tool usage for your xmcp server using Polar.

Installation

Install the Polar plugin:

Shell

pnpm i @xmcp-dev/polar

Polar Setup

Before integrating the plugin, set up your product on Polar:

Create a new product with your desired payment configuration
Add the License Key benefit to the product
(Optional) Add a Meter Credit benefit to track and limit tool usage

Configuration

Initialize the Polar provider to access validation methods:

src/lib/polar.ts

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

Configuration Options

TypeScript

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

type - Environment type (defaults to "production" if not set)
token - Polar authentication token
organizationId - Your Polar organization ID
productId - Your Polar product ID

Info

These examples read the license key from the license-key header and pass it explicitly to the provider.

License Key Validation

Validate license keys in your tools using the validateLicenseKey method:

TypeScript

import { headers } from "xmcp/headers";

const value = headers()["license-key"];
const licenseKey = typeof value === "string" ? value : "";
const response = await polar.validateLicenseKey(licenseKey, {
  name: "tool_call_event",
  metadata: { tool_name: "my-tool", calls: 1 },
});

Response Object

The validation response contains:

TypeScript

{
  valid: boolean;
  code: string;
  message: string;
}

Handling Invalid Keys

Return appropriate messages when validation fails:

TypeScript

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

The returned message can include a checkout URL. Return it before executing protected work; this does not automatically open checkout in the client.

Usage Tracking

Track tool usage by adding a meter credit benefit to your product and passing event objects during validation.

Meter Credit Setup

Configure a meter credit benefit in your Polar product with the appropriate limits and tracking settings.

Tracking Events

Pass an event object to validateLicenseKey to record usage:

TypeScript

const event = {
  name: "tool_call_event",
  metadata: { tool_name: "tool_name", calls: 1 },
};

const response = await polar.validateLicenseKey(licenseKey, event);

The metadata field accepts any string or number values for flexible usage tracking.

Example

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

src/tools/protected-tool.ts

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 value = headers()["license-key"];
  const licenseKey = typeof value === "string" ? value : "";

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

Polar

One framework to rule them all