@boomin/mcp

Shared MCP protocol implementation for Boomin referral program installation, program operation, and Distribution operation. It powers the hosted MCP at mcp.boomin.ai (served from services/mcp) and is not published to npm.

Install into Claude Code:

claude mcp add --transport http boomin https://mcp.boomin.ai/mcp

Remote clients can authorize through Boomin's browser flow. The MCP server advertises OAuth metadata at:

https://mcp.boomin.ai/.well-known/oauth-authorization-server

The browser consent flow signs the admin in with Boomin email OTP, asks for an organization and skill packs, then exchanges an authorization code for a scoped sk_boomin_live_... platform token.

The write-bearing packs (program_operator, distribution_operator) must be explicitly granted through the hosted consent flow or npx @boomin/cli mcp install --pack distribution_operator.

Skill packs

| Pack | Tools | What it is for | | --- | --- | --- | | referral_installer (default) | boomin_doctor, boomin_detect_project, boomin_get_connect_config, boomin_provision_handoff, boomin_scaffold_referral_first, boomin_verify_referral_install, boomin_get_partner_standing, boomin_record_test_event | Get a referral program installed in someone's app and prove it works. | | program_operator | boomin_get_program, boomin_update_program, boomin_update_required_channels, boomin_update_referral_settings, requirements CRUD, tiers CRUD, boomin_evaluate_program, boomin_preview_qualification | Operate the program's rules: channels, requirements, tiers, qualification. | | distribution_operator | distribution_create, distribution_launch, distribution_status, deployment_pause, deployment_resume, enrollment_invite, enrollment_approve, performance_summary | Operate Distributions on the Platform API v1 tree. |

0.2.0

Tool names are underscored. Every tool moved from boomin.x to boomin_x — MCP clients with strict tool-name validation reject dots. tools/list only advertises the underscore form; a call that arrives with a cached dotted name is still normalized rather than hard-failed.

Platform API v1. Every tool with a v1 counterpart now speaks the Stripe-shaped REST tree at /v1/platform (DISTRIBUTION_CORE.md §4): Bearer-only auth, POST-update, bare top-level resource objects, cursor lists {object:'list',data,has_more}, an Idempotency-Key on every mutation, and typed errors as {error:{code,message,param,request_id}}.

Still on the legacy RPC surface, which stays live, because v1 has no counterpart yet:

• boomin_update_program — v1 /programs is read-only (no update route).
• boomin_evaluate_program / boomin_preview_qualification — qualification evaluation has no v1 route.
• boomin_doctor's token probe — POST /smoke is the only call that reports a token's scopes. Doctor additionally probes the v1 tree and reports it as platformV1.
• boomin_get_connect_config, boomin_get_partner_standing, boomin_record_test_event — these are the public/HMAC-signed Partner Connect API (/v1/connect), not the platform tree, and are unaffected by v1.
• boomin_detect_project, boomin_scaffold_referral_first, boomin_verify_referral_install — local filesystem tools; no HTTP at all.

dryRun still means "do not mutate". v1 has no dryRun flag, and these tools have always defaulted to dryRun: true. The default now reads the current resource and returns {ok, dryRun, method, path, changes, current} without issuing the mutation; dryRun: false performs the real call.

Typed error surfacing. v1 error.code is preserved verbatim and paired with a plain-language hint plus a retryable flag, so an LLM caller knows what to do rather than just that something failed. Mapped codes include funding_required, operation_conflict, cancellation_in_progress, cancellation_requires_intervention, band_limit_reached, missing_scope (which also reports the exact requiredScope), the platform_token_* family, and operation_wait_timeout.

Launch follows its operation. distribution_launch validates the draft, launches (v1 returns 202 {distribution, status:'launching', operation} with id strings — never a synchronous success), then polls the operation to a terminal status (succeeded | partial | failed | canceled) and answers with the final operation, the resulting distribution, and its deployments rollup. partial is reported as the real, distinct outcome it is.

Gates

cd packages/mcp && npm run build && npm test    # syntax check + node:test suite
cd services/mcp && npm ci && npm run build      # tsc --noEmit over the worker