Connect Easypromos to Claude: Track User Engagement and Virtual Coins

If your team needs to connect Easypromos to Claude to automate gamification workflows, manage virtual coin inventories, or analyze participant engagement, you need a Model Context Protocol (MCP) server. This server acts as the translation layer between Claude's tool calls and the Easypromos REST API. 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 Easypromos to ChatGPT or explore our broader architectural overview on connecting Easypromos to AI Agents.

Giving a Large Language Model (LLM) read and write access to a gamification and promotion engine like Easypromos is an engineering challenge. You have to handle API token lifecycles, map complex JSON schemas to MCP tool definitions, and navigate domain-specific workflows like two-step login token retrieval for user operations. Every time Easypromos updates an endpoint or changes a payload requirement, you have to update your custom integration layer, redeploy, and test.

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

The Engineering Reality of the Easypromos 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, the reality of implementing it against specialized APIs is painful. Easypromos is built to run highly stateful, compliance-heavy promotions with complex participant lifecycles.

If you decide to build a custom MCP server for Easypromos, here are the specific integration challenges you will face:

The Login Token (lt) Auth Pattern Standard APIs operate on resource IDs. If you want to update a user, you pass the user_id. Easypromos enforces a much stricter security model for participant-facing operations. To assign a segment, check participation limits, or grant virtual coins, an LLM cannot just use the user_id. It must first make an API call to generate a short-lived "Login Token" (lt) for that specific user and promotion, and then inject that lt into the payload of subsequent requests. A custom MCP server requires you to build chaining logic to handle this; a dynamically generated MCP server exposes this naturally via separate tools, teaching the LLM the correct sequence through JSON schema definitions.

Multi-Currency Virtual Coin Management Gamification environments are often multi-currency. A single promotion might track "Points", "Tokens", and "Tickets" as distinct virtual coin ledgers. You do not just hit a /add-points endpoint. You must fetch the user's current coin balances, extract the exact coin_id for the ledger you want to modify, and then submit a signed transaction payload containing the promotion_id, the user's lt, the positive or negative amount, and a required reason string for the audit log.

Stateful Participation Gating LLMs tend to assume they can just execute write operations (like submitting a participation) immediately. In Easypromos, participation requires checking state constraints first. A promotion stage might limit users to one participation per day, or require a specific virtual coin balance to enter. If the LLM tries to force a participation without checking these limits, the API throws complex validation errors. The integration layer must expose discrete check-and-execute tools so the agent can "look before it leaps."

Truto's Managed MCP Server Architecture

Truto eliminates the need to build a custom MCP server by dynamically generating one from the Easypromos API documentation and resource schemas. When you connect an Easypromos account via Truto, the platform's MCP router exposes those resources as JSON-RPC 2.0 tools.

Here is what that architecture looks like:

flowchart TD
    Claude["Claude Desktop<br>(MCP Client)"]
    TrutoRouter["Truto MCP Router<br>(JSON-RPC 2.0)"]
    ProxyAPI["Truto Proxy API<br>(Auth & Pagination)"]
    Easypromos["Easypromos API<br>(Upstream)"]

    Claude -->|"HTTP POST<br>/mcp/:token"| TrutoRouter
    TrutoRouter -->|"tools/list<br>tools/call"| ProxyAPI
    ProxyAPI -->|"Bearer Token<br>REST Requests"| Easypromos

How Truto handles tool generation and input flattening: Truto does not hardcode tools. It inspects the Easypromos API definitions and documentation records at runtime. For every documented resource method (e.g., list, get, create), it constructs a tool.

When Claude calls a tool, it passes arguments in a flat JSON object. Truto's router intelligently splits this flat object, routing parameters to the upstream query string or JSON body based on the original Easypromos API schema requirements. This means Claude only has to worry about providing the right data, while Truto handles the HTTP mechanics.

Step 1: Generating the Easypromos MCP Server URL

To connect Claude to Easypromos, you first need a secure MCP server URL. Truto issues a unique, cryptographically hashed token scoped exclusively to a specific connected Easypromos account.

You can generate this URL using either the Truto UI or the Truto API.

Method A: Via the Truto UI (For IT and Admins)

1. Log into your Truto dashboard and navigate to the Integrated Accounts section.
2. Select the specific Easypromos connection you want to expose to Claude.
3. Click on the MCP Servers tab.
4. Click Create MCP Server.
5. Select your configuration preferences (e.g., restricting access to specific methods or tagging categories).
6. Click Generate and securely copy the resulting MCP Server URL (it will look like https://api.truto.one/mcp/a1b2c3d4...).

Method B: Via the API (For Developers)

If you are automating the provisioning of AI agents, you can generate MCP servers programmatically. Make an authenticated POST request to the Truto API:

curl -X POST https://api.truto.one/integrated-account/{integrated_account_id}/mcp \
  -H "Authorization: Bearer YOUR_TRUTO_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "name": "Easypromos Engagement Agent",
    "config": {
      "methods": ["read", "write", "custom"]
    }
  }'

