Expansion Pack Quickstart

The expansion pack turns agent-side revenue moments — free-tier limits, trial gates, usage walls, feature gates — into Stripe-powered conversion, inside your own MCP server. One import; your entitlement logic stays yours; fail-open by design.

You need: a TypeScript MCP server built on @modelcontextprotocol/sdk (McpServer), and an Inception Agents account. Stripe is optional until you want to convert (analytics posture works without it).

1. Install

npm install @inception-agents/expansion-pack

2. Mint an API key

In your dashboard, open Settings → API Keys and mint a server key (sk_…). Set it as INCEPTION_API_KEY in your server’s environment.

3. Register the pack

import { McpServer } from '@modelcontextprotocol/sdk/server/mcp.js';
import { registerExpansionPack } from '@inception-agents/expansion-pack';

const server = new McpServer({ name: 'your-server', version: '1.0.0' });

// ...your existing tools, unchanged...

registerExpansionPack(server, {
  apiKey: process.env.INCEPTION_API_KEY!,

  // YOUR entitlement logic — runs locally in your server. Return
  // { allowed: true } to pass through, or a blocked verdict with the
  // reason. Blocked verdicts become recorded revenue moments.
  resolveEntitlement: async ({ subjectRef, action }) => {
    return checkYourPlanLimits(subjectRef, action);
  },

  // Pseudonymous end-user reference — hash your user/workspace id.
  // Never raw PII. Without it, walls are anonymous (still counted).
  getSubjectRef: (extra) => hashUserId(extra),
});

Config-only alternative: if your plans live in Stripe Billing + Entitlements, skip resolveEntitlement and set entitlementSource: 'stripe' (plus getStripeCustomerId and a capabilities declaration). Inception reads your own connected Stripe for the verdict — no entitlement code to write.

Both modes are fail-open: if Inception is unreachable, your tools keep working and verdicts pass through as allowed. Our outage can never break your server.

4. Trigger your first moment

Deploy, then hit a gated tool through any MCP host (Claude, Cursor, ChatGPT — or the MCP Inspector). When your entitlement check returns a blocked verdict:

• the wall appears in Dashboard → Expansion → Walls, with its trigger context;
• unrealized revenue starts accumulating (moments × recommended plan price);
• with Stripe connected, the user sees the upgrade path in the thread — checkout, portal, or admin approval — and the task resumes after payment.

This works at analytics posture with zero Stripe setup: you see every moment before you convert any of them. A quiet first week is normal — the dashboard measures the agent-side demand you already have.

5. Next steps

• Connect Stripe (Dashboard → Integrations → Stripe) to turn walls into checkouts on your own connected account. Inception never touches card data and holds no entitlement authority.
• Tune the playbook — posture ladder (walls-only by default), frequency caps, quiet segments, per-lifecycle postures, and a draft → approve → apply flow for offer copy.
• Declare capabilities (capabilities option) so blocked-action copy gets precise: which capability each tool needs, and which plans include it.
• Trials: register a provisionTrial hook and the start_trial tool activates free trials in your own system — trials are always free; a trial converting later is a first-class, deterministically attributed conversion.

The SDK embed is the canonical integration: the pack runs inside your server, in your infrastructure. Inception does not host your MCP server.