> ## Documentation Index
> Fetch the complete documentation index at: https://docs.firstpromoter.com/llms.txt
> Use this file to discover all available pages before exploring further.

# Affiliate MCP Server

> Connect AI tools like Claude Code, Claude Desktop and Cursor to your own affiliate data.

> [!WARNING]
>
> The FirstPromoter Affiliate MCP server is experimental. Tool names and parameters may change without notice.

The Affiliate MCP server lets you, as an affiliate, ask an AI assistant about your own performance in a FirstPromoter program: referrals, commissions, payouts, links, promo codes and reports. It is available to every affiliate.

> [!NOTE]
>
> This page is for **affiliates**. If you run an affiliate program, use the [MCP server for program admins](https://docs.firstpromoter.com/mcp/overview.md) instead. It connects with OAuth and covers the whole program.

## Example prompts

* "How much have I earned this month, and how much is still pending?"
* "List my referrals from the last 30 days that became customers."
* "When is my next payout and how much will it be?"
* "List my referral links and the campaign each one belongs to."
* "Compare my clicks, referrals and earnings over the last three months, by month."

## What it can do

* **Read-only.** The tools only read data. They cannot create, change or delete anything, and they cannot move money.
* **Your data only.** Every answer is scoped to your own affiliate account in one program, the same data you see in your affiliate dashboard.
* **One program per key.** The server uses the API key from the program you created it in. If you promote several programs, add one server entry per program, each with that program's key.

## Connection details

| | |
| - | - |
| **URL** | `https://mcp.firstpromoter.com/affiliate` |
| **Transport** | Streamable HTTP (stateless) |
| **Authentication** | `Authorization: Bearer {your_api_key}` header |

Get the API key in your affiliate dashboard under **Profile** → **API & AI tools**; see [Authentication](https://docs.firstpromoter.com/api-reference-v2/api-affiliate/authentication.md#get-your-api-key). The key already identifies the program, so the MCP server does not need an Account ID.

> [!NOTE]
>
> The affiliate server authenticates with an API key header, so it works with MCP clients that let you set custom headers. Connectors that only support OAuth (such as custom connectors on Claude web or ChatGPT) cannot connect to it yet.

## Connect

### Claude Code (CLI)

```bash theme={null}
claude mcp add --transport http firstpromoter-affiliate https://mcp.firstpromoter.com/affiliate \
  --header "Authorization: Bearer {your_api_key}"
```

Run `/mcp` inside a session to verify the connection and browse the available tools.

### Cursor

Add the server to `~/.cursor/mcp.json` (or `.cursor/mcp.json` in a project):

```json theme={null}
{
  "mcpServers": {
    "firstpromoter-affiliate": {
      "url": "https://mcp.firstpromoter.com/affiliate",
      "headers": {
        "Authorization": "Bearer {your_api_key}"
      }
    }
  }
}
```

Other MCP clients that support streamable HTTP with custom headers use the same URL and `Authorization` header.

### Claude Desktop

Claude Desktop's configuration file starts local servers, so use the [`mcp-remote`](https://www.npmjs.com/package/mcp-remote) bridge (requires Node.js). Open **Settings** → **Developer** → **Edit Config** and add:

```json theme={null}
{
  "mcpServers": {
    "firstpromoter-affiliate": {
      "command": "npx",
      "args": [
        "-y",
        "mcp-remote",
        "https://mcp.firstpromoter.com/affiliate",
        "--header",
        "Authorization:${AUTH_HEADER}"
      ],
      "env": {
        "AUTH_HEADER": "Bearer {your_api_key}"
      }
    }
  }
}
```

Restart Claude Desktop after saving the file.

### Several programs

Add one entry per program, each with its own key, for example `firstpromoter-acme` and `firstpromoter-globex`. The assistant then sees each program as a separate set of tools.

## Available tools

| Tool | Description |
| - | - |
| `get_me` | Your affiliate profile in the program: name, email, balances and the campaigns you belong to. |
| `list_campaigns` | Campaigns you are part of. Takes only `page` and `per_page`. |
| `list_referrals` | Your referrals. Filter by `type`, `state`, `campaign_id` and a `created_from` / `created_to` date range. |
| `list_commissions` | Your commissions. Filter by `status`, `paid`, `campaign_id` and a `created_from` / `created_to` date range. |
| `list_payouts` | Your payouts. Filter by `status` and `campaign_id`. |
| `get_payout_stats` | Amounts of your next and overdue payouts with their period and payment dates, pending payouts without a set period, and the program's payout terms. Takes no arguments. |
| `list_referral_links` | Your referral links, optionally for one `promoter_campaign_id`. |
| `list_promo_codes` | Promo codes assigned to you, optionally for one `promoter_campaign_id`. |
| `get_performance_report` | Clicks, referrals, customers and earnings between `start_date` and `end_date` (default: the last 30 days), grouped by `group_by` (`day`, `week`, `month` or `year`; default `day`), optionally for one `campaign_id`. |

Every `list_*` tool, including `list_campaigns` and `list_referral_links`, is paginated with `page` (default 1) and `per_page` (default 20, maximum 50) and returns `page`, `per_page`, `total_count` and `total_pages` in its `meta`. The tools return the same fields as the [Affiliate API](https://docs.firstpromoter.com/api-reference-v2/api-affiliate/introduction.md).

## Errors

* **401 Unauthorized**: the `Authorization` header is missing, or the key is wrong, regenerated or disabled.
* **403 Forbidden**: the token is not an affiliate API key (for example a dashboard session or a program admin's token), your affiliate account is archived, or your email is not confirmed yet.
* A tool can also return an error with the same message the dashboard shows, for example when you still need to add a payout method before you can see your data.

## Security

* The MCP server is read-only, but the key behind it is not: anyone who has it can read your data in the program and change it through the [Affiliate API](https://docs.firstpromoter.com/api-reference-v2/api-affiliate/authentication.md#security-best-practices). Do not share it or commit it to a repository.
* If a key is exposed, **regenerate** it in **Profile** → **API & AI tools**. The old key stops working for both the API and the MCP server, so update your MCP configuration with the new key.
* **Disable** API access to cut off every connected AI tool at once.


This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.