The API will return the server details:

{
  "id": "mcp_srv_9x8y7z",
  "name": "Easypromos Engagement Agent",
  "config": {
    "methods": ["read", "write", "custom"]
  },
  "expires_at": null,
  "url": "https://api.truto.one/mcp/a1b2c3d4e5f6g7h8..."
}

Keep the url value safe - this is the endpoint Claude will use to interact with Easypromos.

Step 2: Connecting the MCP Server to Claude

Now that you have the Truto MCP server URL, you need to configure Claude to use it. Because Truto MCP servers operate over HTTP Server-Sent Events (SSE) via a remote transport proxy, they are incredibly easy to configure.

Method A: Via the Claude UI (Desktop or Web)

If your organization uses Claude's web or desktop interfaces with custom connector support:

1. Open Claude and navigate to Settings.
2. Locate the Integrations or Connectors section.
3. Click Add MCP Server or Add custom connector.
4. Give the connector a recognizable name (e.g., "Easypromos (Truto)").
5. Paste the Truto MCP Server URL into the endpoint field.
6. Click Add or Save. Claude will instantly handshake with Truto and pull down the list of available Easypromos tools.

(Note: For ChatGPT users on Pro/Enterprise plans, the process is nearly identical via Settings -> Apps -> Advanced settings -> Developer mode -> Custom connectors).

Method B: Via Manual Configuration File (Claude Desktop)

If you are a developer using Claude Desktop and prefer file-based configuration, you can edit the claude_desktop_config.json file directly.

Add the following block to your configuration file, using the official @modelcontextprotocol/server-sse npx runner to handle the remote transport layer:

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

Restart Claude Desktop. The application will initialize the server and the Easypromos tools will immediately become available in the context window.

Security and Access Control

Giving an AI agent access to production participant data requires strict guardrails. Truto's MCP tokens are isolated per-account and support multiple layers of configuration:

• Method Filtering: Use the config.methods array to restrict the server to specific operations. Passing ["read"] ensures Claude can only pull user reports and coin balances, physically preventing it from altering transactions or limits.
• Tag Filtering: Use config.tags to scope access by functional area. If you only want the LLM to access gamification data but not admin organizing brands, you can restrict the tools to specific tagged resources.
• Expiration (expires_at): You can set a strict ISO 8601 datetime for the token. Once the timestamp passes, the distributed key-value store automatically purges the token, terminating Claude's access immediately. Ideal for short-lived debugging sessions.
• Secondary Authentication (require_api_token_auth): By default, the cryptographically secure URL is the only authentication needed. Setting require_api_token_auth: true forces the client to also pass a valid Truto API token in the Authorization header, adding a strict identity-based perimeter.

Hero Tools for Easypromos Automation

Truto automatically generates tools for every documented Easypromos resource. Here are 6 high-leverage tools that unlock complex gamification workflows for Claude.

1. list_all_easypromos_users

Retrieves the participants registered in an Easypromos promotion. It returns key attributes like first_name, email, segments, and the underlying user_id.

Context: This is almost always the first tool an AI agent calls to identify a participant in a workflow. The agent uses the email to find the id required for subsequent operations.

"Find the user with the email address player1@example.com in promotion ID 55432 and tell me what segments they belong to."

2. get_single_easypromos_users_logintoken_by_id

Generates the unique login access code (lt) for a specific user within a promotion.

Context: This tool bridges the gap between identity and authorization. Because Easypromos requires an lt parameter for sensitive gamification writes, the LLM must call this tool after finding the user ID but before granting coins or logging participations.

"Generate a login token for user ID 98765 in promotion 55432 so we can adjust their virtual coin balance."

3. list_all_easypromos_coin_users

Retrieves the virtual coin balances of a single user in an Easypromos promotion.

Context: Since promotions can support multiple currencies (e.g., "Gold" and "Silver"), this tool returns an array of coin objects, each containing the coin_id, name, and current balance. The LLM needs this to find the correct coin_id for ledger updates.

"Check the current virtual coin balances for user ID 98765 in promotion 55432. Tell me how much 'Gold' they have."

4. create_a_easypromos_coin_transaction

Creates a ledger entry to add or remove virtual coins for a participant. A positive amount credits coins; a negative amount debits them.

Context: This is the core write tool for gamification currency. It requires the promotion_id, the user's lt, the amount, and a descriptive reason for the audit log.

"Add 500 virtual coins to this user's balance. Use their login token 'abc123xyz' for promotion 55432, and set the reason to 'Support compensation for downtime'."

5. list_all_easypromos_participation_remainings

Checks the remaining participations a user has left in a specific stage of a promotion, based on configured velocity limits (per hour, day, week, etc.).

Context: Essential for validating whether an action is allowed before attempting it. It returns remaining, can_participate, and next_participation timestamp.

