AI Integration with Model Context Protocol (MCP)

The Loyalteez MCP Server enables AI assistants like Claude, ChatGPT, and Cursor to directly integrate, manage, and build complete Loyalteez loyalty programs—including gamification features like streaks, leaderboards, achievements, and perks—through natural conversation.

What is MCP?

Model Context Protocol (MCP) is an open standard that allows AI assistants to:

Invoke Tools: Execute actions (API calls, file operations)
Access Resources: Read structured data (configs, schemas)
Maintain Context: Understand domain-specific information

Why Use MCP for Loyalteez?

Instead of manually reading documentation and writing integration code, you can simply describe what you want:

Traditional Integration Flow:
Developer → Reads Docs → Writes Code → Tests → Debugs → Ships

AI-Native Integration Flow:
Developer → Describes Intent → AI Invokes MCP → Validates → Ships

Installation

Prerequisites

Node.js 18+ installed
Claude Desktop, Cursor, or another MCP-compatible AI assistant

Install the MCP Server

Option 1: Install from npm (Recommended)

npm install -g @loyalteez/mcp-server

Or install locally:

npm install @loyalteez/mcp-server

Option 2: Install from GitHub

git clone https://github.com/Alpha4-Labs/loyalteez-mcp.git
cd loyalteez-mcp
npm install
npm run build

Configuration

Claude Desktop

Add to your Claude Desktop MCP configuration (~/Library/Application Support/Claude/claude_desktop_config.json on macOS, %APPDATA%\Claude\claude_desktop_config.json on Windows):

If installed via npm:

{
  "mcpServers": {
    "loyalteez": {
      "command": "npx",
      "args": ["@loyalteez/mcp-server"],
      "env": {
        "LOYALTEEZ_NETWORK": "mainnet",
        "LOYALTEEZ_BRAND_ID": "0x47511fc1c6664c9598974cb112965f8b198e0c725e"
      }
    }
  }
}

If installed from GitHub:

{
  "mcpServers": {
    "loyalteez": {
      "command": "node",
      "args": ["/path/to/loyalteez-mcp/dist/index.js"],
      "env": {
        "LOYALTEEZ_NETWORK": "mainnet",
        "LOYALTEEZ_BRAND_ID": "0x47511fc1c6664c9598974cb112965f8b198e0c725e"
      }
    }
  }
}

Cursor

Add to .cursor/mcp.json:

If installed via npm:

{
  "servers": {
    "loyalteez": {
      "command": "npx",
      "args": ["@loyalteez/mcp-server"],
      "env": {
        "LOYALTEEZ_NETWORK": "mainnet",
        "LOYALTEEZ_BRAND_ID": "your-brand-id-here"
      }
    }
  }
}

If installed from GitHub:

{
  "servers": {
    "loyalteez": {
      "command": "node",
      "args": ["/path/to/loyalteez-mcp/dist/index.js"],
      "env": {
        "LOYALTEEZ_NETWORK": "mainnet",
        "LOYALTEEZ_BRAND_ID": "your-brand-id-here"
      }
    }
  }
}

Environment Variables

LOYALTEEZ_NETWORK: Network to use - mainnet (default) or testnet
LOYALTEEZ_BRAND_ID: Your brand wallet address (optional, can also be provided per-tool)

Quick Start Examples

Example 1: Design a Loyalty Program

Simply describe what you want:

User: "Design a loyalty program for my developer Discord with events for 
quality contributions, daily check-ins, and helpful answers"

AI: [Uses loyalteez_design_program tool]
    Returns: Complete program with:
    - Event structure
    - Reward amounts
    - Implementation code
    - Best practices

Example 2: Add Daily Check-ins

User: "Add daily check-ins with streak bonuses to my Telegram bot"

AI: [Uses loyalteez_streak_checkin tool]
    Generates code:
    - Bot command handler
    - Streak tracking logic
    - Multiplier calculations
    - Milestone notifications

