Open Loyalty MCP Server

MCP (Model Context Protocol) server for interacting with Open Loyalty API. This server enables AI agents like Claude and ChatGPT to manage loyalty programs, members, points, rewards, and transactions.

Prerequisites

• Node.js 18 or later
• An Open Loyalty account with API access

Installation

Via npm (Recommended)

npm install -g @open-loyalty/mcp-server

Or use directly with npx (no installation required):

npx @open-loyalty/mcp-server

Claude Desktop one-click install (.mcpb)

The easiest way to install for Claude Desktop is the prebuilt .mcpb bundle. It includes the server and its dependencies, so no Node.js or npm setup is required.

1. Download the bundle: openloyalty-mcp.mcpb
2. Open the downloaded file, or drag it into the Extensions/Settings area of Claude Desktop to install it.
3. When prompted, enter your Open Loyalty API URL and API token.

To pin a specific version, use the jsDelivr URL, for example [email protected].

From Source

git clone https://github.com/OpenLoyalty/openloyalty-mcp.git
cd openloyalty-mcp/openloyalty-mcp
npm install
npm run build

Configuration

The server requires the following environment variables:

| Variable | Description | |----------|-------------| | OPENLOYALTY_API_URL | Your Open Loyalty API URL (e.g., https://api.openloyalty.io) | | OPENLOYALTY_API_TOKEN | Your API authentication token | | OPENLOYALTY_DEFAULT_STORE_CODE | Default store code (e.g., default) |

For local development, create a .env file based on .env.example:

cp .env.example .env

Transport Modes

The server supports two transport modes for different use cases:

| Mode | Binary | Use Case | |------|--------|----------| | stdio | openloyalty-mcp | Local usage with Claude Desktop, Claude Code, Cursor | | HTTP | openloyalty-mcp-http | Remote hosting, ChatGPT Actions, web integrations |

Both modes provide identical functionality - only the transport layer differs.

Stdio Mode (Local)

Use stdio mode when running the server locally with MCP clients like Claude Desktop.

Claude Desktop Configuration

Add this to your Claude Desktop configuration file:

• macOS: ~/Library/Application Support/Claude/claude_desktop_config.json
• Windows: %APPDATA%\Claude\claude_desktop_config.json

Using npx (Recommended)

{
  "mcpServers": {
    "openloyalty": {
      "command": "npx",
      "args": ["-y", "@open-loyalty/mcp-server"],
      "env": {
        "OPENLOYALTY_API_URL": "https://your-instance.openloyalty.io",
        "OPENLOYALTY_API_TOKEN": "your-api-token",
        "OPENLOYALTY_DEFAULT_STORE_CODE": "default"
      }
    }
  }
}

Using Global Installation

{
  "mcpServers": {
    "openloyalty": {
      "command": "openloyalty-mcp",
      "env": {
        "OPENLOYALTY_API_URL": "https://your-instance.openloyalty.io",
        "OPENLOYALTY_API_TOKEN": "your-api-token",
        "OPENLOYALTY_DEFAULT_STORE_CODE": "default"
      }
    }
  }
}

Using Local Build

{
  "mcpServers": {
    "openloyalty": {
      "command": "node",
      "args": ["/path/to/openloyalty-mcp/dist/index.js"],
      "env": {
        "OPENLOYALTY_API_URL": "https://your-instance.openloyalty.io",
        "OPENLOYALTY_API_TOKEN": "your-api-token",
        "OPENLOYALTY_DEFAULT_STORE_CODE": "default"
      }
    }
  }
}

HTTP Mode (Remote Hosting)

Use HTTP mode when hosting the server remotely for web-based MCP clients or ChatGPT Actions.

Running HTTP Server

# Using the binary
openloyalty-mcp-http

# Using npm scripts
npm run start:http

# Development mode
npm run dev:http

HTTP Environment Variables

| Variable | Required | Description | |----------|----------|-------------| | OPENLOYALTY_API_URL | Yes* | Open Loyalty API URL | | OPENLOYALTY_API_TOKEN | Yes* | API authentication token | | OPENLOYALTY_DEFAULT_STORE_CODE | Yes* | Default store code | | PORT or MCP_HTTP_PORT | No | Server port (default: 3000) | | OAUTH_ENABLED | No | Enable multi-tenant OAuth mode | | BASE_URL | OAuth | Public URL for OAuth callbacks | | REDIS_URL | OAuth | Redis URL for token storage | | OPENLOYALTY_MAX_RETRIES | No | Max retries for transient 429/503 responses (default: 4) | | OPENLOYALTY_RETRY_BASE_MS | No | Base backoff delay in ms (default: 500) | | OPENLOYALTY_RETRY_MAX_MS | No | Max backoff delay in ms (default: 8000) |

*Required when OAUTH_ENABLED is not set or false

The client automatically retries rate-limited (429) and briefly-unavailable (503) responses with exponential backoff and jitter, honoring any Retry-After header. This means firing several calls in parallel within one turn (e.g. multiple analytics tools) succeeds transparently rather than surfacing RATE_LIMITED.

HTTP Endpoints

| Endpoint | Method | Description | |----------|--------|-------------| | / | GET | Server info | | /health | GET | Health check | | /mcp | POST | MCP message endpoint | | /mcp | GET | SSE stream (with session) | | /mcp | DELETE | Close session |

Single-Tenant Mode

For dedicated deployments with fixed credentials:

export OPENLOYALTY_API_URL="https://api.openloyalty.io"
export OPENLOYALTY_API_TOKEN="your-token"
export OPENLOYALTY_DEFAULT_STORE_CODE="default"
openloyalty-mcp-http

Multi-Tenant OAuth Mode

For shared deployments where each user provides their own credentials:

export OAUTH_ENABLED=true
export BASE_URL="https://your-server.com"
export REDIS_URL="redis://localhost:6379"
openloyalty-mcp-http

With OAuth enabled, additional endpoints are available:

| Endpoint | Description | |----------|-------------| | /authorize | OAuth authorization form | | /token | Token exchange | | /register | Dynamic client registration | | /.well-known/oauth-authorization-server | OAuth metadata |

ChatGPT Actions Integration

To use with ChatGPT:

1. Host the HTTP server with OAuth enabled
2. In GPT Editor → Configure → Actions:
   • Authentication: OAuth
   • Authorization URL: https://your-server.com/authorize
   • Token URL: https://your-server.com/token
   • Scope: mcp
3. Add your MCP endpoint: https://your-server.com/mcp

Users will be prompted to enter their Open Loyalty credentials during the OAuth flow.

Development

# Run stdio server in development mode
npm run dev

# Run HTTP server in development mode
npm run dev:http

# Build for production
npm run build

# Run tests
npm test

# Type checking
npm run typecheck

Available Tools (145 total)

Wallet Types (4 tools)

• ol_wallet_type_list - List all available wallet types (point currencies)
• ol_wallet_type_get - Get full details for a specific wallet type by ID
• ol_wallet_type_create - Create a new point currency (wallet type)
• ol_wallet_type_update - Update an existing wallet type's configuration

Tier Sets (6 tools)

• ol_tierset_list - List all tier sets
• ol_tierset_create - Create a tier set (container for all tiers)
• ol_tierset_get - Get tier set details including condition IDs
• ol_tierset_update - Update tier set metadata
• ol_tierset_update_tiers - Add all tiers to a tier set in one call
• ol_tierset_get_tiers - Get all tiers in a tier set

Members (11 tools)

• ol_member_create - Register a new loyalty program member
• ol_member_get - Get member details including profile, points balance, and tier status
• ol_member_list - Search and list members with optional filters
• ol_member_update - Update member profile fields
• ol_member_activate - Activate a member account
• ol_member_deactivate - Deactivate a member account
• ol_member_delete - Permanently remove member and all associated data
• ol_member_anonymize - GDPR-compliant anonymization of all member PII
• ol_member_get_tier_progress - Get a member's tier progression status
• ol_member_assign_tier - Manually assign a tier level to a member
• ol_member_remove_manual_tier - Remove manually assigned tier from member

Points (10 tools)

• ol_points_add - Add points to a member's wallet manually
• ol_points_spend - Deduct points from member wallet
• ol_points_transfer - Transfer points from one member to another (P2P)
• ol_points_block - Block (freeze) points from a member's active balance
• ol_points_unblock - Release a blocked points transfer back to active balance
• ol_points_cancel - Cancel a specific points transfer, reversing the movement
• ol_points_expire - Manually expire a points transfer before its natural expiry
• ol_points_get_balance - Get member points balance breakdown
• ol_points_get_history - Get points transaction history for a member
• ol_points_get_histogram - Get points histogram data for visualization

Rewards (14 tools)

• ol_reward_list - List available rewards
• ol_reward_create - Create a new reward that members can redeem with points
• ol_reward_get - Get full reward details including configuration and coupon settings
• ol_reward_update - Update reward configuration
• ol_reward_activate - Activate a reward, making it available to redeem
• ol_reward_deactivate - Deactivate a reward, hiding it from members
• ol_reward_buy - Purchase reward for member, deducting points
• ol_reward_redeem - Mark coupon as used
• ol_reward_category_list - List reward categories
• ol_reward_category_create - Create a new reward category
• ol_reward_category_update - Update a reward category's name, status, or sort order
• ol_reward_photo_upload - Attach a photo to a reward
• ol_reward_photo_delete - Permanently delete a photo from a reward
• ol_member_get_issued_rewards - List rewards redeemed/issued to a specific member

Transactions (4 tools)

• ol_transaction_create - Record a purchase transaction
• ol_transaction_get - Get transaction details
• ol_transaction_list - List transactions with filters
• ol_transaction_assign_member - Assign unmatched transaction to member

Campaigns (13 tools)

• ol_campaign_list - List all campaigns with optional filters
• ol_campaign_create - Create campaign (earning rule) to automate engagement
• ol_campaign_get - Get full campaign configuration
• ol_campaign_update - Full update of campaign configuration
• ol_campaign_patch - Partial update (active/displayOrder only)
• ol_campaign_delete - Permanently delete a campaign
• ol_campaign_simulate - Simulate campaign effects without executing
• ol_campaign_generate_codes - Generate unique redemption codes for a campaign
• ol_campaign_list_codes - List redemption codes for a campaign
• ol_campaign_get_available - Get campaigns available to a member
• ol_campaign_get_visible - Get campaigns visible to a member
• ol_campaign_get_leaderboard - Get leaderboard rankings for a campaign
• ol_member_get_challenge_progress - Get a member's progress on all challenges

Segments (9 tools)

• ol_segment_list - List customer segments
• ol_segment_create - Create segment to group members by behavior or attributes
• ol_segment_get - Get full segment details including parts and criteria
• ol_segment_update - Update segment configuration
• ol_segment_delete - Permanently delete a segment
• ol_segment_get_members - Get members belonging to a segment
• ol_segment_activate - Activate a segment
• ol_segment_deactivate - Deactivate a segment
• ol_segment_get_resources - List resources associated with an existing segment

Achievements (7 tools)

• ol_achievement_list - List achievements
• ol_achievement_create - Create achievement for gamification
• ol_achievement_get - Get achievement details
• ol_achievement_update - Update achievement (full replacement)
• ol_achievement_patch - Patch achievement (active/displayOrder)
• ol_achievement_get_member_progress - Get member's progress on achievement
• ol_achievement_list_member_achievements - List member's achievements

Badges (4 tools)

• ol_badge_list - List badge types
• ol_badge_get - Get badge type details
• ol_badge_update - Update badge type configuration
• ol_badge_get_member_badges - Get badges earned by member

Analytics (9 tools)

• ol_analytics_tiers - Get tier distribution with member counts
• ol_analytics_members - Get member statistics (new, active, inactive)
• ol_analytics_points - Get points statistics (issued, spent, expired)
• ol_analytics_transactions - Get transaction statistics
• ol_analytics_referrals - Get referral program statistics
• ol_analytics_campaigns - Get campaign performance metrics
• ol_analytics_dashboard - Get dashboard overview metrics
• ol_analytics_units - Get wallet-specific metrics
• ol_analytics_campaign_detail - Get detailed campaign analytics

Audit Logs (2 tools)

• ol_audit_list - List audit log entries
• ol_audit_export - Export audit logs

Stores (6 tools)

• ol_store_list - List stores
• ol_store_create - Create store for multi-tenancy
• ol_store_get - Get store details
• ol_store_update - Update store configuration
• ol_store_get_settings - Get the loyalty program settings for the current store
• ol_store_update_settings - Update loyalty program settings (partial PATCH)

Webhooks (6 tools)

• ol_webhook_list - List webhook subscriptions
• ol_webhook_create - Create webhook subscription for event notifications
• ol_webhook_get - Get webhook subscription details
• ol_webhook_update - Update webhook subscription
• ol_webhook_delete - Delete webhook subscription
• ol_webhook_events - List available webhook event types

Import (3 tools)

• ol_import_create - Create bulk import from CSV
• ol_import_list - List imports with status
• ol_import_get - Get import details and item statuses

Export (4 tools)

• ol_export_create - Create data export (async)
• ol_export_list - List exports with status
• ol_export_get - Get export status and details
• ol_export_download - Download export CSV (when status='done')

Custom Events (7 tools)

• ol_custom_event_schema_create - Create a new custom event schema
• ol_custom_event_schema_list - List available custom event schemas
• ol_custom_event_schema_get - Get details of a custom event schema including its fields
• ol_custom_event_schema_update - Update an existing custom event schema
• ol_custom_event_schema_activate - Activate or deactivate a custom event schema
• ol_custom_event_send - Send a custom event for a member
• ol_custom_event_list - List custom events that have been sent

Referrals (3 tools)

• ol_referral_create - Create a referral relationship between members
• ol_referral_list - List referral relationships with optional filters
• ol_referral_delete - Delete a referral relationship for a member

Channels (5 tools)

• ol_channel_list - List sales channels (e.g. Mobile App, Point of Sale, Web)
• ol_channel_create - Create a new sales channel
• ol_channel_get - Get full details of a specific channel by channelId
• ol_channel_update - Update a channel's name, identifier, or description
• ol_channel_delete - Permanently delete a channel

Languages (5 tools)

• ol_language_list - List all configured languages
• ol_language_create - Add a new language to the platform
• ol_language_get - Get details of a specific language by its locale code
• ol_language_update - Update a language's name, sort order, or default status
• ol_language_delete - Delete a language

Group of Values (6 tools)

• ol_group_of_values_list - List all groups of values
• ol_group_of_values_create - Create a new group of values container
• ol_group_of_values_update - Update a group's name, description, or active status
• ol_group_value_add - Add an individual value to a group of values
• ol_group_value_update - Update an individual value's string or description
• ol_group_value_delete - Permanently delete an individual value from a group

Context (1 tool)

• ol_context_get - Get current store state (wallet types, tier sets, segments, campaigns, rewards) in one call

Interactive App Views (6 tools)

• ol_dashboard_app - Interactive loyalty program dashboard with tier, points, and campaign charts
• ol_member_profile_app - Interactive member profile card with tier badge and points balance
• ol_rewards_catalog_app - Interactive rewards catalog with category and affordability filtering
• ol_tier_visualizer_app - Interactive visualization of loyalty tier structures
• ol_transaction_timeline_app - Interactive timeline of a member's transactions and point movements
• ol_campaign_builder_app - Interactive multi-step wizard for creating loyalty campaigns

Example Workflows

1. Create 3-Tier Loyalty Program

ol_wallet_type_list
// Note: conditions use `attribute` (not `type`) and walletType expects the wallet CODE (e.g., "default"), not the UUID.
ol_tierset_create({ name: "VIP Program", conditions: [{ attribute: "activeUnits", walletType: "points" }] })
ol_tierset_get({ tierSetId: "..." })
ol_tierset_update_tiers({
  tierSetId: "...",
  tiers: [
    { name: "Bronze", conditions: [{ conditionId: "xxx", value: 400 }] },
    { name: "Silver", conditions: [{ conditionId: "xxx", value: 800 }] },
    { name: "Gold", conditions: [{ conditionId: "xxx", value: 1200 }] }
  ]
})

2. Full Member Lifecycle

// Register member
ol_member_create({ email: "[email protected]", firstName: "John", lastName: "Doe" })

// Add welcome bonus
ol_points_add({ memberId: "...", points: 100, comment: "Welcome bonus" })

// Record purchase (auto-earns points via campaigns)
ol_transaction_create({
  header: { documentNumber: "INV-001", purchasedAt: "2024-01-15T10:00:00Z" },
  items: [{ sku: "PROD-1", name: "Widget", grossValue: 99.99, category: "Electronics" }],
  customerData: { email: "[email protected]" }
})

// Check tier progress
ol_member_get_tier_progress({ memberId: "..." })

3. Reward Redemption Flow

// List available rewards
ol_reward_list({ active: true })

// Check member balance
ol_points_get_balance({ memberId: "..." })

// Purchase reward (deducts points, returns coupon code)
ol_reward_buy({ rewardId: "...", memberId: "..." })

// Later: mark coupon as used
ol_reward_redeem({ memberId: "...", couponCode: "COUP-ABC123" })

4. Assign Unmatched Transaction

// Find unmatched transactions
ol_transaction_list({ matched: false })

// Assign to member (triggers point campaigns)
ol_transaction_assign_member({ documentNumber: "INV-999", loyaltyCardNumber: "CARD-123" })

5. Create Double Points Campaign for Gold Tier

// First, find the Gold tier level ID
ol_tierset_get_tiers({ tierSetId: "..." })

// Create a segment targeting Gold tier members
ol_segment_create({
  name: "Gold Members",
  parts: [{
    criteria: [{
      type: "tier",
      tierIds: ["gold-level-id"]
    }]
  }]
})

// Create campaign with double points effect
ol_campaign_create({
  type: "direct",
  trigger: "transaction",
  translations: { en: { name: "Double Points for Gold", description: "Gold members earn 2x points" } },
  // Required: activity.startsAt, rules[].name. Use effects[].effect (not type). pointsRule is a STRING expression (not an object).
  activity: { startsAt: "2024-01-01T00:00:00Z" },
  rules: [{
    name: "Double points",
    effects: [{
      effect: "give_points",
      pointsRule: "transaction.grossValue * 2"
    }]
  }],
  audience: {
    target: "segment",
    segments: ["segment-id"]
  },
  active: true
})

// Test the campaign before it triggers
ol_campaign_simulate({
  trigger: "transaction",
  transaction: { grossValue: 100 },
  customer: { email: "[email protected]" }
})

6. Create VIP Segment Based on Transaction Count

// Create segment for members with 10+ transactions
ol_segment_create({
  name: "VIP Customers",
  description: "Members with 10 or more purchases",
  parts: [{
    criteria: [{
      type: "transaction_count",
      min: 10
    }]
  }],
  active: true
})

// Check segment membership
ol_segment_get_members({ segmentId: "..." })

// Use for campaign targeting
ol_campaign_create({
  type: "direct",
  trigger: "transaction",
  translations: { en: { name: "VIP Bonus" } },
  activity: { startsAt: "2024-01-01T00:00:00Z" },
  rules: [{
    name: "VIP Bonus Points",
    effects: [{ effect: "give_points", pointsRule: "50" }]
  }],
  audience: { target: "segment", segments: ["vip-segment-id"] },
  active: true
})

7. Create Purchase Achievement with Badge

// Create an achievement for making 5 purchases
ol_achievement_create({
  translations: { en: { name: "Frequent Shopper", description: "Make 5 purchases" } },
  rules: [{
    type: "direct",
    trigger: "transaction",
    aggregation: { type: "quantity" },
    completeRule: {
      periodGoal: 5,
      period: { type: "day", consecutive: 1 }
    }
  }],
  badgeTypeId: "shopper-badge-id",
  active: true
})

// Check member progress
ol_achievement_get_member_progress({ memberId: "...", achievementId: "..." })

// List all member achievements and badges
ol_achievement_list_member_achievements({ memberId: "..." })
ol_badge_get_member_badges({ memberId: "..." })

8. Segment Logic: OR vs AND

// Parts use OR logic - member matches if ANY part matches
// Criteria within parts use AND logic - must match ALL criteria in that part

// Example: (10+ transactions) OR (5-9 transactions)
ol_segment_create({
  name: "High Value Members",
  parts: [
    {
      // Part 1: Frequent shoppers
      criteria: [
        { type: "transaction_count", min: 10, max: 999999 }
      ]
    },
    {
      // Part 2: Moderately frequent shoppers (OR with Part 1)
      criteria: [
        { type: "transaction_count", min: 5, max: 9 }
      ]
    }
  ]
})

9. Analyze Program Performance

// Get high-level dashboard metrics
ol_analytics_dashboard()

// Analyze tier distribution
ol_analytics_tiers({ dateFrom: "2024-01-01", dateTo: "2024-12-31" })

// Check points economy
ol_analytics_points({ dateFrom: "2024-01-01", dateTo: "2024-12-31" })

// Analyze specific campaign
ol_analytics_campaign_detail({ campaignId: "campaign-uuid" })

// Get wallet-specific metrics
ol_analytics_units({ walletTypeCode: "points" })

10. Audit User Actions

// List recent audit entries
ol_audit_list({ perPage: 50 })

// Filter by specific user
ol_audit_list({ username: "[email protected]" })

// Filter by entity type and date range
ol_audit_list({
  entityType: "MEMBER",
  dateFrom: "2024-01-01",
  dateTo: "2024-01-31"
})

// Export audit logs for compliance
ol_audit_export({
  dateFrom: "2024-01-01",
  dateTo: "2024-12-31"
})

11. Multi-Tenant Store Setup

// Create a new store for a region
ol_store_create({
  code: "EU",
  name: "European Store",
  currency: "EUR",
  active: true
})

// List all stores
ol_store_list()

// Use storeCode in subsequent operations
ol_member_create({
  email: "[email protected]",
  firstName: "Jean",
  lastName: "Dupont",
  storeCode: "EU"
})

12. Subscribe to Member Events for CRM Sync

// Discover available event types
ol_webhook_events()

// Subscribe to member creation events
ol_webhook_create({
  eventName: "member.created",
  url: "https://crm.example.com/webhooks/loyalty",
  headers: [
    { headerName: "Authorization", headerValue: "Bearer crm-token" }
  ]
})

// List current subscriptions
ol_webhook_list()

// Update subscription URL
ol_webhook_update({
  webhookSubscriptionId: "...",
  url: "https://crm-v2.example.com/webhooks/loyalty"
})

13. Bulk Import Members from CSV

// Create import with CSV content
ol_import_create({
  type: "member",
  fileContent: "email,firstName,lastName\[email protected],John,Doe\[email protected],Jane,Smith",
  fileName: "members.csv"
})

// Poll import status
ol_import_list({ type: "member" })

// Check individual item statuses
ol_import_get({ importId: "..." })

14. Export Campaign Codes and Download

// Create export for campaign codes
ol_export_create({
  type: "campaignCode",
  filters: { campaignId: "campaign-uuid" }
})

// Poll until status is 'done'
ol_export_get({ exportId: "..." })

// Download the CSV file
ol_export_download({ exportId: "..." })

15. Bulk Add Points via Import

// Create import for adding points to multiple members
ol_import_create({
  type: "unitTransferAdding",
  fileContent: "loyaltyCardNumber,points,comment\nCARD-001,500,Promotion bonus\nCARD-002,500,Promotion bonus"
})

// Check import progress
ol_import_get({ importId: "..." })

Links

• GitHub: OpenLoyalty/openloyalty-mcp
• Open Loyalty: openloyalty.io
• MCP Protocol: modelcontextprotocol.io

License

MIT