MCP for AI agents

@referalli/mcp is a Model Context Protocol server for Referalli. With it, Claude, Cursor or any MCP client can read your referral and affiliate program: programs, partners, referrals, fraud cases and credit ROI. With your confirmation, it can also act on the program: create partners, links and coupons, approve or void referrals, and draft payout runs.

It runs on your machine over stdio with npx and calls https://referalli.com with your API key. It needs Node.js 20 or later. The source is at github.com/Referalli/referalli-mcp.

1. Create an API key

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

2. Add the server to your client

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

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

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

• Claude Code: add --scope user to make the server available in every project. Check it with claude mcp list, or with /mcp inside a session.

• Claude Desktop: open Settings → Developer → Edit Config. That opens claude_desktop_config.json, in ~/Library/Application Support/Claude/ on macOS and %APPDATA%\Claude\ on Windows. Add the block, then restart Claude Desktop.

• Cursor: put the block in ~/.cursor/mcp.json (every project) or .cursor/mcp.json (one project), then enable referalli under Cursor Settings → MCP.

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

Keep the key out of files you commit. A project-level .cursor/mcp.json is usually checked in, so prefer the user-level file for a real key.

3. Ask about your program

Try prompts such as:

• "Which partners drove the most revenue this month, and what did we pay them?"

• "Are there open fraud cases? Summarize each one."

• "Did the store credit we granted pay for itself? Explain the ROI for partner ptr_..."

• "Create a link for Dana in the Acme Partners program that points to /pricing."

Tools

Read tools answer directly:

Write tools never act on the first call:

The first call returns a preview: the exact request, and for referrals and commissions the current object, with a confirmToken. Nothing changes until the agent calls the same tool again with the same arguments, confirm: true and that token, within 5 minutes. A token works once and only for those arguments, and it doubles as the request's Idempotency-Key, so a retried confirmation never applies twice. The API key's scopes still apply: give the server a key with only the scopes it needs.

Other ways for agents to use Referalli

• The OpenAPI document describes every operation, so agent frameworks that load OpenAPI tools can call the API directly.

• /llms.txt points language models at these docs, the SDKs and the spec.