Connect Refersion to Claude: Optimize Offers & Promotion Workflows

If your team needs to connect Refersion to Claude to automate affiliate onboarding, optimize commission structures, or orchestrate high-volume promotion workflows, you need a Model Context Protocol (MCP) server. This server acts as the dynamic translation layer between Claude's LLM function calls and Refersion's underlying REST APIs. You can either build, host, and maintain this complex integration layer yourself, or you can use a managed platform like Truto to dynamically generate a secure, authenticated MCP server URL.

If your team uses ChatGPT instead, check out our companion guide on /connect-refersion-to-chatgpt-manage-affiliates-track-performance/. For a broader architectural overview of deploying multi-agent systems against affiliate platforms, read /connect-refersion-to-ai-agents-automate-prospects-manual-credits/.

Giving a Large Language Model (LLM) read and write access to an affiliate management platform like Refersion is a significant engineering challenge. You must handle complex state transitions, manage polymorphic data feeds, map extensive JSON schemas to rigid MCP tool definitions, and deal with strict rate-limiting constraints. Every time Refersion updates a payload or introduces a new promotional asset type, you have to update your server code, redeploy, and rigorously test the integration.

This guide breaks down exactly how to use Truto to generate a secure, managed MCP server for Refersion, connect it natively to Claude, and execute complex affiliate management workflows using natural language.

The Engineering Reality of the Refersion API

A custom MCP server is essentially a self-hosted integration layer. While the open MCP standard provides a predictable way for models to discover and execute tools, the reality of implementing it against specialized B2B APIs is painful. Refersion is built to manage massive affiliate networks, granular commission routing, and high-throughput click tracking.

If you decide to build a custom Refersion MCP server in-house, here are the specific integration challenges you will face:

Polymorphic Activity Feeds and Schema Hallucinations Refersion's activity endpoints, such as the affiliate activity timeline, return merged datasets containing conversions, payments, and clicks in a single array. This data is polymorphic: a conversion object has conversionCount, total, and currency, while a payment object has completely different keys. LLMs struggle immensely with polymorphic arrays when the schema is not perfectly typed. If you blindly pass this array to Claude, the model will often hallucinate schema keys across object types. A managed MCP server forces strict JSON Schema definitions derived from curated documentation, ensuring Claude knows exactly which fields belong to which activity type.

Strict State Machine Transitions Refersion enforces rigid domain logic around affiliate and conversion statuses. For example, deleting an affiliate is actually a soft-delete (setting the status to DELETED), but the API will reject this operation if the affiliate has any pending or unpaid conversions. Similarly, you cannot update an affiliate's status and locked state in the exact same request, and you can only lock an affiliate if they are already APPROVED. An LLM cannot intuit these rules. It will simply fire concurrent updates and fail. A well-designed MCP tool layer abstracts these constraints into discrete operations (like refersion_conversions_bulk_update) with explicit parameter guidelines that guide the model to sequence its requests correctly.

Caching Layers and Rate Limit Realities Refersion aggressively caches certain heavily queried endpoints. For instance, unfiltered requests to affiliate or conversion count endpoints are cached for 60 seconds per client. If an agent rapidly polls these endpoints after a state change, it will receive stale data and assume the operation failed, triggering infinite retry loops.

Furthermore, Refersion enforces standard rate limits. It is critical to note that Truto does not retry, throttle, or apply backoff on rate limit errors. When the upstream Refersion API returns an HTTP 429 (Too Many Requests), Truto passes that error directly back to Claude. Truto normalizes the upstream rate limit information into standardized headers (ratelimit-limit, ratelimit-remaining, ratelimit-reset) per the IETF specification. The caller (the MCP client or the LLM framework) is entirely responsible for reading these headers and executing exponential backoff.

How to Create the Refersion MCP Server

Truto derives MCP tools dynamically from your connected integration's resources and documentation. There is no hard-coded proxy logic to maintain. When you provision an MCP server, Truto generates a cryptographically secure token that encodes the target tenant, environment, and specific tool filters.

You can generate this server via the Truto UI or programmatically via the API.

Method 1: Via the Truto UI

For ad-hoc configurations or internal IT usage, the UI is the fastest path:

