> For the complete documentation index, see [llms.txt](https://help.openloyalty.io/llms.txt). Markdown versions of documentation pages are available by appending `.md` to page URLs; this page is available as [Markdown](https://help.openloyalty.io/technical-guide/integration/mcp-server.md). # MCP Server 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 | {% hint style="info" %} 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. {% endhint %} ### 🧩 Prerequisites * Node.js 18 or later * An Open Loyalty account with API access * An API token and the API URL for your instance ### 🛠️ Installation {% tabs %} {% tab title="npx (recommended)" %} No install required. Your MCP client launches the server on demand: ```bash npx -y @open-loyalty/mcp-server ``` {% endtab %} {% tab title="Global install" %} ```bash npm install -g @open-loyalty/mcp-server openloyalty-mcp ``` {% endtab %} {% endtabs %} ### ⚙️ Configuration The server is configured entirely through environment variables.
VariableRequiredDescription
OPENLOYALTY_API_URLRequiredYour Open Loyalty API URL, e.g. https://api.openloyalty.io
OPENLOYALTY_API_TOKENRequiredAPI authentication token. Scopes everything the agent can reach.
OPENLOYALTY_DEFAULT_STORE_CODEOptionalDefault store code (e.g. default). Falls back to a per-call parameter.
{% hint style="info" %} For local development, copy `.env.example` to `.env` and fill in the values. Never commit a real token. {% endhint %} ### 🛠️ 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 {% tabs %} {% tab title="Claude Desktop" %} Add the server to your config file: * **macOS:** `~/Library/Application Support/Claude/claude_desktop_config.json` * **Windows:** `%APPDATA%\Claude\claude_desktop_config.json` {% code title="claude\_desktop\_config.json" %} ```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" } } } } ``` {% endcode %} {% endtab %} {% tab title="Claude Code / Cursor" %} Both clients read the same MCP server definition format. Register `openloyalty` with the same `command`, `args`, and `env` shown in the Claude Desktop tab. {% endtab %} {% endtabs %} ### 🛠️ 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:** {% stepper %} {% step %} #### Download the bundle Download the bundle from the unpkg CDN — this URL always serves the latest published version: {% endstep %} {% step %} #### Open in Claude Desktop Double-click the file, or drag it into Claude Desktop under **Settings > Extensions**, then click **Install**. {% endstep %} {% step %} #### 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. {% endstep %} {% endstepper %} ### 🛠️ 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 `` 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." {% hint style="warning" %} **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. {% endhint %} ### 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` | 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) | 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](https://www.npmjs.com/package/@open-loyalty/mcp-server) * Open Loyalty: [openloyalty.io](https://openloyalty.io) * MCP protocol: [modelcontextprotocol.io](https://modelcontextprotocol.io) --- # Agent Instructions This documentation is published with GitBook. GitBook is the documentation platform designed so that both humans and AI agents can read, navigate, and reason over technical content effectively. Learn more at gitbook.com. ## Querying This Documentation If you need additional information that is not directly available in this page, you can query the documentation dynamically by asking a question. Perform an HTTP GET request on the current page URL with the `ask` query parameter, and the optional `goal` query parameter: ``` GET https://help.openloyalty.io/technical-guide/integration/mcp-server.md?ask=&goal= ``` `ask` is the immediate question: it should be specific, self-contained, and written in natural language. `goal` is optional and describes the broader end goal you are ultimately trying to accomplish on behalf of the user. GitBook uses it to tailor the answer towards what is most useful for that goal. The response will contain a direct answer to the question and relevant excerpts and sources from the documentation. Use this mechanism when the answer is not explicitly present in the current page, you need clarification or additional context, or you want to retrieve related documentation sections.