Connect Extole to Claude: Analyze Audiences, Reports & Referrals

If you are scaling a referral or loyalty program, you eventually hit a bottleneck: querying audience metrics, investigating failed reward fulfillments, and running custom reports takes too much manual clicking in the Extole console. By connecting Extole to Claude via the Model Context Protocol (MCP), you can automate these workflows. If your team uses ChatGPT, check out our guide on connecting Extole to ChatGPT or explore our broader architectural overview on connecting Extole to AI Agents.

Giving a Large Language Model (LLM) read and write access to a sprawling referral ecosystem like Extole is a serious engineering task. Extole's API is deeply nested, heavily relies on asynchronous operations, and enforces strict rate limits. Every time an endpoint changes or a new campaign component is introduced, your custom integration layer has to be updated.

This guide breaks down exactly how to use Truto to generate a secure, managed MCP server for Extole, connect it natively to Claude Desktop or your custom agent, and execute complex referral workflows using natural language.

The Engineering Reality of the Extole API

A custom MCP server acts as the translation layer between Claude's JSON-RPC tool calls and Extole's REST APIs. While the open MCP standard provides a predictable way for models to discover tools, the reality of implementing it against Extole's specific architecture is painful.

If you decide to build a custom MCP server for Extole, you own the entire API lifecycle. Here are the specific challenges you will face:

Asynchronous Polling Architectures Extole relies heavily on asynchronous processing for heavy lifting. When you request a report run or trigger a batch job, Extole does not return the data immediately. It returns an operation ID or a report ID with a PENDING status. An LLM does not natively understand how to poll an endpoint, wait, and check state. If you expose the raw endpoints, Claude will hallucinate the report output or get stuck. Your MCP server must accurately map the initial request tools and the subsequent status-checking tools so Claude can autonomously execute the polling loop.

Deeply Nested Campaign Controllers Extole's campaign architecture is incredibly flexible, but that flexibility requires a complex API surface. Campaigns are driven by "Controllers" which contain "Triggers" and "Actions". Creating a simple workflow - like issuing a reward when a condition is met - requires orchestrating multiple interconnected JSON payloads. If you dump Extole's entire OpenAPI spec into an LLM context window, the model will drown in hundreds of esoteric component endpoints. You need a way to filter tools down to specific tags (like reports or audiences).

Strict Rate Limiting and 429s Extole protects its infrastructure with strict rate limits. If your AI agent gets stuck in a loop querying audience members or repeatedly polling a report status too quickly, Extole will return a 429 Too Many Requests error. It is critical to note that Truto does not retry, throttle, or apply backoff on rate limit errors for you. When Extole returns a 429, Truto passes that error directly to the caller, normalizing the upstream rate limit info into standardized headers (ratelimit-limit, ratelimit-remaining, ratelimit-reset) per the IETF spec. Your AI agent (or the framework orchestrating it) is responsible for reading these headers and applying its own retry and exponential backoff strategy.

Instead of building OAuth handling, schema mapping, and endpoint routing from scratch, you can use Truto to dynamically generate a managed MCP server for Extole.

How to Generate an Extole MCP Server with Truto

Truto's dynamic tool generation derives MCP tools directly from Extole's API resources and documentation. You can generate an MCP server via the Truto UI or programmatically via the API.

Method 1: Via the Truto UI

This is the fastest method for internal tooling or quick agent prototyping.