1. Log into your Truto dashboard and navigate to the Integrated Accounts page.
2. Select your connected Refersion account.
3. Click the MCP Servers tab.
4. Click Create MCP Server.
5. Provide a human-readable name, and optionally configure allowed methods (e.g., read, write) or specific tool tags.
6. Click Create and copy the generated MCP server URL (e.g., https://api.truto.one/mcp/a1b2c3d4e5f6...).

Method 2: Via the Truto API

For platform engineers embedding AI agents into a broader application, you can provision MCP servers programmatically. This endpoint creates a database record, generates a random hex string, hashes it for secure storage, and returns the endpoint URL.

POST /integrated-account/{id}/mcp

{
  "name": "Refersion Campaign Agent MCP",
  "config": {
    "methods": ["read", "write", "custom"],
    "tags": ["affiliates", "conversions", "offers"]
  },
  "expires_at": "2026-12-31T23:59:59Z"
}

Response:

{
  "id": "mcp_srv_9x8y7z",
  "name": "Refersion Campaign Agent MCP",
  "config": {
    "methods": ["read", "write", "custom"],
    "tags": ["affiliates", "conversions", "offers"]
  },
  "expires_at": "2026-12-31T23:59:59Z",
  "url": "https://api.truto.one/mcp/a1b2c3d4e5f6..."
}

Connecting the MCP Server to Claude

Once you have your Truto MCP URL, you need to register it with your Claude client. You can do this visually in the Claude Desktop app or via the underlying JSON configuration file.

Method A: Via the Claude UI (Desktop)

1. Open the Claude Desktop application.
2. Navigate to Settings -> Integrations (or Developer Settings depending on your build).
3. Click Add MCP Server.
4. Name the server (e.g., "Refersion Tools").
5. Paste the Truto MCP URL you generated earlier.
6. Click Add. Claude will immediately execute an initialize handshake and request the tools/list payload to discover the Refersion operations.

Method B: Via Manual Configuration File

If you are running Claude Desktop in a managed IT environment or want to script the installation, you can modify the claude_desktop_config.json file directly. Because Truto provides a remote SSE (Server-Sent Events) endpoint, you will use the official @modelcontextprotocol/server-sse transport bridge.

Add the following configuration to your file (typically located at ~/Library/Application Support/Claude/claude_desktop_config.json on macOS or %APPDATA%\Claude\claude_desktop_config.json on Windows):

{
  "mcpServers": {
    "refersion-truto": {
      "command": "npx",
      "args": [
        "-y",
        "@modelcontextprotocol/server-sse",
        "https://api.truto.one/mcp/a1b2c3d4e5f6..."
      ]
    }
  }
}

Save the file and restart Claude Desktop. The model now has full tool-calling capabilities against your Refersion instance.

Hero Tools for Refersion

Truto automatically maps Refersion's vast API surface into highly optimized, schema-enforced MCP tools. Because query and body parameters share a flat input namespace in the MCP protocol, Truto automatically splits arguments based on the underlying schema definition.

Here are 7 high-leverage "hero" tools available for Refersion.

list_all_refersion_affiliates

This tool retrieves Refersion affiliates with extensive profile information, offer details, and performance metrics. It supports deep filtering by status, search term, offer IDs, and performance thresholds.

Contextual Usage Notes: Because affiliate networks scale into the thousands, always instruct Claude to use specific filters (like status=APPROVED) or search parameters to narrow the payload size and avoid overwhelming the context window.

"Claude, list all Refersion affiliates who are currently PENDING. Filter the results to only show affiliates assigned to offer ID 4059, and summarize their company names and geographic locations."

update_a_refersion_affiliate_by_id

This tool executes a partial update on a Refersion affiliate's details. You can modify their status, lock state, custom fields, and profile information.

Contextual Usage Notes: Ensure Claude knows the rule: the locked field cannot be combined with status in the same request, and the affiliate must already be in an APPROVED status before locking.

"Update the Refersion affiliate with ID 99302. Change their status to APPROVED. Wait for that to succeed, and then lock their account so their custom fields cannot be modified."

list_all_refersion_conversions

This operation lists Refersion conversions with robust filtering by status, order ID, affiliate, date range, offer, and platform.

Contextual Usage Notes: Conversions are the lifeblood of affiliate tracking. This tool is perfect for reconciliation workflows where an agent needs to verify if an e-commerce order ID was successfully tracked as an affiliate conversion.

"Pull the list of all Refersion conversions generated in the last 7 days. Filter for conversions that are currently marked as PENDING, and sort them descending by commission amount."

refersion_conversions_bulk_update

This tool updates the status of a single Refersion conversion, supporting transitions between PENDING, APPROVED, DENIED, and UNQUALIFIED.

Contextual Usage Notes: Moving a conversion to APPROVED or DENIED creates an immutable audit trail and dispatches webhook notifications to the affiliate. Use this tool for automated commission approvals.

"Look up conversion ID 884739. If the conversion is currently PENDING, use the bulk update tool to change its status to APPROVED so the affiliate gets credited."

list_all_refersion_offers

Retrieves Refersion offers (commission structures) with filtering by offer type, search terms, and performance-range criteria.

Contextual Usage Notes: Offers define how affiliates get paid (e.g., flat rate vs percentage, returning customer bonuses). This tool helps Claude audit active commission tiers.

"List all active Refersion offers. Find the one named 'Holiday Influencer Tier' and tell me what the return customer commission rate is set to."

create_a_refersion_promotion_method

Creates a new promotion method - such as a coupon code, referral email, or specific SKU trigger - for an affiliate.

Contextual Usage Notes: Promotion method values must be strictly unique per client across all affiliates. If a coupon code is already taken, the API will reject it.

"Create a new coupon promotion method for affiliate ID 10293. Set the coupon value to 'SUMMER-SAVINGS-2026' and link it to their default offer."

refersion_prospects_get_pitch

This custom tool interacts with Refersion's AI prospecting engine to retrieve an existing pitch or generate a personalized AI pitch message for contacting a high-value affiliate prospect.

Contextual Usage Notes: Requires a valid prospect_id from the prospects list. This is highly useful for automating outbound affiliate recruitment.

"Get the AI pitch message for prospect ID 5502. If the message looks good, output it so I can copy it into my email client."

To view the complete schema details, query parameters, and the dozens of other available tools, visit the Refersion Truto Integration Page.

Workflows in Action

By layering these tools inside Claude, you can build autonomous workflows that replace hours of manual affiliate management.

Workflow 1: End-of-Month Conversion Reconciliation

At the end of the month, affiliate managers must review pending conversions against actual e-commerce returns or cancellations before approving commissions.

"Claude, I need to reconcile yesterday's conversions. First, list all conversions currently in PENDING status. Check the list. For any conversion with a commission over $100, update its status to APPROVED using the bulk update tool."

Execution Steps:

1. Claude calls list_all_refersion_conversions with the filter status=PENDING and a date range for yesterday.
2. Claude parses the JSON response, filtering in memory for objects where the commission amount exceeds $100.
3. Claude iterates through the high-value conversions, calling refersion_conversions_bulk_update for each one, passing the conversion_id and setting status: "APPROVED".

sequenceDiagram
    participant User
    participant Claude as Claude Desktop
    participant Truto as Truto MCP Server
    participant Refersion as Refersion API

    User->>Claude: "Reconcile pending conversions..."
    Claude->>Truto: call tool: list_all_refersion_conversions (status=PENDING)
    Truto->>Refersion: GET /conversions?status=PENDING
    Refersion-->>Truto: JSON Array of conversions
    Truto-->>Claude: Standardized tool response
    Claude->>Claude: Filter for commission > $100
    loop For each high-value conversion
        Claude->>Truto: call tool: refersion_conversions_bulk_update (id, APPROVED)
        Truto->>Refersion: POST /conversions/bulk_update
        Refersion-->>Truto: 204 No Content
        Truto-->>Claude: Success confirmation
    end
    Claude-->>User: "I have approved 14 high-value conversions."

Workflow 2: Automated Affiliate Onboarding & Asset Assignment

When new affiliates apply, they land in a PENDING state. You can instruct Claude to review new applications and provision their assets.

"Claude, fetch all affiliates in PENDING status. For each one, update their status to APPROVED. Then, generate a unique tracking link for each newly approved affiliate, and assign them a new coupon promotion method matching their first name and the year."

Execution Steps:

1. Claude calls list_all_refersion_affiliates with status=PENDING.
2. For each record, Claude calls update_a_refersion_affiliate_by_id with status: "APPROVED".
3. Claude calls refersion_affiliates_get_link to generate their primary tracking link.
4. Claude calls create_a_refersion_promotion_method using type: "coupon" and formats the value (e.g., JOHN2026).

Workflow 3: Prospecting and Outreach Execution

Outbound affiliate recruitment is notoriously time-consuming. Claude can orchestrate the discovery and outreach generation process natively.

"Claude, list all affiliate prospects from the Refersion discovery tool. Find the top 3 prospects by audience size. Generate a personalized pitch for each using the get pitch tool, and format the output as an HTML email draft."

Execution Steps:

1. Claude calls list_all_refersion_prospects to pull discovery records.
2. Claude analyzes the metadata to select the top 3 prospects.
3. Claude calls refersion_prospects_get_pitch for each specific prospect_id.
4. Claude synthesizes the returned AI pitches and formats them into an HTML block for the user.

Security and Access Control

When granting an LLM access to your financial and affiliate data, security is paramount. Truto's MCP architecture provides several layers of access control that are evaluated at the edge before any request touches the Refersion API:

• Method Filtering: When creating the MCP server, you can restrict the token to specific operations. By passing methods: ["read"], you ensure the agent can only execute get and list operations, physically preventing Claude from accidentally deleting an offer or approving a fraudulent conversion.
• Tag Filtering: You can restrict the MCP server to specific resource tags. For example, passing tags: ["prospects"] creates a purpose-built server that can only interact with outreach tools, isolating it from core financial and commission data.
• Require API Token Auth: By setting require_api_token_auth: true, possession of the MCP URL is no longer sufficient. The MCP client (or the user session) must also pass a valid Truto API Bearer token, adding an essential secondary layer of identity verification.
• Ephemeral Servers (expires_at): You can set an explicit ISO 8601 expiration datetime on the server. Once the timestamp is reached, Truto's cleanup alarms automatically destroy the server record and revoke the KV storage tokens, making it ideal for temporary AI agent sessions or contractor access.

Moving Beyond Point-to-Point Scripts

Building a custom Refersion integration for Claude requires navigating polymorphic payloads, complex state machines, and unforgiving rate limits. Hard-coding these interactions leads to brittle agents that break the moment the vendor updates an endpoint.

By leveraging Truto's auto-generated MCP servers, you abstract away the API mechanics. Your LLM gets perfectly mapped JSON schemas, standardized error handling, and secure tool execution, allowing your engineering team to focus on designing intelligent agent workflows instead of maintaining API boilerplate.

Ready to transform your affiliate operations with AI? Deploy your first Refersion MCP server today.