Skip to main content
Glama
@referalli/mcp

@referalli/mcp

Official
by Referalli

@referalli/mcp

A Model Context Protocol server for Referalli. It lets Claude, Cursor or any MCP client read your referral and affiliate program (programs, partners, referrals, fraud cases, ROI) and, with your confirmation, act on it (create partners, links and coupons, approve or void referrals, draft payout runs).

It runs locally over stdio with npx and talks to https://referalli.com with your API key. Requires Node.js 20 or later.

1. Get an API key

In Referalli, open Settings → API keys and create a key. Start with a test-mode key (rk_test_…). The key's scopes decide what the server can do: a read-only key gives a read-only assistant.

Related MCP server: Refgrow MCP Server

2. Add the server to your client

Claude Code

claude mcp add --transport stdio --env REFERALLI_API_KEY=rk_test_your_key referalli -- npx -y @referalli/mcp

Add --scope user to make it available in every project. Check it with claude mcp list, or with /mcp inside a session.

Claude Desktop

Open Settings → Developer → Edit Config (claude_desktop_config.json: ~/Library/Application Support/Claude/ on macOS, %APPDATA%\Claude\ on Windows) and add:

{
  "mcpServers": {
    "referalli": {
      "command": "npx",
      "args": ["-y", "@referalli/mcp"],
      "env": {
        "REFERALLI_API_KEY": "rk_test_your_key"
      }
    }
  }
}

Restart Claude Desktop.

Cursor

Add the same block to ~/.cursor/mcp.json (all projects) or .cursor/mcp.json (one project):

{
  "mcpServers": {
    "referalli": {
      "command": "npx",
      "args": ["-y", "@referalli/mcp"],
      "env": {
        "REFERALLI_API_KEY": "rk_test_your_key"
      }
    }
  }
}

Then enable referalli under Cursor Settings → MCP.

Other clients

Any client that launches stdio servers works: the command is npx -y @referalli/mcp, with REFERALLI_API_KEY in its environment.

Configuration

Variable

Meaning

REFERALLI_API_KEY

Required. A Referalli API key.

REFERALLI_API_URL

API base URL. Default https://referalli.com; use http://localhost:4000 for a local API.

Tools

Read tools answer directly:

Tool

What it returns

list_programs

The affiliate programs in the organization

program_overview

Funnel and revenue for the last 30 days

partner_performance

Per-partner clicks, referrals, revenue and commissions

list_referrals

Recent referrals with attribution channel and status

list_fraud_cases

Open fraud cases awaiting review

roi_summary

Credit ROI: what granted credit cost and the cash it earned back

roi_trace

The timeline behind an ROI figure for one customer or one partner

roi_patterns

Customers or partners matching a credit-ROI pattern (for example credit_only)

my_referral_link

A partner's own referral link, by the partner's partnerExternalRef (for a support bot answering that partner)

my_balance

A partner's own pending, approved and paid commission

my_next_payout

A partner's next payout date and the approved amount it would include

Write tools never act on the first call. They return a preview of exactly what would change plus a one-time confirmation token. Only a second call with confirm: true, that token and the same arguments, made within 5 minutes, performs the change:

create_partner, create_link, create_coupon, approve_referral, void_referral, pause_referral, resume_referral, approve_due_commissions, create_payout_run (a draft; no money moves), settle_commission.

MIT licensed.

Available Tools

21 tools
approve_due_commissionsA
Destructive

Approve every commission line whose hold period has passed. Write: the first call returns a preview and a confirmToken; call again with confirm: true and that token to do it.

Inputs: confirm, confirmToken.

approve_referralA
Destructive

Approve a referral held for review. Write: the first call returns a preview and a confirmToken; call again with confirm: true and that token to do it.

Inputs: referralId (required), confirm, confirmToken.

create_couponA
Destructive

Create a coupon code that attributes to a partner. Write: the first call returns a preview and a confirmToken; call again with confirm: true and that token to do it.

Inputs: code (required), partnerId (required), programId (required), confirm, +1 more.

create_partnerA
Destructive

Create a partner. Write: the first call returns a preview and a confirmToken; call again with confirm: true and that token to do it.

Inputs: email (required), displayName (required), confirm, externalRef, +1 more.

create_payout_runA
Destructive

Create a payout run (a draft: it is not executed, no money moves). Write: the first call returns a preview and a confirmToken; call again with confirm: true and that token to do it.

Inputs: confirm, confirmToken.

list_fraud_casesB
Read-only

Open fraud cases awaiting review

Inputs: no named parameters.

list_programsB
Read-only

List the affiliate programs in this organization

Inputs: no named parameters.

list_referralsB
Read-only

Recent referrals with attribution channel and status

Inputs: no named parameters.

my_balanceA
Read-only

A partner's own commission balance: pending (in its hold period), approved (due in the next payout) and paid, in integer minor units of currency.

Inputs: partnerExternalRef (required).

my_next_payoutA
Read-only

When a partner's next payout run is (YYYY-MM-DD, or null when none is scheduled) and how much approved commission it would include.

Inputs: partnerExternalRef (required).

partner_performanceC
Read-only

Per-partner clicks, referrals, revenue, and commissions

Inputs: no named parameters.

pause_referralA
Destructive