1. Log into your Truto dashboard and navigate to the Integrated Accounts page.
2. Select your connected Extole account.
3. Click the MCP Servers tab.
4. Click Create MCP Server.
5. Select your desired configuration. (For Extole, we highly recommend filtering by tags - such as audiences or reports - so you do not overwhelm Claude's context window with all 300+ Extole tools).
6. Copy the generated MCP server URL (e.g., https://api.truto.one/mcp/a1b2c3d4e5f6...).

Method 2: Via the Truto API

If you are dynamically spinning up AI agents for your own users, you can generate MCP servers programmatically. Make a POST request to the /integrated-account/:id/mcp endpoint.

const response = await fetch('https://api.truto.one/integrated-account/<EXTOLE_ACCOUNT_ID>/mcp', {
  method: 'POST',
  headers: {
    'Authorization': `Bearer ${TRUTO_API_KEY}`,
    'Content-Type': 'application/json'
  },
  body: JSON.stringify({
    name: "Extole Audience & Reports MCP",
    config: {
      methods: ["read", "write"],
      tags: ["audiences", "reports", "rewards"] 
    },
    expires_at: "2026-12-31T23:59:59Z"
  })
});
 
const mcpServer = await response.json();
console.log(mcpServer.url); 
// Pass this URL to your MCP client

The resulting URL contains a cryptographic token that securely maps to the specific Extole tenant. No additional OAuth handshakes are required by the AI agent.

How to Connect the MCP Server to Claude

Once you have your Truto MCP Server URL, you must register it with your Claude client.

Method 1: Via the Claude Desktop UI

If you are using Claude Desktop for local operations:

1. Open Claude Desktop and navigate to Settings -> Integrations -> Add MCP Server.
2. Provide a name for the connection (e.g., "Extole Automation").
3. Paste the Truto MCP URL into the connection field.
4. Click Add. Claude will automatically ping the /tools/list endpoint and register all available Extole operations.

Method 2: Via Manual Configuration File

If you are running a custom MCP client, an agentic framework (like LangChain or LlamaIndex), or prefer configuring Claude Desktop manually, you can edit your claude_desktop_config.json file. Truto provides an SSE (Server-Sent Events) wrapper for seamless connection.

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

Save the configuration file and restart your client. Claude now has direct access to your Extole instance.

Hero Tools for Extole

Extole has hundreds of endpoints covering everything from complex trigger rules to webhooks. Exposing all of them is unnecessary for most agentic workflows. Here are the highest-leverage "hero tools" your Claude agent should have access to.

1. list_all_extole_audiences

This tool allows Claude to retrieve all configured audience definitions in your Extole environment. It returns the audience IDs, names, and creation dates, which is the critical first step before auditing audience membership.

"Fetch a list of all active audiences in our Extole account. Find the ID for the audience named 'High Value Referrers'."

2. extole_audiences_list_members

Once Claude knows an audience ID, it can use this tool to list the specific person_id values of all current members. This is vital for cross-referencing which users belong to specific targeting cohorts.

"Using the audience ID you just found, list all the members currently in the 'High Value Referrers' segment."

3. create_a_extole_report

Extole relies on asynchronous report generation. This tool instructs Extole to begin a new report run based on specific parameters (like report_type). Extole will return a report_id with a status of PENDING or QUEUED.

"Trigger a new report run for 'Referral Performance'. Use the default parameters and tell me the report ID once it starts."

4. get_single_extole_report_by_id

Because reports are asynchronous, Claude must use this tool to poll the report status. Once the status changes to DONE, this tool returns the download_uri where the actual data resides.

"Check the status of report ID 10452. If it is done, give me the download URL and the total row count."

5. list_all_extole_person_rewards

When a customer complains that they did not receive their referral bonus, this is the tool to use. It pulls all rewards associated with a specific person_id, including the reward state (EARNED, FAILED, FULFILLED), the face value, and the associated campaign.

"Look up the reward history for person ID 99381. Did any of their recent rewards fail to fulfill?"

6. create_a_extole_person_shareable

This tool allows Claude to dynamically generate a new referral link (shareable) for a specific person. It returns the unique code, target URL, and share URL.

"Generate a new unique shareable referral link for person ID 44512 and format it as a markdown link so I can send it to them."

This is just a curated selection of high-leverage tools. For the complete inventory of available proxy APIs and their exact schemas, visit the Extole integration page.

Workflows in Action

Exposing individual endpoints to Claude is useful, but the real power of MCP comes from chaining these tools together to solve complex, multi-step problems.

Scenario 1: Auditing Failed Rewards for Support Triage

A customer service agent needs to know why a user is complaining about a missing referral payout. Instead of logging into Extole, searching the user, and digging through reward logs, they simply ask Claude.

"A user with person ID 88472 is asking about their missing referral bonus. Can you check their reward history and tell me the status of their recent rewards?"

How Claude executes this:

1. Claude calls list_all_extole_person_rewards passing the person_id: 88472 in the query parameters.
2. The Truto MCP Server routes this to the Extole API and returns the array of reward objects.
3. Claude analyzes the JSON payload, filtering for rewards with a state of FAILED or CANCELED.
4. Claude formulates a natural language response explaining exactly which reward failed, the timestamp, and the face value, saving the support agent ten minutes of clicking.

Scenario 2: Asynchronous Report Execution and Polling

Your marketing team needs to analyze the latest campaign performance data, but Extole requires generating a report asynchronously.

"Please run a new report for campaign summaries. Check it until it finishes, and then give me the download link."

How Claude executes this:

1. Claude calls create_a_extole_report providing the required report_type.
2. The MCP Server returns a JSON object containing a report_id (e.g., rep_999) and a status of PENDING.
3. Claude understands it needs to wait. It internally pauses, then calls get_single_extole_report_by_id passing rep_999.
4. If the status is still IN_PROGRESS, Claude will wait and call the tool again.
5. Once the MCP server returns a status of DONE, Claude reads the download_uri from the payload and presents the link to the user.

sequenceDiagram
    participant Claude as Claude Agent
    participant MCP as Truto MCP Server
    participant Extole as Extole API
    
    Claude->>MCP: Call create_a_extole_report
    MCP->>Extole: POST /v2/reports
    Extole-->>MCP: Returns report_id (Status: PENDING)
    MCP-->>Claude: report_id
    
    Claude->>MCP: Call get_single_extole_report_by_id
    MCP->>Extole: GET /v2/reports/{report_id}
    Extole-->>MCP: Status: IN_PROGRESS
    MCP-->>Claude: IN_PROGRESS
    
    Note over Claude,MCP: Claude pauses and retries
    
    Claude->>MCP: Call get_single_extole_report_by_id
    MCP->>Extole: GET /v2/reports/{report_id}
    Extole-->>MCP: Status: DONE, download_uri
    MCP-->>Claude: Report ready for download

Scenario 3: Audience Migration and Provisioning

You need to move a specific user into an elite referral tier (a specific audience) and generate a new tracking link for them.

"Find the audience ID for 'VIP Advocates'. Once you have it, list the current members to see if person ID 55102 is in it. If not, generate a new shareable link for person ID 55102 so we can email them."

How Claude executes this:

1. Claude calls list_all_extole_audiences to retrieve the audience mapping and finds the ID for 'VIP Advocates'.
2. Claude calls extole_audiences_list_members passing that audience ID.
3. Claude scans the returned array of person_ids. It notices that 55102 is missing.
4. Claude then calls create_a_extole_person_shareable with person_id: 55102 to generate the new referral asset.
5. Claude replies with the new target URL and share URL for the VIP user.

Security and Access Control

Giving an AI agent raw API access to your referral platform introduces risk. Truto provides several architectural layers to lock down your Extole MCP server:

• Method Filtering: You can strictly limit the MCP server to read operations. If a user asks Claude to delete an audience, the tool call is rejected at the Truto router level before it ever hits Extole.
• Tag Filtering: Extole has over 300 endpoints. By configuring the MCP server to only expose tools tagged with audiences or reports, you prevent Claude from accidentally wandering into core webhook configurations or API key management.
• Additional API Authentication: By default, the MCP URL contains a secure hash. For enterprise deployments, you can enable require_api_token_auth: true. This forces the MCP client to pass a valid Truto API token in the Authorization header, ensuring URL possession alone is not enough.
• Automatic Expiration: If you are spinning up a server for a temporary audit script or an external contractor, you can set an expires_at timestamp. Truto will automatically destroy the token and flush it from edge KV storage at the exact minute it expires.

Automate Extole at Scale

Building a custom Extole integration for an AI agent means wrestling with async polling loops, massive OpenAPI schemas, and strict rate limits. By using Truto to generate a managed MCP server, you instantly give Claude the ability to read reports, investigate rewards, and segment audiences using natural language.

Stop writing boilerplate JSON-RPC handlers and OAuth token refresh scripts. Give your agents the exact tools they need, securely and instantly.