---
title: "Connect Perkville to Claude: Manage Rewards and Referral Programs"
slug: connect-perkville-to-claude-manage-rewards-and-referral-programs
date: 2026-08-04
author: Yuvraj Muley
categories: ["AI & Agents"]
excerpt: "Learn how to build a secure, managed MCP server for Perkville to connect your rewards, points, and referral programs directly to Claude."
tldr: "Connect Perkville to Claude using Truto's managed MCP server. This guide covers how to expose loyalty transactions, connection balances, and referral workflows to AI agents securely."
canonical: https://truto.one/blog/connect-perkville-to-claude-manage-rewards-and-referral-programs/
---

# Connect Perkville to Claude: Manage Rewards and Referral Programs


If your teams need to orchestrate customer loyalty tiers, manage rewards workflows, or automate referral programs from within their AI workspaces, you need a [Model Context Protocol (MCP) server](https://truto.one/what-is-mcp-and-mcp-servers-and-how-do-they-work/). This server acts as the translation layer between Claude's tool calls and Perkville's REST APIs. You can either [build and maintain this infrastructure yourself](https://truto.one/the-hands-on-guide-to-building-mcp-servers-for-ai-agents-2026/), or use a managed integration platform like Truto to dynamically generate a secure, authenticated MCP server URL. If your team uses ChatGPT, check out our guide on [connecting Perkville to ChatGPT](https://truto.one/connect-perkville-to-chatgpt-sync-loyalty-rules-and-user-points/) or explore our broader architectural overview on [connecting Perkville to AI Agents](https://truto.one/connect-perkville-to-ai-agents-orchestrate-tiers-and-transactions/).

Giving a Large Language Model (LLM) read and write access to a loyalty platform like Perkville is an engineering challenge. You have to handle API authentication lifecycles, map relational data structures to flat MCP tool definitions, and deal with strict state changes in ledger systems. Every time an endpoint changes, you have to update your server code, redeploy, and test the integration.

This guide breaks down exactly how to use Truto to generate a [secure, managed MCP server](https://truto.one/managed-mcp-for-claude-full-saas-api-access-without-security-headaches/) for Perkville, connect it natively to Claude, and execute complex rewards workflows using natural language.

## The Engineering Reality of the Perkville API

A custom MCP server is a self-hosted integration layer. While the open MCP standard provides a predictable way for models to discover tools over JSON-RPC 2.0, the reality of implementing it against vendor APIs is painful. 

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

**Complex Relational Hierarchy and Mandatory Filters**
Perkville's data model is highly relational. A user is not just a flat record; they are represented by a `Connection` which links them to a specific `Business` (the rewards program entity). To interact with anything - from `Challenges` to `Vouchers` to `Transactions` - the underlying API often requires a `business` ID filter. If you blindly expose the entire API to an LLM, the model will constantly fail by forgetting to pass the mandatory business context. Truto's dynamic tool schemas automatically inform the LLM which query parameters are required, preventing hallucinated or malformed requests.

**Immutable Point Ledgers**
Points in Perkville are managed via an immutable ledger. You cannot simply "update" a point balance. You must execute a `Transaction` to award points, or execute a `Void Transaction` to reverse a previous action. Providing an LLM write access to a financial ledger requires strict schema boundaries. A managed MCP server enforces these boundaries by strictly validating the LLM's JSON arguments against the `body_schema` derived directly from API documentation records.

**Rate Limits and Standardized Headers**
Perkville enforces quotas on API usage. When building AI agents, it is remarkably easy for a model to loop through pagination and hit a rate limit. If this happens, Truto does not silently retry, throttle, or apply exponential backoff on your behalf. When the upstream Perkville API returns an `HTTP 429 Too Many Requests`, Truto passes that error directly to the caller. However, Truto normalizes the upstream rate limit information into standard headers (`ratelimit-limit`, `ratelimit-remaining`, `ratelimit-reset`) per the IETF specification. This guarantees that your agent framework has the exact data it needs to manage its own backoff logic reliably.

Instead of building this foundational plumbing from scratch, you can deploy a managed MCP server that derives its capabilities dynamically.

## How to Generate a Perkville MCP Server

Truto's MCP servers are generated dynamically. Rather than executing hand-coded integration logic, Truto [derives tool definitions at runtime](https://truto.one/auto-generated-mcp-tools-for-ai-agents-a-2026-architecture-guide/) from the integration's registered resources and documentation schemas. Each server is scoped to a single authenticated Perkville account.

You can create this server in two ways.

### Method 1: Via the Truto UI

For administrators and internal tooling, the easiest path is the dashboard:

1. Navigate to the **Integrated Accounts** page in your Truto dashboard.
2. Select your connected Perkville instance.
3. Click the **MCP Servers** tab.
4. Click **Create MCP Server**.
5. Select your desired configuration (e.g., Read-Only methods, specific tags like 'transactions', and an optional expiration date).
6. Copy the generated MCP server URL. 

### Method 2: Via the Truto API

For engineers building multi-tenant AI applications, you can provision MCP servers programmatically for your end-users. The API validates that the integration has tools available, generates a secure token backed by distributed edge storage, and returns a ready-to-use URL.

Make a POST request to `/integrated-account/:id/mcp`:

```typescript
const response = await fetch('https://api.truto.one/integrated-account/YOUR_ACCOUNT_ID/mcp', {
  method: 'POST',
  headers: {
    'Authorization': 'Bearer YOUR_TRUTO_API_KEY',
    'Content-Type': 'application/json'
  },
  body: JSON.stringify({
    name: "Claude Perkville Ops Server",
    config: {
      methods: ["read", "write"], 
      tags: ["loyalty", "rewards"], 
      require_api_token_auth: false
    },
    expires_at: "2026-12-31T23:59:59Z"
  })
});

const data = await response.json();
console.log(data.url); // https://api.truto.one/mcp/abc123def456...
```

The returned URL contains a cryptographically hashed token that securely identifies the exact Perkville account and the specific tool filters you applied.

## How to Connect the MCP Server to Claude

Once you have your Truto MCP URL, you can connect it to your AI environment. Because the Truto MCP server communicates natively over HTTP POST with JSON-RPC 2.0 messages, it is completely plug-and-play.

### Method A: Via the Claude or ChatGPT UI

If you are using enterprise chat interfaces, connecting the server takes seconds:

**For Claude:**
1. Open Claude and navigate to **Settings** -> **Integrations**.
2. Click **Add MCP Server** (or Add Custom Connector).
3. Paste your Truto MCP URL and click **Add**.

**For ChatGPT:**
1. Open ChatGPT and navigate to **Settings** -> **Apps** -> **Advanced settings**.
2. Enable **Developer mode**.
3. Under MCP servers / Custom connectors, click to add a new server.
4. Give it a name (e.g., "Perkville Rewards") and paste your Truto MCP URL.

### Method B: Via Manual Configuration File (Claude Desktop)

If you are running Claude Desktop locally or configuring a custom agent framework, you will use the Server-Sent Events (SSE) transport layer. 

Edit your `claude_desktop_config.json` file (located at `~/Library/Application Support/Claude/claude_desktop_config.json` on Mac or `%APPDATA%\Claude\claude_desktop_config.json` on Windows):

```json
{
  "mcpServers": {
    "perkville": {
      "command": "npx",
      "args": [
        "-y",
        "@modelcontextprotocol/server-sse",
        "--url",
        "https://api.truto.one/mcp/YOUR_SECURE_TOKEN_HERE"
      ]
    }
  }
}
```

Restart Claude Desktop. The model will automatically send an `initialize` request to the server, discover the tools, and make them available in your chat context.

## Hero Tools for Perkville

When Claude connects to the server, it asks for the list of available tools. Truto dynamically maps the flat arguments provided by the LLM into the required query strings and JSON body schemas required by Perkville.

Here are the highest-leverage operations your AI agent can perform.

### List All Connections

A `Connection` represents a specific user enrolled in a specific business's rewards program. This tool is the entry point for almost all user-centric workflows, allowing the model to search by email or external member IDs.

> "Find the Perkville connection record for alex.smith@example.com at our primary business location to get their connection ID."

### Get Connection Balance

Points balance queries are distinct from base connection records in the API. This tool retrieves the real-time point balance, lifetime earned points, and lifetime spent points for a specific user connection.

> "Check the current available point balance and lifetime earned points for connection ID 98765."

### Create a Transaction

This is the core ledger operation. It allows the agent to award points (or deduct them) for a specific user connection. The agent must pass the business ID, the user/email, and the point quantity.

> "Award 500 bonus points to alex.smith@example.com for completing the feedback survey. Ensure the transaction is attributed to our main business ID."

### List All Challenges

Challenges in Perkville dictate how users earn points (e.g., "Check-in 5 times", "Refer 3 friends"). This tool allows the agent to inspect the active rewards rules, eligibility criteria, and expiration dates.

> "List all active challenges for our business and identify which ones require an active membership to earn rewards."

### Create a Referral

Referral programs drive acquisition. This tool allows the agent to programmatically generate a referral record between an existing user and a prospect, triggering the associated challenge rewards when the criteria are met.

> "Create a referral record from existing user alex.smith@example.com to prospect jane.doe@example.com. Set the referral source to 'Support Chat Intervention'."

### Update a Voucher

When users redeem points, they receive a Voucher. This tool allows the agent to manipulate the state of that voucher, most commonly to mark it as `USED` after fulfilling a customer's request in another system.

> "Update voucher ID vch_10293 to mark its status as USED, as I have just applied the discount to their subscription billing system."

To view the complete inventory of available operations, endpoints, and exact JSON schema definitions, visit the [Perkville integration page](https://truto.one/integrations/detail/perkville).

## Workflows in Action

MCP tools become powerful when the LLM chains them together to solve multi-step problems. Here are two real-world examples of how support and operations personas can automate Perkville workloads.

### Scenario 1: Proactive Support Compensation

**Persona:** Customer Support Specialist

> "A customer (sarah.connor@example.com) had a terrible experience with a late delivery today. Check her current loyalty status and point balance. If she is an active member, issue her 1,000 apology points under our main business account and let me know her new total."

**How the Agent Executes:**
1. Calls `list_all_perkville_connections` filtering by `sarah.connor@example.com` to verify enrollment and extract the `connection_id` and `business_id`.
2. Calls `get_single_perkville_connection_balance_by_id` using the retrieved `connection_id` to read the current state.
3. Calls `create_a_perkville_transaction` passing the `business_id`, the user's email, a quantity of `1000`, and a title note of "Service Recovery Bonus".
4. Calls `get_single_perkville_connection_balance_by_id` again to confirm the updated point balance.

The user receives a concise summary of the transaction success and the customer's new point total, entirely avoiding manual ledger entries.

```mermaid
sequenceDiagram
    participant User
    participant LLM as Claude Desktop
    participant Truto as Truto MCP Server
    participant Upstream as Perkville API

    User->>LLM: "Check points for sarah... award 1000 points..."
    LLM->>Truto: call tool: list_all_perkville_connections(email)
    Truto->>Upstream: GET /v2/connections/?email=sarah...
    Upstream-->>Truto: Return connection data
    Truto-->>LLM: connection_id, business_id

    LLM->>Truto: call tool: create_a_perkville_transaction(points: 1000)
    Truto->>Upstream: POST /v2/transactions/
    Upstream-->>Truto: Transaction success
    Truto-->>LLM: 200 OK

    LLM-->>User: "I have successfully awarded 1,000 points."
```

### Scenario 2: Campaign Audit and Voucher Management

**Persona:** Marketing Operations

> "We need to audit our 'Summer VIP' challenge. Find the challenge, check if any users have earned vouchers from it, and if there are any unredeemed vouchers older than 30 days, mark them as expired."

**How the Agent Executes:**
1. Calls `list_all_perkville_challenges` filtering by the name "Summer VIP" to extract the specific challenge configuration and associated perk rules.
2. Calls `list_all_perkville_vouchers` filtering by the relevant business and perk ID to retrieve all distributed rewards.
3. Claude processes the returned JSON, analyzing the `created_datetime` and `status` fields against the current date.
4. Iteratively calls `update_a_perkville_voucher_by_id` for any vouchers that meet the expiration criteria, patching the status or `expiration_date`.

The marketing manager gets an automated cleanup of the voucher liability table without writing a script or manually digging through the Perkville UI.

## Security and Access Control

Connecting an autonomous AI agent to an immutable transaction ledger requires stringent security controls. Truto provides four distinct mechanisms to secure your Perkville MCP servers:

*   **Method Filtering:** By defining `config.methods: ["read"]`, you can create a safe, read-only MCP server. The tool generation engine evaluates this filter at runtime. If the model attempts to invoke a write operation, the tool simply will not exist in the server's directory.
*   **Tag Filtering:** Limit the server's scope to specific functional areas using `config.tags`. For instance, applying a `["reporting"]` tag ensures the LLM can only access analytical endpoints, hiding administrative user management tools entirely.
*   **Expiration Controls:** Using the `expires_at` property creates short-lived, ephemeral MCP access. Truto utilizes a distributed alarm service to automatically purge the token from edge storage when the time-to-live is reached, ensuring temporary access cannot be exploited later.
*   **Extra Authentication (`require_api_token_auth`):** For enterprise environments where MCP URLs might be exposed in configuration files, setting this flag to `true` mandates a second layer of authentication. The MCP client must provide a valid Truto API token in the Authorization header to successfully invoke tools.

## Building Agentic Loyalty Workflows

Integrating AI with enterprise systems is no longer about summarizing text; it is about taking action. But building the middleware to facilitate those actions - handling OAuth 2.0, mapping dense JSON schemas, and normalizing IETF rate limits - consumes engineering resources that should be spent on your core product.

Truto's dynamic MCP server architecture removes the boilerplate. By generating tools directly from documented API resources at runtime, your AI agents always have safe, schema-validated access to the underlying vendor ecosystem.

Stop hand-coding API connectors just to give your LLM access to a third-party ledger.

> Want to connect your AI agents to Perkville and 100+ other enterprise applications without writing integration code? Let's build your managed MCP architecture.
>
> [Talk to us](https://cal.com/truto/partner-with-truto)