"Check if user ID 98765 is allowed to participate in stage ID 1234 of promotion 55432 today. How many tries do they have left?"

6. list_all_easypromos_participation_participates

Submits a new participation for a registered user, consuming one of their available limits. Highly recommended for Instant Win or "Spin the Wheel" stages.

Context: This executes the primary gamification loop. It requires the user's lt, the promotion_id, and the stage_id. It returns the participation_id and any prize won.

"Using login token 'abc123xyz', execute a participation for stage 1234 in promotion 55432. Tell me if the user won a prize."

For a complete list of tools, including organizing brands, ranking systems, and point-of-sale management, review the Easypromos Integration Page.

Workflows in Action

Giving Claude access to discrete tools is useful, but the real value emerges when the LLM chains them together to handle multi-step gamification tasks.

Workflow 1: Gamification Support and Coin Adjustments

Customer support teams often need to adjust a participant's virtual balance due to bugs, complaints, or manual rewards.

User Prompt:

"A player with email 'vip_player@example.com' complained their points didn't sync for promotion 55432. Check their current balance, and if it's under 1000, grant them 500 coins. Use the reason 'Manual VIP Support Grant'."

How Claude executes this:

1. Calls list_all_easypromos_users (passing promotion_id: 55432) to find the user ID for vip_player@example.com.
2. Calls get_single_easypromos_users_logintoken_by_id to generate the lt required for transaction operations.
3. Calls list_all_easypromos_coin_users to identify the user's current balance and extract the correct coin_id.
4. Evaluates the balance logic natively. Finding it is under 1000, it proceeds.
5. Calls create_a_easypromos_coin_transaction using the promotion_id, the lt, an amount of 500, and the requested reason.

Result: Claude responds to the support agent confirming the exact previous balance, the new transaction ID, and verifying that the user now has the updated coin amount in their ledger.

Workflow 2: Programmatic Participation Execution

Marketing teams running external events or physical activations might need to process digital participations in bulk based on off-platform actions.

User Prompt:

"I need to log a participation for user ID 44556 in the Instant Win stage (ID 8899) for promotion 55432. Before doing so, check if they have any participations left for the day. If they do, run the participation and tell me what prize they won."

How Claude executes this:

1. Calls list_all_easypromos_participation_remainings passing the user_id, stage_id, and promotion_id.
2. Claude analyzes the can_participate boolean and the remaining integer in the response.
3. If valid, Claude calls get_single_easypromos_users_logintoken_by_id to fetch the user's lt.
4. Calls list_all_easypromos_participation_participates using the lt, promotion_id, and stage_id.

Result: Claude returns a formatted summary: "The user had 2 participations remaining today. I executed the participation (ID: 998877). Good news - the user won the '10% Discount Code' prize!"

sequenceDiagram
    participant User as Human Operator
    participant LLM as Claude Desktop
    participant MCP as Truto MCP Server
    
    User ->> LLM: "Log participation if user has tries left..."
    LLM ->> MCP: Call list_all_easypromos_participation_remainings
    MCP -->> LLM: Returns remaining: 2, can_participate: true
    LLM ->> MCP: Call get_single_easypromos_users_logintoken_by_id
    MCP -->> LLM: Returns lt: "abc123xyz"
    LLM ->> MCP: Call list_all_easypromos_participation_participates
    MCP -->> LLM: Returns participation_id, prize data
    LLM -->> User: "Participation successful. Won 10% discount!"

Rate Limits, Pagination, and Error Handling

When writing automated workflows, understanding how the underlying infrastructure handles scale is critical.

A factual note on rate limits: Truto does not retry, throttle, or apply backoff logic on rate limit errors. When the upstream Easypromos API returns an HTTP 429 (Too Many Requests), Truto passes that error directly to the caller. Truto normalizes the upstream rate limit data into standardized headers (ratelimit-limit, ratelimit-remaining, ratelimit-reset) per the IETF specification. The caller (in this case, your AI agent framework or custom MCP client script) is completely responsible for handling retries, delays, or exponential backoffs based on those headers. Truto does not automatically absorb these errors.

Handling Pagination: For list endpoints (like list_all_easypromos_users), Truto automatically enhances the tool schemas with limit and next_cursor properties. The MCP tool description explicitly instructs the LLM to pass cursor values back exactly as received. If Claude notices that a result set is incomplete, it knows how to invoke the tool again, injecting the next_cursor from the previous response to walk through the dataset.

Accelerating Gamification Operations

Gamification logic is inherently complex. Managing virtual economies, stateful participation limits, and segmented user audiences requires precision. Building point-to-point scripts for every new promotion or requirement drains engineering resources.

By leveraging Truto's dynamically generated MCP server, you abstract away the API mechanics while preserving the full capabilities of the Easypromos platform. Claude can navigate the login token dance, query multi-currency ledgers, and execute instant-win logic safely and predictably.

Stop writing hardcoded integration scripts. Give your AI agents native, tool-calling access to Easypromos and build better gamification experiences today.