@referalli/mcp
OfficialYou can read and (with confirmation) act on a Referalli referral/affiliate program from any MCP client.
Read-only
List programs, see a 30-day funnel/revenue overview, and get per-partner clicks, referrals, revenue and commissions.
Review recent referrals (attribution channel and status) and open fraud cases.
Analyze credit ROI (
roi_summary), trace an ROI figure for one customer or partner (roi_trace), and find subjects matching ROI patterns likecredit_onlyorbonus_collector.Answer partner self-service questions: their own referral link, balance, and next payout (by
partnerExternalRef).
Write (preview + confirmation token first; only confirm: true with the same args within 5 minutes executes)
Create partners, tracked links and coupons.
Approve, void, pause or resume referrals.
Approve due commissions, and settle a commission as paid (store credit).
Draft a payout run (no money moves).
Click on "Deploy Server".
Wait a few minutes for the server to deploy. Once ready, it will show a "Started" state.
In the chat, type
@followed by the MCP server name and your instructions, e.g., "@@referalli/mcp Show me our affiliate program's funnel and revenue for the last 30 days"
That's it! The server will respond to your query, and you can continue using it as needed.
Here is a step-by-step guide with screenshots.
@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/mcpAdd --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 |
| Required. A Referalli API key. |
| API base URL. Default |
Tools
Read tools answer directly:
Tool | What it returns |
| The affiliate programs in the organization |
| Funnel and revenue for the last 30 days |
| Per-partner clicks, referrals, revenue and commissions |
| Recent referrals with attribution channel and status |
| Open fraud cases awaiting review |
| Credit ROI: what granted credit cost and the cash it earned back |
| The timeline behind an ROI figure for one customer or one partner |
| Customers or partners matching a credit-ROI pattern (for example |
| A partner's own referral link, by the partner's |
| A partner's own pending, approved and paid commission |
| 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.
Links
Changelog: CHANGELOG.md
MIT licensed.
Available Tools
21 toolsapprove_due_commissionsADestructive
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_referralADestructive
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_couponADestructive
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_linkADestructive
Create a tracked link for a partner in a program. Write: the first call returns a preview and a confirmToken; call again with confirm: true and that token to do it.
Inputs: partnerId (required), programId (required), destinationUrl (required), code, +2 more.
create_partnerADestructive
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_runADestructive
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_casesBRead-only
Open fraud cases awaiting review
Inputs: no named parameters.
list_programsBRead-only
List the affiliate programs in this organization
Inputs: no named parameters.
list_referralsBRead-only
Recent referrals with attribution channel and status
Inputs: no named parameters.
my_balanceARead-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_payoutARead-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).
my_referral_linkARead-only
A partner's own referral link, for answering a partner in chat or an AI agent. Pass the partner's verified id in your system (partnerExternalRef); never guess it from an email.
Inputs: partnerExternalRef (required).
partner_performanceCRead-only
Per-partner clicks, referrals, revenue, and commissions
Inputs: no named parameters.
pause_referralADestructive
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_overviewBRead-only
Funnel and revenue overview for the last 30 days
Inputs: no named parameters.
resume_referralADestructive
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_patternsARead-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_summaryARead-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_traceARead-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_commissionADestructive
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_referralADestructive
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
Scored across 21 tools
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.
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.
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.
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
Related MCP Connectors
Talk to your public-facing AI from any MCP client — Claude, ChatGPT, Cursor, Cline, Windsurf.
Marketo MCP server for AI. 130 tools to operate Marketo from Claude, Cursor, or ChatGPT.
API-first CRM for LLMs - contacts, companies, deals and activities over a native MCP server.
Remote MCP server for supportsheep: run AI interviews and manage support content for your blog.
Related MCP Servers
- AlicenseAqualityDmaintenanceLocal-first MCP server for Quo/OpenPhone automation across messaging, calls, contacts, users, phone numbers, and webhooks via a clean stdio tool surface.212AGPL 3.0
- AlicenseAqualityCmaintenanceMCP server for managing affiliate and referral programs. Track referrals, manage affiliates, process conversions, and handle payouts through AI assistants like Claude, Cursor, and ChatGPT.1881 npm2MIT
- AlicenseBqualityBmaintenanceProvides 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.4872 npm2MIT
- AlicenseNot gradedqualityBmaintenanceEnables 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 npmApache 2.0