License Management

mcp2p uses a four-gate validation model to ensure every payment operation is authorized, rate-limited, and audited. This page explains how the model works, the available license tiers, the key format, and how to create and programmatically validate license keys.

The 4-gate model

Enforcement happens at four distinct layers. Each gate independently blocks unauthorized usage — a compromised gate does not defeat the others.

Gate 1

Build-time type check

The createMcp2pServer function requires a licenseKey field in its config object. TypeScript will produce a compile error if the field is missing or the wrong type. This is your first guardrail — it is impossible to build a valid server without providing a license key.

Gate 2

Runtime startup validation

When the server starts, the SDK sends the license key to the mcp2p license server for validation. The server checks that the key exists, is active, and that the requested rails are covered by the license tier. If validation fails, the server exits with a descriptive error. Results are cached for 5 minutes (configurable).

Gate 3

Per-call entitlement check

Before executing each payment tool call, the SDK checks: Is this rail enabled for this license? Has the monthly transaction rate limit been reached? Is the license still within its validity window? Any failure here aborts the tool call and returns a license error to the AI client.

Gate 4

Async usage reporting

After each successful tool call, the SDK asynchronously reports usage to the license server (fire-and-forget). This data feeds the analytics dashboard and billing system. The fire-and-forget pattern means a reporting failure never blocks a payment.

Tier comparison

Choose the tier that matches your production requirements. All tiers include full access to sandbox testing at no additional cost.

TierRailsTransactionsKeysSupportPricing
SandboxMock rails onlyUnlimited1CommunityFree
Starter1 live rail1,000 / mo2EmailContact sales
GrowthPopular3 live rails10,000 / mo10Priority emailContact sales
EnterpriseAll railsCustomUnlimitedDedicatedCustom
Sandbox keys are created automatically when you register. They enable unlimited testing against mock rails with no real funds. Mock rails simulate the full 2FA flow, error scenarios, and response shapes of live rails.

Key format

All mcp2p license keys follow the format mcp2p_[env]_[hash] where:

  • mcp2p — Fixed prefix, identifies the key as an mcp2p license key.
  • [env] — Either live (production) or test (sandbox).
  • [hash] — A 32-character alphanumeric random identifier.

mcp2p_live_a1b2c3d4e5f6g7h8i9j0k1l2m3n4

Production key

mcp2p_test_a1b2c3d4e5f6g7h8i9j0k1l2m3n4

Sandbox key

Keys are SHA-256 hashed before storage in the database. The plain-text key is shown exactly once at creation time. Copy it immediately to your password manager or secrets vault — it cannot be recovered. If lost, create a new key and revoke the old one.

Creating keys via the dashboard

  1. Log into app.mcp2p.dev and open your organization.
  2. Navigate to Settings → License Keys.
  3. Click New Key. Select the environment (test or live), give the key a descriptive name (e.g., “Production Server A”), and optionally set an expiry date.
  4. Click Create. Copy the plain-text key displayed — this is the only time it will be shown.
  5. Store the key in your secrets manager and add it to your server's environment as MCP2P_LICENSE_KEY.

Validating keys programmatically

For tooling, CI pipelines, or administrative scripts, you can validate a license key directly against the mcp2p license server REST API:

// GET /api/v1/license/validate
// Authorization: Bearer <license-key>

const response = await fetch("https://license.mcp2p.dev/api/v1/license/validate", {
  headers: {
    Authorization: `Bearer ${process.env.MCP2P_LICENSE_KEY}`,
  },
});

const { data, error } = await response.json();

if (error) {
  console.error("License invalid:", error.code, error.message);
} else {
  console.log("License valid:", {
    tier: data.tier,          // "sandbox" | "starter" | "growth" | "enterprise"
    env: data.env,            // "test" | "live"
    rails: data.rails,        // ["spei", "pse", "pix"]
    expiresAt: data.expiresAt, // ISO 8601 or null for never
    usage: {
      thisMonth: data.usage.thisMonth,
      limit: data.usage.limit,
    },
  });
}

Response shape

FieldTypeDescription
tierstringLicense tier name
envstring"test" or "live"
railsstring[]Enabled rail identifiers
expiresAtstring | nullISO 8601 expiry, or null if never
usage.thisMonthnumberTransactions used in the current billing period

Revoking a key

To revoke a key, go to Settings → License Keys in the dashboard, find the key, and click Revoke. Revocation takes effect immediately — the next time the SDK tries to validate the key at Gate 2 or Gate 3, it will receive a LICENSE_REVOKED error and refuse to execute payment operations.

The SDK caches valid license responses for up to 5 minutes (configurable). A revoked key may continue to work for up to 5 minutes after revocation if the cached result has not yet expired. For immediate termination, reduce cacheTtlSeconds to 0 in your server config and restart the server.

Next steps