MCP Server

Install, configure, and use the Open Loyalty MCP Server to let AI agents manage your loyalty program via Claude, Cursor, and other MCP-compatible clients.

The @open-loyalty/mcp-server package exposes the Open Loyalty API as a set of MCP (Model Context Protocol) tools. Any MCP-compatible client — Claude Desktop, Claude Code, Cursor, Claude Cowork — can discover and call those tools on your behalf.

Because Open Loyalty is API-first, the server covers the full platform: members, points, tiers, rewards, transactions, campaigns, segments, achievements, badges, analytics, and the admin surface. Tool inputs are validated with Zod schemas, and errors return AI-actionable hints so the agent can self-correct without a human round-trip.

Package

@open-loyalty/mcp-server

Tools

145 tools across 22 domains

Transport

stdio

Runtime

Node.js 18+

License

MIT

The MCP Server is a developer tool. It connects directly to your Open Loyalty API — treat the API token with the same care as an admin password.

🧩 Prerequisites

Node.js 18 or later
An Open Loyalty account with API access
An API token and the API URL for your instance

🛠️ Installation

No install required. Your MCP client launches the server on demand:

npx -y @open-loyalty/mcp-server

⚙️ Configuration

The server is configured entirely through environment variables.

Variable

Required

Description

OPENLOYALTY_API_URL

Required

Your Open Loyalty API URL, e.g. https://api.openloyalty.io

OPENLOYALTY_API_TOKEN

Required

API authentication token. Scopes everything the agent can reach.

OPENLOYALTY_DEFAULT_STORE_CODE

Optional

Default store code (e.g. default). Falls back to a per-call parameter.

For local development, copy .env.example to .env and fill in the values. Never commit a real token.

🛠️ Transport: stdio

The server communicates over stdio, the standard MCP transport for local desktop clients. The binary is openloyalty-mcp. The client launches the server process and talks to it over standard input and output — there is nothing to host or deploy.

🛠️ Client Setup

Add the server to your config file:

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

claude_desktop_config.json

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

🛠️ Claude Cowork and One-Click Install (.mcpb)

Claude Cowork is Anthropic's agent for everyday knowledge work inside the Claude desktop app. Instead of chatting prompt by prompt, you describe an outcome and Cowork plans and runs the steps across your files and connected tools. It reads the same Open Loyalty MCP tools as Claude Code, but the people using it rarely need to hand-edit a JSON config.

For that audience, the server can be shipped as an MCP Bundle — a single .mcpb file. A bundle packages the server, its dependencies, and a manifest.json describing the configuration it needs. Claude Desktop installs it in one click: no Node.js to install, no terminal, no config file to edit. Anything installed into Claude Desktop this way is automatically available to Cowork.

To install from a bundle:

Download the bundle

Download the bundle from the unpkg CDN — this URL always serves the latest published version:

https://unpkg.com/@open-loyalty/mcp-server/openloyalty-mcp.mcpb

Open in Claude Desktop

Double-click the file, or drag it into Claude Desktop under Settings > Extensions, then click Install.

Enter your credentials

When prompted, paste your API URL and API token, plus an optional default store code. Claude stores them and wires up the server automatically.

🛠️ Quick Start

Once the server is registered and your client restarted, confirm the connection by asking the agent to list members or fetch program analytics. The agent will discover the tools automatically and call them against your instance.

Example prompts to try:

"List the top 10 members by points balance in the default store."
"Create a campaign that grants double points to the lapsed-60-days segment this weekend, then show it to me before activating."
"Add 500 points to member <id> and read back the new wallet balance."
"Which tier has the lowest retention this quarter? Use program analytics."
"Build a segment of members with no purchase in 60 days and tell me how many qualify."

Human in the loop. Treat write actions (create, spend, publish) as proposals. Review the agent's plan before it commits changes to a live program.

Tool reference

145 tools across 22 domains. Names and descriptions match v1.20.0.

Wallet types (4)

Tool

Description

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)

Tool

Description

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)

Tool

Description

ol_member_create

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)

Tool

Description

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)

Tool

Description

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)

Tool

Description

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)

Tool

Description

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)

Tool

Description

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)

Tool

Description

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)

Tool

Description

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)

Tool

Description

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)

Tool

Description

ol_audit_list

List audit log entries

ol_audit_export

Export audit logs

Stores (6)

Tool

Description

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)

Tool

Description

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)

Tool

Description

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)

Tool

Description

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)

Tool

Description

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)

Tool

Description

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

Languages (5)

Tool

Description

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

Channels (5)

Tool

Description

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

Group of values (6)

Tool

Description

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

Description

ol_context_get

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

Interactive app views (6)

Tool

Description

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

⚙️ Error Handling

Tool inputs are validated with Zod schemas before any API call. When a call fails, the server returns an actionable error message rather than a raw stack trace, so the agent can correct the request (for example, a missing store code or an invalid member ID) and retry automatically.

🛠️ Troubleshooting

Symptom

Fix

Tools do not appear

Restart the MCP client after editing its config. Confirm the JSON is valid.

401 / 403 responses

Check OPENLOYALTY_API_TOKEN and confirm the token has the required scope.

Wrong or empty data

Verify OPENLOYALTY_API_URL points at the right instance and OPENLOYALTY_DEFAULT_STORE_CODE is set or passed per call.

Node errors on launch

Ensure Node.js 18 or later is on the PATH that the MCP client uses.

🧩 Links

npm package: @open-loyalty/mcp-server
Open Loyalty: openloyalty.io
MCP protocol: modelcontextprotocol.io

Last updated 22 days ago

Was this helpful?