Example 3: Create Custom Events

User: "Create 5 events for my Telegram trading community: daily check-in, 
helpful answer, trade signal, referral, and milestone celebration"

AI: [Uses loyalteez_create_events_batch tool]
    Returns:
    - All created events with IDs
    - Telegram bot implementation code
    - Event tracking examples

Available Tools

The MCP server provides 24+ tools organized into categories:

Program Design

loyalteez_design_program - AI-powered program generation

Event Management

loyalteez_create_event - Create single custom event
loyalteez_create_events_batch - Create multiple events
loyalteez_track_event - Fire events and reward users
loyalteez_get_event_config - Get all configured events
loyalteez_bulk_events - Batch event tracking
loyalteez_admin_reward - Manual admin rewards

User Management

loyalteez_resolve_user - Convert platform identity to wallet
loyalteez_get_user_balance - Get user balance and history
loyalteez_check_eligibility - Check reward eligibility
loyalteez_get_user_stats - Comprehensive user statistics

Engagement & Gamification

loyalteez_streak_checkin - Process streak check-in
loyalteez_get_streak_status - Get streak status
loyalteez_claim_streak_milestone - Claim milestone bonuses
loyalteez_log_activity - Track voice/message activity
loyalteez_calculate_reward - Calculate rewards with multipliers
loyalteez_get_leaderboard - Get ranked leaderboards
loyalteez_update_leaderboard_stats - Update user stats

loyalteez_create_drop - Create time-limited reward drops
loyalteez_claim_drop - Process drop claims
loyalteez_process_third_party_event - Integrate with Mee6, Arcane, etc.

Perks & Redemption

loyalteez_list_perks - Get available perks
loyalteez_check_perk_eligibility - Check perk eligibility
loyalteez_redeem_perk - Redeem a perk

Achievements

loyalteez_get_user_achievements - Get user achievements
loyalteez_update_achievement_progress - Update achievement progress

Transactions

loyalteez_relay_transaction - Execute gasless transactions

Webhooks

loyalteez_validate_webhook - Validate webhook signature
loyalteez_webhook_example - Generate webhook receiver code

Diagnostics

loyalteez_health_check - Check API health status

Available Resources

The MCP server provides access to:

Documentation Resources

All developer documentation is available as MCP resources:

loyalteez://docs/architecture
loyalteez://docs/api/rest-api
loyalteez://docs/integrations/discord
loyalteez://docs/guides/custom-events
... and 50+ more documentation pages

Static Resources

Contracts: loyalteez://contracts/ltz-token, loyalteez://contracts/perk-nft, loyalteez://contracts/all
Network: loyalteez://network/config - Soneium network configuration
Event Types: loyalteez://events/standard - Standard event types reference (includes channel constraints and domain validation)
Shared Services: loyalteez://shared-services/endpoints - API endpoints reference
OAuth Providers: loyalteez://platforms/mappings - OAuth provider ID formats
Error Codes: loyalteez://errors/codes - Complete HTTP status codes and error response reference
Error Handling: loyalteez://errors/handling - Error handling patterns and best practices
Rate Limits: loyalteez://rate-limits/endpoints - Rate limits by endpoint with reset periods
Rate Limit Strategies: loyalteez://rate-limits/strategies - Code examples for handling rate limits
SDK Methods: loyalteez://sdk/methods - JavaScript SDK method reference with examples
SDK Examples: loyalteez://sdk/examples - SDK usage examples for React, Vue, Next.js

BrandId Configuration

The brandId parameter is required for most operations. You can provide it in two ways:

Environment Variable (Recommended): Set LOYALTEEZ_BRAND_ID in your MCP configuration
Tool Parameter: Provide brandId as a parameter to each tool call

If neither is provided, tools will return a helpful error message explaining how to set it up.

Common Use Cases

Discord Bot Integration

