MCP server

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, 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.

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:

{
  "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.

VS Code

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

{
  "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.

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; 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:

{
  "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

The server registers 14 tools. Use tools/list for the current catalog. The public manifest 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):

{
  "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.