RefCampaign hosts a Model Context Protocol (MCP) endpoint so you can manage your program directly from Claude Desktop and other MCP-compatible LLM clients. No download, no Node install — just paste a URL.

## What you can do

Fourteen tools exposed:

| Tool                                                      | Use case                                      |
| --------------------------------------------------------- | --------------------------------------------- |
| `get_dashboard_summary`                                   | "How's my program this month?"                |
| `list_campaigns`, `get_campaign`                          | Quick overview of a specific campaign         |
| `list_conversions`, `get_conversions_summary`             | Drill-down on conversions, period-over-period |
| `list_commissions`                                        | Triage what needs review                      |
| `approve_commissions` (bulk), `reject_commissions` (bulk) | "Approve all PENDING under €50 from May"      |
| `list_affiliates`, `get_affiliate`                        | Inspect a specific affiliate's stats          |
| `list_pending_applications`                               | Find applicants awaiting review               |
| `accept_application`, `reject_application`                | Onboard or refuse a single applicant          |
| `accept_applications` (bulk)                              | Mass-onboard applicants                       |

Bulk write tools default to a **dry-run preview** showing how many rows would be affected. Pass `confirm: true` to execute. Combined with Claude Desktop's per-tool permission prompt, this gives you a double safety net before anything is mutated.

## Discovery

For agent clients that auto-discover MCP endpoints, RefCampaign publishes a machine-readable manifest at [`/.well-known/mcp.json`](https://app.refcampaign.com/.well-known/mcp.json):

```bash
curl https://app.refcampaign.com/.well-known/mcp.json | jq .
```

The manifest declares the endpoint URL, transport (`streamable-http`), auth scheme (`bearer`) and the full list of tool slugs. It's intentionally static so any HTTP client can fetch it without auth.

## Setup

<Steps>
  <Step>
    ### Generate an API key

    Go to [Settings → API keys](https://app.refcampaign.com/dashboard/settings/api) and create a new key. Copy it once — it's hash-stored and won't be shown again.
  </Step>

  <Step>
    ### Edit your Claude Desktop config

    Open the file:

    * **macOS** : `~/Library/Application Support/Claude/claude_desktop_config.json`
    * **Windows** : `%APPDATA%\Claude\claude_desktop_config.json`

    Add the RefCampaign entry under `mcpServers`:

    ```json
    {
      "mcpServers": {
        "refcampaign": {
          "url": "https://app.refcampaign.com/api/mcp",
          "headers": {
            "Authorization": "Bearer rcm_live_xxxxxxxxxxxx"
          }
        }
      }
    }
    ```

    Replace `rcm_live_...` with your API key.
  </Step>

  <Step>
    ### Restart Claude Desktop

    The 14 RefCampaign tools should appear in the tool picker. Type a request in natural language, e.g.

    > "Approve all my pending commissions under €50 from May."

    Claude will pick the right tool, run a dry-run first, then ask your permission before executing.
  </Step>
</Steps>

## Authentication, scopes & rate limits

* Every request requires `Authorization: Bearer <api-key>` — no anonymous access.
* Per-account rate limit : **1000 requests / minute**, sliding window. The MCP client retries once on a 429 if `Retry-After` is short ; otherwise it surfaces the error to the LLM.
* Request body capped at **1 MB** — JSON-RPC payloads are tiny in practice, the cap is a safety margin.
* All actions are scoped to your merchant account — there is no risk of leaking data across merchants.

### API key scopes

If your API key has scopes attached :

* `mcp:read` — required for the read tools (list / get / summary).
* `mcp:write` — required for the bulk approve / reject / accept tools.
* `*` (wildcard) or no scopes set — full access (backward-compatible default).

Scope-restricted keys are useful when you want to give Claude Desktop read-only access for reporting without risking accidental approvals. Generate a `mcp:read`-only key alongside your main key and swap the header when you want strict read-only mode.

## Troubleshooting

**"Invalid API key" on first call** → the key was either revoked, never generated, or copied with a typo. Regenerate at [Settings → API keys](https://app.refcampaign.com/dashboard/settings/api).

**No tools appear after install** → check Claude Desktop's developer logs (Help → Show Logs). Most issues are typos in `claude_desktop_config.json` ; validate the JSON with `cat $config | jq` first.

**429 Too Many Requests** → you've exceeded 1000 requests / minute on the API key. Wait a minute or generate a separate key for a different integration.

## Privacy

The hosted MCP endpoint sees only the requests your Claude Desktop sends. We log requests at the same level as the rest of our API (account ID, tool name, response status — never the prompts you typed in Claude Desktop). The conversation between you and Claude stays between you and Anthropic.