User: "Add loyalty rewards to my Discord bot. Reward users for:
- Daily check-ins (50 LTZ)
- Helpful answers (100 LTZ)
- Voice chat participation (10 LTZ per 5 minutes)"

AI generates complete Discord.js bot code with:
- Command handlers
- Event tracking
- Reward distribution
- Error handling

Telegram Bot Integration

User: "Create a Telegram bot that tracks daily check-ins with streaks"

AI generates complete Telegraf bot code with:
- /checkin command
- Streak tracking
- Milestone notifications
- Leaderboard integration

Web Integration

User: "Add loyalty rewards to my Next.js app for newsletter signups and purchases"

AI generates:
- React components
- API route handlers
- Event tracking hooks
- Balance display components

Best Practices

Set BrandId in Environment: Use LOYALTEEZ_BRAND_ID environment variable for convenience
Use Resources: AI can access documentation resources to understand best practices
Test on Testnet: Use LOYALTEEZ_NETWORK=testnet for testing
Check Eligibility: Use loyalteez_check_eligibility before tracking events
Update Leaderboards: Call loyalteez_update_leaderboard_stats after rewards

Troubleshooting

BrandId Not Found

If you see "BrandId is required but not provided":

Set LOYALTEEZ_BRAND_ID in your MCP configuration, or
Provide brandId as a parameter to tool calls

Tool Not Found

Ensure you've built the project:

cd loyalteez-mcp
npm run build

Resource Not Found

Resources are loaded at server startup. Ensure:

Documentation files exist in the expected location
Resource URIs match the expected format

Architecture

AI Assistant (Claude/ChatGPT/Cursor)
    ↓ MCP Protocol
Loyalteez MCP Server
    ↓ HTTP API
Loyalteez APIs
    - Event Handler (api.loyalteez.app)
    - Shared Services (services.loyalteez.app)
    - Pregeneration (register.loyalteez.app)

Security

No API keys required - uses public brandId identifier
All inputs validated server-side
Rate limiting awareness (documented limits)
Support for testnet/mainnet separation
BrandId can be set via environment variable for convenience

Next Steps

Install and configure the MCP server
Try a simple prompt: "Design a loyalty program for my Discord server"
Review the generated code and customize as needed
Deploy and test your integration

Recent Updates

The MCP server includes support for the latest Loyalteez features:

Boost Events: Custom Discord server boost events (first_boost, tier_1_boost, tier_2_boost, tier_3_boost, boost_tier_upgrade)
Natural Participation: Automatic rewards for GM/GN check-ins, quality messages, popular messages, auto-welcome, voice activity
Role Bonuses: Role-based multipliers (1.0-5.0x) and flat bonuses (0-1000 LTZ) for Discord roles
Max Claims: Clarified event-level vs drop-level max claims (999999 or -1 for unlimited)

Package Information

npm Package: @loyalteez/mcp-server
GitHub Repository: Alpha4-Labs/loyalteez-mcp
Version: 1.0.0
License: MIT

For more examples and detailed documentation, see the MCP Server README.

What is MCP?​

Why Use MCP for Loyalteez?​

Installation​

Prerequisites​

Install the MCP Server​

Configuration​

Claude Desktop​

Cursor​

Environment Variables​

Quick Start Examples​

Example 1: Design a Loyalty Program​

Example 2: Add Daily Check-ins​

Example 3: Create Custom Events​

Available Tools​

Program Design​

Event Management​

User Management​

Engagement & Gamification​

Social Features​

Perks & Redemption​

Achievements​

Transactions​

Webhooks​

Diagnostics​

Available Resources​

Documentation Resources​

Static Resources​

BrandId Configuration​

Common Use Cases​

Discord Bot Integration​

Telegram Bot Integration​

Web Integration​

Best Practices​

Troubleshooting​

BrandId Not Found​

Tool Not Found​

Resource Not Found​

Architecture​

Security​

Related Documentation​

Next Steps​

Recent Updates​

Package Information​