Connect Perkville to ChatGPT: Sync Loyalty Rules and User Points

If you want your AI agents to audit customer point balances, trigger referral rewards, or manage loyalty program tiers, you need to connect Perkville to ChatGPT. If your team uses Claude instead, check out our guide on connecting Perkville to Claude, 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 and rewards platform is an engineering challenge. The Model Context Protocol (MCP) provides a standardized way for AI models to discover and execute tools, but building an MCP server from scratch means dealing with OAuth 2.0 token lifecycles, maintaining massive JSON schemas for every endpoint, and handling complex rate limits.

You can either spend weeks building and hosting a custom integration layer, or you can use a managed platform to automatically derive those tools directly from the API documentation. This guide breaks down exactly how to use Truto to generate a secure, managed MCP server for Perkville, connect it natively to ChatGPT, and execute complex loyalty workflows using natural language.

The Engineering Reality of the Perkville API

A custom MCP server is a self-hosted translation layer that turns an LLM's tool calls into REST API requests. If you decide to build a custom MCP server for Perkville, your engineering team is entirely responsible for the API lifecycle.

Integrating with Perkville introduces specific domain challenges that break standard CRUD assumptions.

The Relational Complexity of Loyalty Data

In Perkville, a global User is distinctly separate from their relationship with a specific rewards program. To track a user's point balance or lifetime earned points, you cannot simply query a /users endpoint. You must navigate to a Connection, which represents the relationship between a User and a Business. If an LLM attempts to look up points based on a user ID without understanding the business context, the query will fail. Your custom server must define explicit JSON schemas that guide the LLM to pass the correct relational IDs.

Business-Scoped Filtering Requirements

Many of Perkville's core endpoints - such as agreements, challenges, and staff rosters - strictly require a business ID filter to execute. Furthermore, Perkville's API does not support business__in array queries for many endpoints; you must query on a per-business basis. If your MCP server's schema does not mark the business parameter as strictly required, the LLM will construct invalid requests and hallucinate the response.

Raw Rate Limits and Standardized Headers

Perkville enforces its own specific rate limits on API requests. When interacting with an LLM that might fire off parallel tool calls to analyze hundreds of user transactions, you will inevitably hit 429 Too Many Requests errors.

It is critical to note that Truto does not automatically retry, throttle, or apply backoff logic on rate limit errors. When the upstream Perkville API returns an HTTP 429, Truto passes that error directly to the caller. What Truto does provide is normalization: it translates Perkville's upstream rate limit information into standardized HTTP headers (ratelimit-limit, ratelimit-remaining, ratelimit-reset) per the IETF specification. Your client application - or the LLM's own internal retry logic - is entirely responsible for interpreting these headers and executing exponential backoff. Do not build an MCP server assuming the network layer will absorb API abuse.

The Managed MCP Approach

Instead of manually mapping Perkville's relational model to MCP tool definitions, Truto utilizes dynamic, documentation-driven tool generation.

When you connect a Perkville account to Truto, the platform reads the integration's resource definitions and automatically derives the query schemas, body schemas, and tool descriptions. If a Perkville API endpoint changes, the MCP tool definition updates automatically. The resulting MCP server is exposed as a self-contained, token-secured URL that can be pasted directly into ChatGPT.

Step 1: Generate the Perkville MCP Server

