MCP server

Rekomi runs a hosted MCP server at https://mcp.rekomi.com/api/mcp. Pick your AI client below, paste two values, restart. That's it.

Claude Desktop

Paste two lines into claude_desktop_config.json. Restart.

Claude Code

One claude mcp add command. CLI persists the config.

ChatGPT

Settings → Connectors → Add custom connector. UI only.

Cursor

Add to ~/.cursor/mcp.json. Same JSON shape as Claude.

Windsurf

Cascade panel → MCP servers → Add. Streamable-HTTP.

Continue

Add to ~/.continue/config.json. Restart the extension.

Zed

Add to ~/.config/zed/settings.json under context_servers.

Generate a connection token

Every connection needs an rk_mcp_* token. It's the only credential your AI client uses.

1. Sign in to app.rekomi.com.
2. Open Settings → AI assistant.
3. Click Generate connection token, give it a name (e.g. Claude Desktop laptop), and copy the rk_mcp_* value. It is shown exactly once.

Owner-only to create. Up to 10 active per organization. Revoke at any time; the change propagates within ~10 seconds. Free and Trial plans included.

Connect Claude Desktop

Edit your claude_desktop_config.json:

{
  "mcpServers": {
    "rekomi": {
      "url": "https://mcp.rekomi.com/api/mcp",
      "headers": {
        "Authorization": "Bearer rk_mcp_YOUR_TOKEN_HERE"
      }
    }
  }
}

Restart Claude Desktop. Ask it "what's in my Rekomi account?" to confirm.

Connect Claude Code

claude mcp add --transport http rekomi https://mcp.rekomi.com/api/mcp \
  --header "Authorization: Bearer rk_mcp_YOUR_TOKEN_HERE"

The URL must come before --header. The --header flag is variadic, so any positional argument after it gets eaten as another header. If you see error: missing required argument 'commandOrUrl', that's the cause.

The CLI persists the config to ~/.claude.json and subsequent sessions auto-connect.

Connect ChatGPT

ChatGPT supports MCP via the Connectors UI on chatgpt.com (Plus, Pro, Team, Enterprise — 2026 Apps SDK rollout). There's no JSON config to paste; the setup is in the UI.

1. Open chatgpt.com → profile menu (bottom-left) → Settings → Connectors → Add custom connector.
2. Name: Rekomi.
3. MCP server URL: https://mcp.rekomi.com/api/mcp
4. Authentication: Custom header.
   • Header name: Authorization
   • Header value: Bearer rk_mcp_YOUR_TOKEN_HERE
5. Save. Start a new chat, enable the Rekomi connector, ask "list my pending Rekomi affiliates".

Connect Cursor

Add to ~/.cursor/mcp.json (global) or .cursor/mcp.json in your project root:

{
  "mcpServers": {
    "rekomi": {
      "url": "https://mcp.rekomi.com/api/mcp",
      "headers": {
        "Authorization": "Bearer rk_mcp_YOUR_TOKEN_HERE"
      }
    }
  }
}

Connect Windsurf

Open the Cascade panel and click the hammer/plug icon → MCP servers → Add server. Pick Streamable-HTTP transport and paste:

{
  "mcpServers": {
    "rekomi": {
      "serverUrl": "https://mcp.rekomi.com/api/mcp",
      "headers": {
        "Authorization": "Bearer rk_mcp_YOUR_TOKEN_HERE"
      }
    }
  }
}

Restart Windsurf. The Rekomi tools appear under Available tools in the Cascade panel.

Connect Continue

Add to ~/.continue/config.json under experimental.modelContextProtocolServers, then restart the Continue extension:

{
  "experimental": {
    "modelContextProtocolServers": [
      {
        "transport": {
          "type": "streamable-http",
          "url": "https://mcp.rekomi.com/api/mcp"
        },
        "headers": {
          "Authorization": "Bearer rk_mcp_YOUR_TOKEN_HERE"
        }
      }
    ]
  }
}

Connect Zed

Add to ~/.config/zed/settings.json under context_servers:

{
  "context_servers": {
    "rekomi": {
      "source": "custom",
      "command": null,
      "settings": {
        "url": "https://mcp.rekomi.com/api/mcp",
        "headers": {
          "Authorization": "Bearer rk_mcp_YOUR_TOKEN_HERE"
        }
      }
    }
  }
}

