RefCampaign hosts a **Streamable HTTP** endpoint at `https://app.refcampaign.com/api/mcp`. It requires a merchant API key in the `Authorization` header and an active subscription entitlement. No local RefCampaign server is needed.

## Permissions

In [Settings → API keys](https://app.refcampaign.com/dashboard/settings/api), deselect **API: read** and select **MCP: read** for reporting. Add **MCP: write** only if the assistant must change commissions or applications. Copy the secret when creating the key. Creating a key does not modify or revoke existing keys.

| Scope                               | Access                                        |
| ----------------------------------- | --------------------------------------------- |
| `mcp:read`                          | Read tools                                    |
| `mcp:write`                         | Write tools, including their dry-run previews |
| Both                                | Read and write                                |
| `*`                                 | Full access for existing wildcard keys        |
| Empty, or only API `read` / `write` | No access to MCP tools                        |

Scopes are checked when a tool runs. A visible tool is not necessarily authorized.

## Client configuration

These examples follow the linked client references. They do not imply that every client version has been tested against RefCampaign.

### Claude Code

Merge this entry into the project's `.mcp.json`:

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

Supply `REFCAMPAIGN_MCP_KEY` through your secret manager in the environment that launches Claude Code. Keep the variable reference in the file; never commit a secret. Check the connection with `/mcp`. See [Claude Code's MCP reference](https://code.claude.com/docs/en/mcp).

### VS Code

For extension-host chat, open **MCP: Open User Configuration** and merge:

```json
{
  "inputs": [
    {
      "type": "promptString",
      "id": "refcampaign-key",
      "description": "RefCampaign MCP API key",
      "password": true
    }
  ],
  "servers": {
    "refcampaign": {
      "type": "http",
      "url": "https://app.refcampaign.com/api/mcp",
      "headers": {
        "Authorization": "Bearer ${input:refcampaign-key}"
      }
    }
  }
}
```

Start it with **MCP: List Servers** and enter the key in the masked prompt. Agent Host does not receive servers requiring interactive inputs; this example targets the extension host. See [VS Code's MCP reference](https://code.visualstudio.com/docs/agents/reference/mcp-configuration).

### Claude Desktop and claude.ai

These are not `claude_desktop_config.json` entries. Desktop local servers and remote connectors use different setup paths. RefCampaign provides static Bearer authentication, not an MCP OAuth flow. Do not assume an OAuth-only connector can use it. See [Anthropic's remote connector guide](https://support.claude.com/en/articles/11175166-get-started-with-custom-connectors-using-remote-mcp); use a header-capable client as above for this guide.

## Verify a read

With only `mcp:read`, ask: “List my campaigns without changing anything.” The corresponding `tools/call` parameters are:

```json
{
  "name": "list_campaigns",
  "arguments": {}
}
```

For staging, use `https://app.test.refcampaign.com/api/mcp` with a staging `rc_test_` key. Never send a production key to staging. A connection or `tools/list` alone is insufficient: verify a successful read.

## Tools and discovery

| Tools                                                             | Scope       |
| ----------------------------------------------------------------- | ----------- |
| `get_dashboard_summary`                                           | `mcp:read`  |
| `list_campaigns`, `get_campaign`                                  | `mcp:read`  |
| `list_conversions`, `get_conversions_summary`                     | `mcp:read`  |
| `list_commissions`                                                | `mcp:read`  |
| `list_affiliates`, `get_affiliate`                                | `mcp:read`  |
| `list_pending_applications`                                       | `mcp:read`  |
| `approve_commissions`, `reject_commissions`                       | `mcp:write` |
| `accept_application`, `reject_application`, `accept_applications` | `mcp:write` |

The server registers 14 tools. Use `tools/list` for the current catalog. The [public manifest](https://app.refcampaign.com/.well-known/mcp.json) describes the endpoint, transport, authentication and tool names. Automatic discovery depends on the client.

## Write confirmation

`approve_commissions`, `reject_commissions` and `accept_applications` default to `confirm: false`. Even their previews require `mcp:write`. Bound operations with explicit IDs from a read response. These `tools/call` parameters preview one commission approval (replace the example ID):

```json
{
  "name": "approve_commissions",
  "arguments": {
    "commission_ids": [
      "cl00000000000000000000001"
    ],
    "confirm": false
  }
}
```

Review the preview, then send the same IDs with `confirm: true` only when you intend to approve them. The server does not require a previous preview or reserve records between calls.

**`accept_application` and `reject_application` execute immediately** with `mcp:write`; they have no `confirm` input. Client approval prompts depend on client settings. Use a read-only key for reporting.

## Troubleshooting

* **401:** key missing, expired, revoked or incorrectly supplied.
* **402:** the merchant needs an active subscription entitlement.
* **Missing scope:** create a key with the required MCP permission; API scopes do not grant MCP access.
* **429:** respect `Retry-After` when provided and wait for the applicable window to reset. The authenticated limit is 1,000 requests/minute **per account**, shared by its keys. A separate pre-authentication IP limit also applies. Retry behavior depends on the client.
* **405 / 413:** use Streamable HTTP POST, not legacy SSE GET. The route rejects declared `Content-Length` above 1 MB; a separate hosting limit also applies. GET and DELETE are not implemented.

## Data sent to the client

Tools return merchant data, including affiliate details, conversions and commissions, to your client and potentially its model provider. RefCampaign receives tool arguments, which may contain information from your conversation. Review the client's data policy and grant only the permissions you need.