Every MCP server in Truto is scoped to a single integrated account (a specific tenant's connected Perkville instance). You can generate the server URL via the Truto UI or programmatically via the API.

Method A: Via the Truto UI

For internal teams and one-off workflows, the dashboard is the fastest path.

1. Navigate to the Integrated Accounts page in your Truto dashboard.
2. Select your connected Perkville account.
3. Click the MCP Servers tab.
4. Click Create MCP Server.
5. Select your desired configuration (e.g., allow read and write methods, or filter by specific tags).
6. Copy the generated MCP server URL (it will look like https://api.truto.one/mcp/a1b2c3d4...).

Method B: Via the API

For production platforms dynamically spinning up agents for users, you should generate the server programmatically. Truto validates the configuration, hashes the token securely, and stores the configuration in a distributed key-value store for low-latency routing.

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

curl -X POST https://api.truto.one/integrated-account/<PERKVILLE_ACCOUNT_ID>/mcp \
  -H "Authorization: Bearer <YOUR_TRUTO_API_TOKEN>" \
  -H "Content-Type: application/json" \
  -d '{
    "name": "Perkville Admin Agent",
    "config": {
      "methods": ["read", "write"],
      "tags": ["loyalty", "users"]
    },
    "expires_at": "2026-12-31T23:59:59Z"
  }'

The API returns a fully configured MCP URL ready for the LLM:

{
  "id": "mcp_srv_9x8y7z",
  "name": "Perkville Admin Agent",
  "config": { "methods": ["read", "write"], "tags": ["loyalty", "users"] },
  "expires_at": "2026-12-31T23:59:59Z",
  "url": "https://api.truto.one/mcp/a1b2c3d4e5f6g7h8i9j0"
}

Step 2: Connect the Server to ChatGPT

Because the MCP server URL contains a cryptographic token encoding the authentication and account context, connecting it to a client requires zero additional OAuth boilerplate.

Method A: Via the ChatGPT UI

If you are using ChatGPT Plus, Team, or Enterprise, you can add custom connectors directly in the interface.

1. Open ChatGPT and go to Settings.
2. Navigate to Apps -> Advanced settings (or Connectors depending on your exact rollout phase).
3. Ensure Developer mode is enabled.
4. Click Add custom connector.
5. Name the connector "Perkville Loyalty Operations".
6. Paste the Truto MCP URL into the Server URL field and click Add.

ChatGPT will immediately ping the server's initialize endpoint, perform a handshake, and ingest all available Perkville tools.

Method B: Via Manual Config File (SSE Transport)

If you are deploying a custom agent framework or using desktop clients like Claude Desktop that rely on JSON configuration files, you can wrap the Truto endpoint using the standard SSE transport module.

Add the following to your agent's MCP configuration file:

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

Security and Access Control

Exposing an enterprise loyalty platform to an autonomous model requires strict access controls. Truto MCP servers support granular security primitives:

• Method Filtering: Restrict a server to safe operations. By setting config.methods = ["read"], the LLM can only execute get and list operations, preventing it from accidentally deleting perks or awarding unauthorized points.
• Tag Filtering: Group API resources logically. Setting config.tags = ["reporting"] ensures the LLM only sees tools related to read-only analytics, hiding destructive administrative endpoints.
• Require API Token Auth: By default, possessing the MCP URL grants access. By setting require_api_token_auth: true, you enforce a second layer of security - the client must pass a valid Truto API token in the Authorization header to successfully execute a tool.
• Automatic Expiration: Set an expires_at timestamp to create ephemeral MCP servers. Truto relies on distributed scheduled alarms to completely purge the token and configuration from storage the millisecond it expires, ensuring zero stale access.

Core Perkville Tools for LLMs

Truto auto-generates tools based on the underlying integration schema. Here are the highest-leverage hero tools your AI agent can use to orchestrate Perkville.

1. Get Single Perkville Business by ID

Loyalty programs in Perkville operate under a Business context. This tool retrieves the core metadata of the rewards program, including its physical locations, basic promotional messages, and branding configurations.

"Fetch the business details for ID 5920. I need to know the rewards program name, the loyalty launch date, and how many active locations are tied to this account."

2. List All Perkville Connections

A Connection represents the link between a user and a business's rewards program. This is the critical tool for retrieving point balances, lifetime earned points, and current tier levels.

"Look up the connection record for user_email 'john.doe@example.com' at business ID 5920. What is his current active point balance and lifetime earned points?"

3. Create a Perkville Transaction

Transactions are the ledger of a loyalty program. Use this tool to award points to a user for an action, or to deduct points. It requires the business ID and the user ID (or email).

"Award 500 bonus points to 'john.doe@example.com' under business ID 5920. Mark the classification as 'EARN' and set the title to 'Holiday Special Bonus'."

4. List All Perkville Perks

Perks define the actual reward rules. They are classified as either EARN (actions that generate points) or REDEEM (spending points for a reward). This tool allows an AI agent to audit the current rule configurations.

"List all active perks for business ID 5920. Filter the results to only show perks with the classification 'REDEEM' and tell me the point cost for the 'Free T-Shirt' reward."

5. Create a Perkville Referral

Referrals are a massive driver of loyalty growth. This tool allows the AI to programmatically trigger a referral flow between two users at a specific business.

"Create a new referral at business ID 5920. The referring user ID is 1045, and they are referring their friend at 'jane.smith@example.com'. Please confirm when the referral is logged."

6. List All Perkville Challenges View

Challenges are complex reward programs with multiple steps. This specific view tool returns data formatted from the user's perspective, including their requirement progress, eligibility, and completion rewards.

"Check the active challenges for business ID 5920. Tell me what completion rewards are currently configured for the 'Summer Fitness Challenge'."

For a full inventory of available tools, query schemas, and body parameters, review the Perkville integration page.

Workflows in Action

To understand how an AI agent uses these tools in a multi-step workflow, let's look at how ChatGPT navigates relational data to execute a loyalty operation.

Workflow 1: Auditing and Adjusting a User's Point Balance

A customer support agent asks ChatGPT to investigate a user who reported missing points, and then compensate them.

"Check the current point balance for sarah.connor@example.com at business 5920. If her balance is under 1,000 points, award her 250 points for 'Customer Support Adjustment'."

Execution Steps:

1. ChatGPT calls list_all_perkville_connections with business=5920 and user_email=sarah.connor@example.com.
2. The Perkville API returns the connection object, revealing a point_balance of 800.
3. ChatGPT evaluates the logic (800 < 1000).
4. ChatGPT calls create_a_perkville_transaction with business_id=5920, user_email=sarah.connor@example.com, points=250, classification=EARN, and title=Customer Support Adjustment.
5. The API returns a 201 Created with the new transaction ID.
6. ChatGPT replies to the support agent confirming the new balance.

sequenceDiagram
    participant User as Support Rep
    participant ChatGPT as ChatGPT
    participant TrutoMCP as Truto MCP Server
    participant Perkville as Perkville API

    User->>ChatGPT: "Check Sarah's balance, add 250 points if under 1k"
    ChatGPT->>TrutoMCP: Call list_all_perkville_connections
    TrutoMCP->>Perkville: GET /connections?business=5920&user_email=sarah...
    Perkville-->>TrutoMCP: Return connection (balance: 800)
    TrutoMCP-->>ChatGPT: Return schema data
    ChatGPT->>TrutoMCP: Call create_a_perkville_transaction
    TrutoMCP->>Perkville: POST /transactions (points: 250)
    Perkville-->>TrutoMCP: Return 201 Created (Transaction ID: 991)
    TrutoMCP-->>ChatGPT: Return success
    ChatGPT-->>User: "Done. Added 250 points. Her new balance is 1050."

Workflow 2: Exporting Active Redemption Rules

A marketing manager needs a summary of all active ways users can spend their points to update a landing page.

"I need to update our website's rewards page for business ID 5920. Please list all active redemption perks, what they cost in points, and any specific fine print attached to them."

Execution Steps:

1. ChatGPT calls list_all_perkville_perks with business=5920 and classification=REDEEM.
2. The Perkville API returns a paginated list of perk objects.
3. ChatGPT parses the title, points, and fine_print properties from the JSON array.
4. ChatGPT formats this data into a clean, human-readable markdown table for the marketing manager.

Redefining Loyalty Operations

Connecting Perkville to ChatGPT fundamentally changes how your team manages loyalty programs. Instead of forcing support reps to navigate complex SaaS dashboards to adjust point balances or requiring marketers to manually export reward rules to CSVs, you can orchestrate your entire loyalty stack using natural language.

By leveraging an MCP server managed by Truto, you eliminate the technical debt of building custom OAuth flows, maintaining pagination cursors, and updating schemas. Your engineering team focuses on core product features, while your AI agents get secure, real-time read and write access to the exact data they need.