From nothing to a settled test receipt, no sales call in the middle.

1Register — claim a tenant

Scaffold the edge, mint a signing key, and register your resource origin with the core. Registration pins your origin and your authoritative public key — the trust root receipt integrity rests on. No forms, no dashboard.

2Verify — the self-grading exam

"A phase is done iff its prove command is green" is the project's own law; it becomes your onboarding contract. verify runs a vendor-facing conformance slice against your integration and says, definitively, "you're done" — or exactly what's broken.

3Claim — connect Stripe

"Connect with Stripe." Connect OAuth hands over verified business identity, entity, and payouts — the entire company-details form, deleted, because Stripe already collected it. Handsel is not merchant of record on the primary rail and holds $0.

Stripe stays in test mode until you say otherwise; no live payments move.

4Connect — go live on the ladder

Point your MCP surface at the mounted routes and you're on the ladder: guest calls get a price-0 co-signed receipt, and the same grant climbs to claimed, mandated, and assured without re-onboarding.

5Three integration depths, one gradient

Vendors climb from shallow to deep exactly like users climb guest → mandated.

6The vendor edge — hello world

The whole integration is config plus your own tools. Byte-identical to what npm create @handsel/vendor --product word-count scaffolds — the one synced hello-world across the SDK docs and this site (docs:sync).

/**
 * Word Count — a Handsel MCP vendor over @handsel/mcp. One REAL deterministic tool,
 * word_count (a pure function of its input — no dataset, no inference, no network on
 * the answer path), sits behind the Handsel ladder: @handsel/sdk enforces guest/claimed
 * quota, the 401/403 challenges, and receipts. Configure via env (see .env.example).
 */
import { serveMcpVendor } from '@handsel/mcp'
import { McpServer } from '@modelcontextprotocol/sdk/server/mcp.js'
import { z } from 'zod'

const env = z
  .object({
    HANDSEL_CORE: z.string().url(),
    VENDOR_RESOURCE: z.string().url(),
    VENDOR_SIGNING_SEED: z
      .string()
      .regex(/^[0-9a-fA-F]{64}$/, 'expected a 64-hex Ed25519 seed from `handsel keygen`')
      .optional(),
    VENDOR_SECRET: z.string().optional(),
    CORE_SECRET: z.string().optional(),
    PORT: z.coerce.number().int().positive().optional(),
  })
  .parse(process.env)

await serveMcpVendor({
  product: 'word-count',
  name: 'Word Count',
  resource: env.VENDOR_RESOURCE,
  handselCore: env.HANDSEL_CORE,
  ...(env.VENDOR_SIGNING_SEED ? { signingSeed: env.VENDOR_SIGNING_SEED } : {}),
  ...(env.VENDOR_SECRET ? { vendorSecret: env.VENDOR_SECRET } : {}),
  ...(env.CORE_SECRET ? { coreSecret: env.CORE_SECRET } : {}),
  // Pricing models — the receipt bills price_usd_micros * units (patterns: the
  // @handsel/sdk README, "Pricing models"). Beyond per-call flat:
  //   metered       — unit: 'token' + onCall: (body) => ({ units: yourCount(body) })
  //   success-gated — bill_on_miss: false + onCall: (body) => ({ miss: wasEmpty(body) })
  //   freemium      — price_usd_micros: 0 (calls co-sign price-0 proof-of-use receipts)
  pricing: { unit: 'call', price_usd_micros: 500 },
  tiers: { guest: { calls_per_day: 5 }, claimed: { calls_per_day: 500 } },
  terms: 'Word Count demo vendor. Calls are metered per the vendor-signed schedule.',
  port: env.PORT ?? 8787,
  // Return a fresh MCP server per request; @handsel/mcp owns the transport. Register
  // your real tools here — word_count is pure + deterministic (Covenant 3).
  buildServer: () => {
    const server = new McpServer({ name: 'word-count', version: '0.1.0' })
    server.registerTool(
      'word_count',
      {
        title: 'Count words',
        description:
          'Count the whitespace-separated words in a string. Deterministic; no dataset, no inference.',
        inputSchema: { text: z.string().describe('The text to count words in.') },
      },
      ({ text }) => {
        const trimmed = text.trim()
        const count = trimmed === '' ? 0 : trimmed.split(/\s+/).length
        return { content: [{ type: 'text' as const, text: String(count) }] }
      },
    )
    return server
  },
})