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. 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, 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 or explore our broader architectural overview on connecting Perkville to AI Agents.

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

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

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

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.

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.