How it works

AI assistants speak MCP to read your affiliate program, approve applications, draft outreach, mint embed tokens, and more, all on behalf of the human asking. Every tool call lands in your audit log with actor_type = mcp. MCP works on every plan, including Trial and Free; feature-tier gates (e.g. embed tokens are Growth+) still apply regardless of how the call arrives.

Machine-readable docs for LLM-driven IDEs and agents: https://rekomi.com/llms/mcp.txt.

AI client  ──Bearer rk_mcp_xxx──►  mcp.rekomi.com/api/mcp
                                        │
                                        │ Forwards + co-signs:
                                        │   Authorization: Bearer rk_mcp_xxx
                                        │   X-Rekomi-MCP-Identity: t=<unix>,v1=<hmac>
                                        ▼
                                   api.rekomi.com/api/v1/*
                                        │
                                        │ Validates the HMAC, validates the token,
                                        │ checks role + scope, runs the action,
                                        │ logs to audit log with actor_type=mcp.
                                        ▼
                                   Your data

The token alone is useless. The backend rejects any direct call to api.rekomi.com with an rk_mcp_* token (returns mcp_relay_required). The trusted relay at mcp.rekomi.com is the only path that produces the HMAC the backend requires.

Transport is MCP Streamable-HTTP in stateless mode: each tool call is a self-contained JSON-RPC request/response over HTTPS. No long-lived sessions, no SSE upgrade. A GET https://mcp.rekomi.com/api/mcp returns a small JSON identity blob you can use as a health check.

Available tools

There are 39 tools (23 reads and 16 safe writes). Each tool maps 1:1 to one Rekomi V1 API endpoint (or, for the install-recipe tools, to an MCP-local content registry). Composition (e.g. "approve every pending affiliate") happens in your AI client's reasoning loop, not inside a tool, so every individual action is surfaced to you for approval and lands in the audit log on its own row.

Cursor-paginated list responses always look like { "items": [...], "nextCursor": "…", "hasMore": true }. list_audit_log returns { "page", "pageSize", "total", "items" } instead.

The assistant calls each tool individually and surfaces its result back to you in chat. Destructive or money-affecting tools (approve_affiliate, reject_affiliate, import_affiliates, import_conversions) should be confirmed by the user before the assistant runs them. For a conversion import, always run preview_conversion_import first and review the unpaid balance before authorizing payment with confirmUnpaidPayout.

Install Rekomi with the assistant

The most common use of the MCP server is what it sounds like: "help me install Rekomi on my site." A typical session looks like this.

1. You start a chat with Claude (or Cursor, or any MCP-capable client) and say "Help me install Rekomi on my Shopify store."
2. The assistant calls get_org_profile to confirm who you are and what plan you're on.
3. It calls get_billing_state to see whether you've connected Stripe yet. If stripeConnectLinked is true, it recommends the stripe-webhook path; if false, it nudges you to coupon codes or browser-pixel.
4. It calls list_install_platforms and matches "Shopify" to shopify.
5. It calls get_install_recipe with platformKey: shopify and walks you through the steps in chat. It surfaces the gotchas inline (Shopify Payments hides your Stripe; Custom Pixel sandbox cannot load external scripts; Shopify Collabs is a separate product).
6. If you haven't created a campaign yet, the assistant offers to call create_campaign and asks you to confirm the name, slug, commission type, and value before doing so.
7. If you're migrating from Rewardful / Tapfiliate / FirstPromoter / PartnerStack / Dub Partners, paste your existing affiliate emails into the chat. The assistant uses bulk_invite_affiliates to send branded onboarding emails to all of them at once. (Requires Starter tier or higher with an active paid subscription.)

What the assistant cannot do (security)

For the install flow to be safe, the MCP server intentionally does not expose certain operations as tools:

• The assistant cannot mint API keys. If your install needs a rk_live_* bearer + rks_* signing secret (Gumroad / Rails / Django / any S2S path), the assistant will deep-link you to Settings → API keys to mint one yourself, then ask you to paste the key back. The MCP token cannot escalate into a long-lived API key that outlives the MCP token itself.
• The assistant cannot create new MCP tokens. Token minting is owner-only and JWT-only.
• The assistant cannot change billing or open Stripe Checkout sessions. Billing decisions stay with the human owner; the assistant can only read billing state via get_billing_state.

If a tool seems missing, that's the reason. The capability is intentionally not exposed.

Plan-gate semantics

There are two different plan gates in the Rekomi backend:

• Public-API gate ([RequiresPlanForApiKey]): blocks Starter/Trial from calling /api/v1/* with a direct rk_live_* key. MCP-relayed traffic bypasses this — that's why MCP works on every plan.
• Feature-tier gate ([RequiresPlan]): blocks Starter/Trial from a specific feature regardless of how it's called. MCP does not bypass this. Today this applies to mint_embed_token (Growth+) and a handful of other surfaces; a Starter user calling mint_embed_token over MCP gets plan_tier_required (HTTP 402).

If a tool returns plan_tier_required, the answer is to upgrade the plan, not to change tokens.

Security model

• Token shape: rk_mcp_*, 256-bit random body, base64url-encoded. Stored as SHA-256 hash; plaintext never persisted.
• One-time reveal: the full token is shown only at creation or rotation. Rotate to invalidate the old value.
• Owner-only minting: only an organization owner can create, rotate, or revoke MCP tokens.
• Per-org cap: 10 active tokens per organization.
• Read+write scope: every MCP token is granted the read_write scope; the per-tool user-consent loop in your AI client is the user-facing approval gate.
• Direct use blocked: a stolen rk_mcp_* is useless without the trusted relay. Direct hits to api.rekomi.com return mcp_relay_required.
• Relay binding: the relay HMAC is computed over {t}.{METHOD}.{path}.{body_sha256_hex} with a shared secret. ±300 s timestamp window, constant-time compare. Replays, body tampering, and method/path swaps all fail validation.
• Revoke propagation: revoked tokens stop authenticating within ~10 s across all instances (bounded by the auth cache TTL).
• Audit trail: every tool call lands in your audit log with actor_type = mcp, the calling token id, action, entity, and timestamps. Filter by actor_type = mcp under Settings → Audit Log.
• Suspension gate: a suspended account stops every MCP call within seconds.
• PII scrubbing: tokens and the relay-identity header are scrubbed from MCP-server-side error reporting before they leave the host.

Best practices

• Use a separate token per device or per AI client. If a laptop is lost, revoke just that token.
• Set up read-only assistant agents by instructing the assistant not to call write tools (the sixteen writes are approve_affiliate, reject_affiliate, preview_payout, mint_embed_token, set_home_currency, set_program_sub_affiliate_config, create_campaign_coupon, generate_affiliate_coupon, revoke_affiliate_coupon, create_campaign, create_affiliate_invite, bulk_invite_affiliates, update_attribution_params, import_affiliates, import_conversions, record_lead). The audit log still records the actor as the assistant.
• Watch your audit log under Settings → Audit Log during the first few days. Filter by actor_type = mcp to see exactly what the assistant has done.
• Don't paste the same token into multiple clients you can't independently revoke later — one token per surface keeps blast radius bounded.

Troubleshooting

• mcp_relay_required error — your AI client is hitting api.rekomi.com directly with an MCP token. Point it at https://mcp.rekomi.com/api/mcp instead.
• plan_tier_required (HTTP 402) on a specific tool — the tool is feature-gated to a higher plan (e.g. mint_embed_token is Growth+). Upgrade the plan or switch to a tool that's available on your tier. Switching tokens will not help — feature gates apply to MCP traffic too.
• unauthorized (HTTP 401) on every call — the token is wrong, revoked, or rotated. Mint a fresh one under Settings → AI assistant.
• Tools list works but every tool returns 401 — the backend cannot validate the relay header. Most often a stale relay secret on one side; contact support.
• Claude Code still sends the old token after I rotated — Claude Code stores the bearer header statically in ~/.claude.json. Rotating the token in the Rekomi dashboard does not propagate. Run claude mcp remove rekomi and then claude mcp add … again with the new token.
• Claude Code logs SDK auth failed: JSON Parse error — harmless. Some MCP clients probe /.well-known/oauth-protected-resource; the server returns a clean JSON 404 and continues with bearer auth.
• /mcp "Re-authenticate" doesn't do anything — that menu item handles OAuth-flow servers; Rekomi uses a static bearer header. Use claude mcp remove + claude mcp add to swap credentials.

See also

• Public API reference
• Audit log
• Machine-readable manifest: rekomi.com/llms/mcp.txt