Rekomi MCP Server - Machine-readable manifest

This file is the canonical, machine-readable description of the Rekomi Model Context
Protocol (MCP) server. It is intended for LLM-driven IDEs, code-generation tools, and
autonomous agents that need to understand how to call the server without scraping the
human-facing HTML docs at https://rekomi.com/docs/developers/mcp.

This manifest is plain text. It contains no markdown formatting, no bullets, and no
links other than fully-qualified URLs. Whitespace is significant for section breaks.


SERVER

Endpoint:          https://mcp.rekomi.com/api/mcp
Transport:         MCP Streamable-HTTP, stateless mode. Each request is a self-contained
                   JSON-RPC POST. No SSE upgrade. No long-lived session id.
Health check:      GET https://mcp.rekomi.com/api/mcp returns JSON
                   {"name":"rekomi","version":"0.1.0","transport":"streamable-http",
                    "docs":"https://rekomi.com/docs/developers/mcp"}.
Backend:           Every request is forwarded to https://api.rekomi.com/api/v1/* by the
                   relay. The MCP server is a thin trusted translator; it does not store
                   data and does not validate tokens itself.


AUTHENTICATION

Header:            Authorization: Bearer rk_mcp_YOUR_TOKEN_HERE
Token shape:       rk_mcp_<base64url(32 random bytes)>. Hashed with SHA-256 server-side;
                   plaintext is shown to the human exactly once at creation or rotation.
Where to get one:  The human user signs in at https://app.rekomi.com, opens Settings,
                   then "AI assistant", and clicks Generate connection token. The agent
                   cannot mint a token for itself; this is an out-of-band step.
Plan eligibility:  rk_mcp_* tokens may be minted on every Rekomi plan (Trial, Starter,
                   Growth, Pro, Enterprise). The Starter-tier public-API gate that applies
                   to rk_live_* keys does NOT apply to MCP-relayed traffic. Per-feature
                   tier gates (see PLAN GATES below) still apply.
Per-org cap:       Maximum 10 active MCP tokens per organization.
Owner-only:        Only an organization owner can create, rotate, or revoke MCP tokens.
Scope:             Every MCP token carries the read_write scope. The per-tool consent
                   loop in the AI client is the user-facing approval gate, not the scope.

Relay-identity header:
                   The Rekomi backend additionally requires an X-Rekomi-MCP-Identity HMAC
                   header on every request. The MCP server at mcp.rekomi.com computes
                   and attaches this header automatically. Callers MUST NOT compute it
                   themselves and MUST NOT bypass mcp.rekomi.com to call api.rekomi.com
                   directly with an rk_mcp_* token; the backend will return
                   mcp_relay_required (HTTP 401). The HMAC payload is
                   {unix_seconds}.{HTTP_METHOD}.{request_path}.{body_sha256_hex} and
                   the shared secret never leaves the MCP server host. The header is
                   valid for ±300 seconds.


PLAN GATES

There are two distinct plan gates in the Rekomi backend:

Public-API gate ([RequiresPlanForApiKey])
  Blocks Free accounts (below Starter) from calling /api/v1/* with a direct rk_live_* key;
  the gate checks tier rank, so a trial at Starter or higher passes. MCP-relayed traffic
  bypasses this gate. This is why MCP works on every plan.

Feature-tier gate ([RequiresPlan])
  Blocks specific features from lower-tier plans regardless of how the call arrives.
  MCP does NOT bypass this gate. A Starter user calling mint_embed_token via MCP will
  receive {"error":"plan_tier_required"} with HTTP 402. The correct response is to ask
  the human to upgrade the plan, not to retry or switch tokens.

The only tool in this manifest currently affected by the feature-tier gate is
mint_embed_token (requires Growth+).


TOOL CATALOG

There are 38 tools (23 reads and 15 safe writes). Each tool maps 1:1 to one backend
endpoint, or, for the install-recipe pair, to an MCP-local content registry. Compose
multiple tool calls in the agent reasoning loop; do not bundle multiple actions into
one tool call.

This manifest documents the original 14 tools below in detail (tools 1-14). Tools
15-38, added in later phases (coupons, currency, sub-affiliates, install assistant,
attribution-params for drop-in migration), are described in summary at the bottom of
this catalog and in full at https://rekomi.com/docs/developers/mcp.

All inputs are JSON. UUID parameters are RFC 4122 UUIDs as strings. ISO8601 parameters
are full ISO timestamps (e.g. 2026-04-01T00:00:00Z). Cursor pagination yields responses
of shape {"items":[...],"nextCursor":"...","hasMore":true}; pass nextCursor back as the
next call's cursor to page forward. The audit log uses offset pagination instead and
returns {"page":int,"pageSize":int,"total":int,"items":[...]}.

Status enum for conversions: Pending | Approved | Refunded | Rejected.
Status enum for payouts:     Pending | Paid | Failed | Cancelled.
actor_type enum:             user | api_key | mcp | system | admin.

1. list_affiliates
   Description:   List affiliates in the brand's account. Cursor-paginated.
   Input schema:
     cursor       string, optional. Opaque pagination cursor from prior response.
     take         integer 1..200, optional, default 50.
     campaignId   UUID, optional. Filter to one campaign (the backend calls these
                  "programs" internally; the MCP layer translates).
   Response:      {items, nextCursor, hasMore}. Each item has id, name, email, status
                  (Pending/Approved/Paused/Rejected), program/campaign id, applied and
                  approved timestamps, and tracking links.
   Backend:       GET /api/v1/affiliates

2. get_affiliate
   Description:   Fetch a single affiliate's full detail including totals, recent
                  conversions, and notes.
   Input schema:
     id           UUID, required.
   Response:      Single affiliate object.
   Backend:       GET /api/v1/affiliates/{id}

3. list_conversions
   Description:   List conversions (sales). Cursor-paginated.
   Input schema:
     cursor       string, optional.
     take         integer 1..200, optional.
     affiliateId  UUID, optional.
     campaignId   UUID, optional.
     status       enum, optional. One of Pending, Approved, Refunded, Rejected.
     since        ISO8601 string, optional. Lower bound on createdAt.
   Response:      {items, nextCursor, hasMore}.
   Backend:       GET /api/v1/conversions

4. list_campaigns
   Description:   List campaigns (referral programs). Cursor-paginated.
   Input schema:
     cursor       string, optional.
     take         integer 1..200, optional.
   Response:      {items, nextCursor, hasMore}. Each campaign has commission rules,
                  payout rules, status, and affiliate count.
   Backend:       GET /api/v1/programs

5. get_campaign
   Description:   Fetch one campaign by id with commission/payout rules and recent
                  stats.
   Input schema:
     id           UUID, required.
   Response:      Single campaign object.
   Backend:       GET /api/v1/programs/{id}

6. list_payouts
   Description:   List payout batches. Cursor-paginated.
   Input schema:
     cursor       string, optional.
     take         integer 1..200, optional.
     status       enum, optional. One of Pending, Paid, Failed, Cancelled.
     affiliateId  UUID, optional.
     since        ISO8601 string, optional. Lower bound on createdAt.
   Response:      {items, nextCursor, hasMore}. Each item has id, status, total amount,
                  recipient count, created/paid timestamps.
   Backend:       GET /api/v1/payouts

7. get_payout
   Description:   Fetch one payout batch's per-affiliate line items.
   Input schema:
     id           UUID, required.
   Response:      Single payout object with line items.
   Backend:       GET /api/v1/payouts/{id}

8. dashboard_summary
   Description:   At-a-glance KPIs: revenue attributed, conversions count, active
                  affiliates, pending approvals. The friendly range argument is
                  translated to an ISO since date before the backend call.
   Input schema:
     range        enum, optional, default 30d. One of 7d, 30d, 90d, ytd, all.
   Response:      Object with revenue, conversions, activeAffiliates, pendingApprovals.
   Backend:       GET /api/v1/dashboard/summary

9. dashboard_timeseries
   Description:   Daily timeseries data points for charting. At most ~365 points.
   Input schema:
     metric       enum, required. One of revenue, conversions, clicks.
     range        enum, optional, default 30d. One of 7d, 30d, 90d, ytd.
   Response:      Array of {date, value} points.
   Backend:       GET /api/v1/dashboard/timeseries

10. list_audit_log
    Description:  Recent audit-log entries for this brand. Offset-paginated (NOT cursor).
    Input schema:
      page        integer >= 1, optional, default 1.
      pageSize    integer 1..100, optional, default 50.
      action      string, optional. Filter by action name, e.g. affiliate.approved.
      entityType  string, optional. Filter by entity, e.g. affiliate or mcp_token.
      since       ISO8601 string, optional.
      until       ISO8601 string, optional.
    Response:     {page, pageSize, total, items}. Each item exposes actorType, action,
                  entityType, entityId, before, after, createdAt.
    Backend:      GET /api/v1/audit-log

11. approve_affiliate
    Description:  Approve a pending affiliate application. Sends the magic-link welcome
                  email. Confirm with the human before calling.
    Input schema:
      id          UUID, required.
    Response:     The updated affiliate row.
    Backend:      POST /api/v1/affiliates/{id}/approve

12. reject_affiliate
    Description:  Reject a pending affiliate application. Optionally notifies the
                  applicant. Confirm with the human before calling.
    Input schema:
      id          UUID, required.
      reason      string up to 1000 chars, optional. Shared with the applicant if notify
                  is true.
      notify      boolean, optional, default true.
    Response:     The updated affiliate row.
    Backend:      POST /api/v1/affiliates/{id}/reject

13. preview_payout
    Description:  Compute what a payout batch would pay out without actually running
                  it. Returns the per-affiliate breakdown. Safe to call repeatedly.
    Input schema:
      campaignId  UUID, optional. Limit preview to one campaign.
      since       ISO8601 string, optional. Lower bound on conversion createdAt.
    Response:     Per-affiliate breakdown of would-be payout amounts.
    Backend:      POST /api/v1/payouts/preview

14. mint_embed_token
    Description:  Issue a short-lived embed token for showing an affiliate dashboard
                  inside another product. Returns the raw token once; store it
                  server-side. Growth+ only. Starter/Trial callers receive
                  plan_tier_required (HTTP 402) even via MCP.
    Input schema:
      affiliateId      UUID, required.
      expiresInHours   integer 1..720, optional, default 24, max 30 days.
      allowedOrigins   string OR array of URL strings, optional. Comma-separated list of
                       allowed iframe parent origins. Arrays are joined into one string.
      rotate           boolean, optional. If an existing token exists for this affiliate,
                       force rotation and return the new one.
    Response:     Object containing the plaintext token (shown once) plus metadata.
    Backend:      POST /api/v1/embed/tokens


TOOLS 15-32 (SUMMARY)

The following 18 tools were added in subsequent phases. Full schemas at
https://rekomi.com/docs/developers/mcp.

Coupons (6 tools)
  15. list_campaign_coupons        Read campaign-level coupons.
  16. create_campaign_coupon       Mint a parent Stripe coupon. Confirm before calling.
  17. list_affiliate_coupons       Read per-affiliate promotion codes.
  18. list_my_coupons              Affiliate-side view of self-mintable coupons.
  19. generate_affiliate_coupon    Mint a per-affiliate promotion code. Confirm.
  20. revoke_affiliate_coupon      Deactivate one promotion code. Confirm.

Currency (2 tools)
  21. get_home_currency            Read the org's HomeCurrency and supported allowlist.
  22. set_home_currency            Change the org's HomeCurrency. Pro+ only.

Sub-affiliate (3 tools)
  23. get_program_sub_affiliate_config
                                   Read a campaign's sub-affiliate settings.
  24. set_program_sub_affiliate_config
                                   Enable/disable sub-affiliate recruiting. Pro+ only.
  25. list_affiliate_sub_affiliates
                                   Drilldown into one affiliate's recruits.

Install assistant (7 tools)
  26. get_org_profile              Read calling org's plan, tier, brand info.
                                   Backend: GET /api/organizations/me
  27. get_billing_state            Read plan + Stripe Connect status. The
                                   stripeConnectLinked boolean decides install path.
                                   Backend: GET /api/billing/state
  28. list_install_platforms       Catalog of 28 platforms with recipes.
                                   Backend: MCP-local registry.
  29. get_install_recipe           Full structured recipe for one platform.
                                   Input: platformKey. Backend: MCP-local registry.
  30. create_campaign              Create a new affiliate campaign. Confirm before
                                   calling. Backend: POST /api/v1/programs
  31. create_affiliate_invite      Send one branded invite email. Available on
                                   every plan including Trial.
                                   Backend: POST /api/affiliate-invites
  32. bulk_invite_affiliates       Bulk-send up to 50 invites for migration from
                                   Rewardful / Tapfiliate / FirstPromoter /
                                   PartnerStack / Dub Partners. Requires Starter+
                                   with an active paid subscription; Trial users
                                   receive paid_plan_required (HTTP 402).
                                   Backend: POST /api/affiliate-invites/bulk

Attribution params for drop-in migration (3 tools)
  33. get_attribution_params       Read brand's custom attribution params + the 16
                                   canonical defaults + the effective priority order
                                   the loader uses. Use during migration walkthroughs
                                   to confirm whether the source platform's param is
                                   already recognized.
                                   Backend: GET /api/v1/settings/attribution-params
  34. update_attribution_params    Set the brand's custom attribution params. Input
                                   is a comma-separated string, each entry
                                   [a-z0-9_-]{2,32}, max 10 entries, max 256 chars.
                                   Empty/omit clears the override. Owner-level write,
                                   audit-logged.
                                   Backend: PATCH /api/v1/settings/attribution-params
  35. get_install_snippet          Return the ready-to-paste <script> install snippet
                                   for the brand with program id + custom attribution
                                   params + optional pixel public key already embedded
                                   server-side. Inputs: campaignId (defaults to newest
                                   active campaign), withPixel (default false). Hand
                                   the snippet verbatim to the user; the agent should
                                   not construct HTML attributes itself.
                                   Backend: GET /api/v1/r/install-snippet

Generic import (migrate affiliates + history from any platform, 3 tools)
  36. import_affiliates            Bulk-import an affiliate roster from canonical
                                   JSON rows (platform-agnostic; you map any export
                                   into Rekomi fields). Inputs: campaignId,
                                   affiliates[] (1-1000; per row email, fullName?,
                                   status?, paypalEmail?, slug?), includeStatuses?,
                                   notifyAffiliates?, notificationMessageHtml?.
                                   Dedupes by email within the campaign and the batch
                                   (idempotent); status defaults to approved. Starter+
                                   paid for API-key callers; notifyAffiliates needs
                                   Growth+. A write tool: confirm before running.
                                   Returns a revertible jobId + {imported, skipped,
                                   errored, reasons}.
                                   Backend: POST /api/v1/affiliates/import
  37. preview_conversion_import    Dry-run a historical conversion/commission import.
                                   Writes nothing. Inputs: campaignId, conversions[]
                                   (1-1000 canonical rows). Returns {rowsTotal,
                                   wouldImport, wouldSkip, wouldError, skipReasons,
                                   paidBalance, unpaidBalance}. Always run before
                                   import_conversions and show the user unpaidBalance.
                                   Backend: POST /api/v1/conversions/import/preview
  38. import_conversions           Import historical conversions/commissions so
                                   migrated affiliates keep earnings + stats. Inputs:
                                   campaignId, conversions[] (per row affiliateEmail?
                                   /affiliateSlug? [one required], customerEmail?,
                                   customerName?, amountCents, commissionCents,
                                   currency, occurredAt, paid, type?, stripeCustomerId?,
                                   stripeSubscriptionId?, externalId?),
                                   confirmUnpaidPayout? (default false), excludePaid?.
                                   Idempotent (never double-pays). Money safety: paid
                                   rows lock as settled history; unpaid rows become
                                   payable ONLY with confirmUnpaidPayout=true. Starter+
                                   paid. A write tool that can create payable balances:
                                   always preview first, then confirm with the user
                                   before setting confirmUnpaidPayout=true. Returns a
                                   revertible jobId + unpaidConfirmedCents.
                                   Backend: POST /api/v1/conversions/import

SECURITY NOTE: there is intentionally no create_api_key or create_mcp_token tool.
Credential minting stays in the JWT-authenticated dashboard so an MCP token can
never escalate into a long-lived rk_live_* key that outlives the MCP token.


ERROR ENVELOPE

All 4xx and 5xx responses from /api/v1/* are normalized to:

  {"error":"<code>","message":"<human readable>","field":"<optional>"}

The "field" property is present only on validation errors that can attribute the
problem to a specific input field.

Common error codes:

  unauthorized          HTTP 401. Token missing, invalid, revoked, or rotated.
  mcp_relay_required    HTTP 401. An rk_mcp_* token was used without going through
                        mcp.rekomi.com, or the X-Rekomi-MCP-Identity header is missing,
                        stale (>300 s drift), or has a bad HMAC. Never returned to
                        properly-relayed callers - if you see this, the agent is calling
                        api.rekomi.com directly.
  forbidden             HTTP 403. Authenticated but lacks the role/scope needed.
  plan_tier_required    HTTP 402. Feature requires a higher plan tier. Today this
                        applies to mint_embed_token and a handful of other surfaces.
                        Switching tokens will not help; the human must upgrade.
  not_found             HTTP 404. Resource does not exist or is not visible to this org.
  validation_failed     HTTP 400/415/422. Bad input.
  idempotency_conflict  HTTP 409. Idempotency key collided with a different payload.
  rate_limited          HTTP 429. Too many requests in the window.
  server_error          HTTP 500+. Internal failure; safe to retry with backoff.


SECURITY MODEL

The token alone is not enough. The Rekomi backend will only accept an rk_mcp_* token
when it arrives with a valid X-Rekomi-MCP-Identity HMAC header, which is computed and
attached by the MCP server at mcp.rekomi.com using a shared secret unknown to callers.

The HMAC payload is {unix_seconds}.{HTTP_METHOD}.{request_path}.{body_sha256_hex} and
is signed with HMAC-SHA256 then hex-encoded.

The timestamp window is ±300 seconds, matching Stripe's webhook tolerance. Replays
outside this window are rejected.

Body tampering is detected because the SHA-256 of the body is part of the signed
payload. Method swaps and path swaps are detected for the same reason.

HMAC comparison is constant-time on the server.

Revoked tokens stop authenticating within ~10 seconds across all backend instances
(bounded by the auth-cache TTL).

A suspended organization stops every MCP call within seconds via the suspension
middleware, independent of token state.

Tokens and the X-Rekomi-MCP-Identity header are scrubbed from the MCP server's error
reporting before any data leaves the host.


TOKEN ROTATION PROCEDURE

The human user opens Settings then "AI assistant" at https://app.rekomi.com, finds the
relevant token in the list, and clicks Rotate. The new plaintext is shown once. The
old plaintext stops authenticating within ~10 seconds.

Note: Claude Code stores the bearer header statically in ~/.claude.json. Rotating in
the Rekomi dashboard does NOT propagate to Claude Code. The human must run
"claude mcp remove rekomi" then "claude mcp add --transport http rekomi
https://mcp.rekomi.com/api/mcp --header Authorization: Bearer rk_mcp_NEW_TOKEN" to
update the stored credential. The same pattern applies to any other client that stores
the bearer header statically.

If a token is suspected compromised, click Revoke instead of Rotate. Revoked tokens
cannot be restored; mint a new one.


CONTACT

Status:  https://status.rekomi.com
Docs:    https://rekomi.com/docs/developers/mcp
Support: support@rekomi.com