Pause a referral: its payments are recorded but earn nothing until resumed. Write: the first call returns a preview and a confirmToken; call again with confirm: true and that token to do it.

Inputs: referralId (required), confirm, confirmToken.

program_overviewB
Read-only

Funnel and revenue overview for the last 30 days

Inputs: no named parameters.

resume_referralA
Destructive

Resume a paused referral. Write: the first call returns a preview and a confirmToken; call again with confirm: true and that token to do it.

Inputs: referralId (required), confirm, confirmToken.

roi_patternsA
Read-only

Customers or partners matching a named credit-ROI pattern: credit_only (used credit, never paid cash), churn_at_exhaustion (stopped paying once credit ran out), bonus_collector (partner collected credit without paying themselves), negative_partner (a partner whose referrals lose money overall). Only subjects whose evidence window has fully elapsed are listed, so a young customer is never flagged. Each entry has a subject and detail amounts in minor units.

Inputs: pattern (required).

roi_summaryA
Read-only

Credit ROI: what the credit you granted (referee rewards, commission credit) cost and what it earned back. Amounts are integer minor units (cents) in the reporting currency unless currency is given. cashAfterMinor is real money customers paid after receiving credit; creditCostMinor is what the credit cost you; credit is not real money, so never count it as revenue. profitAfterMinor, netMinor and roi are null when no product margin is set (or a payment lacks one): null means unknown, not zero, so tell the user to set their margin instead of estimating. roi is profit divided by credit cost (2.1 = each unit of credit returned 2.1). Optional filters: from/to (ISO date or instant), programId, partnerId, currency.

Inputs: to, from, currency, partnerId, +1 more.

roi_traceA
Read-only

The timeline behind a credit ROI figure for ONE customer (customerRef) or ONE partner (partnerId); pass exactly one. It lists grants, credit used, and the cash payments after, so you can explain why a number is what it is. Cash is real money paid; credit is not. Profit fields are null when no margin is set.

Inputs: partnerId, customerRef.

settle_commissionA
Destructive

Mark a commission line paid because you credited the partner yourself (store credit). Write: the first call returns a preview and a confirmToken; call again with confirm: true and that token to do it.

Inputs: reference (required), commissionId (required), memo, confirm, +1 more.

void_referralA
Destructive

Void a referral. Permanent: future payments earn nothing. Write: the first call returns a preview and a confirmToken; call again with confirm: true and that token to do it.

Inputs: referralId (required), confirm, confirmToken.

Tool Schema Changelog

Recent tool additions, removals, and schema changes observed during successful MCP inspections.

Loading tool schema changelog…

    TDQS

    B3.4/5.0

    Scored across 21 tools

    Disambiguation4/5

    Most tools have clearly distinct resource+action targets: referral state changes (approve/void/pause/resume) are mutually exclusive, and the my_* self-service tools are clearly scoped to the calling partner. The only real overlap is in the reporting cluster (program_overview vs partner_performance vs roi_summary vs roi_patterns vs roi_trace), but the descriptions draw useful lines between funnel overview, per-partner metrics, aggregate ROI, cohort patterns, and single-subject trace.

    Naming Consistency4/5

    Everything is consistently snake_case, and the write tools follow a predictable verb_noun pattern (create_coupon, approve_referral, create_payout_run). Minor deviation: several reporting tools are noun-first without a verb (program_overview, partner_performance, roi_summary, roi_patterns, roi_trace), and the my_* namespace is a third convention, but all remain readable and unambiguous.

    Tool Count3/5

    At 21 tools this sits in the heavy band for a single affiliate/referral domain. Each tool does earn its place (the ten write tools each cover a distinct lifecycle transition with a uniform confirm-token flow), but the surface is large enough that an agent must scan a lot of options to pick correctly.

    Completeness3/5

    Core flows are covered: partner/link/coupon creation, referral state machine, commission approval and settlement, payout run creation, and rich ROI reporting. Notable gaps: there is no list_partners or get_partner despite create_partner and partner-scoped reports, no way to list commissions or inspect/cancel a payout run after creation, no list_coupons, and list_fraud_cases has no matching resolve/dismiss tool — a dead end.

    Maintenance

    ActivityMaintained
    ResponsivenessNo recent community issues

    Related MCP Connectors

    Related MCP Servers

    • A
      license
      A
      quality
      C
      maintenance
      MCP server for managing affiliate and referral programs. Track referrals, manage affiliates, process conversions, and handle payouts through AI assistants like Claude, Cursor, and ChatGPT.
      18
      81 npm
      2
      MIT
    • A
      license
      B
      quality
      B
      maintenance
      Provides Claude and other MCP clients with access to the Medusa v2 Admin API, enabling order, customer, product, and inventory management, sales reporting, and carefully scoped write actions. It can run locally over stdio or remotely over Streamable HTTP with OAuth 2.1.
      48
      72 npm
      2
      MIT
    • A
      license
      Not graded
      quality
      B
      maintenance
      Enables developers to expose a single set of tool definitions as MCP server tools over stdio or Streamable HTTP, so Claude Code, Codex, Claude Desktop and Cursor can call them with risk-based annotations, human-approved irreversible writes, typed structured results and long-running job handling built in. It also ships the same tools as a CLI from one source, keeping both surfaces in parity.
      869 npm
      Apache 2.0