Joy Loyalty MCP Server

Connect Claude, Cursor, or any MCP-compatible AI client to your Joy Loyalty program. Ask questions and manage loyalty data in natural language — no code required.

Quick start

1. Get your API key

In your Joy admin, go to Settings → Manage keys:

• Recommended: click "Generate read-only key" (a ro_... key). This is the safest option — it can read your loyalty data but can never award, deduct, or change points, even if the key is ever exposed.
• Only use your full Secret key if you need write access (awarding points, adjusting balances, etc.).

2. Add the server to your AI client

For Claude Desktop, edit your config file:

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

{
  "mcpServers": {
    "joy-loyalty": {
      "command": "npx",
      "args": ["-y", "@joy-loyalty-1/mcp-server"],
      "env": {
        "JOY_APP_KEY": "<your-shop-id>",
        "JOY_SECRET_KEY": "<your-key-from-step-1>"
      }
    }
  }
}

No install required — npx downloads and runs the latest version automatically. Node.js 20 or later must be installed on your machine.

3. Restart your AI client and try asking: "How is my loyalty program set up?"

Enabling write access (optional)

By default, the server is read-only — even if you provide your full secret key. To allow the assistant to award points, adjust balances, or make other changes, you must explicitly opt in:

"env": {
  "JOY_APP_KEY": "<your-shop-id>",
  "JOY_SECRET_KEY": "<your-full-secret-key>",
  "JOY_MCP_ENABLE_WRITES": "true"
}

⚠️ "true" must be quoted — it's a text value, not a JSON boolean. Writing true without quotes will cause your AI client to reject the whole configuration with an error like "not a valid MCP server configuration".

Your Joy plan must be Advanced or higher to use the API.

Environment variables

| Variable | Required | Description | |---|---|---| | JOY_APP_KEY | Yes | Your shop ID | | JOY_SECRET_KEY | Yes (one of these two) | Your API key — a read-only (ro_...) or full secret key from Settings → Manage keys | | JOY_MCP_ENABLE_WRITES | No | Set to "true" (quoted) to allow point/data changes. Requires a full secret key — read-only keys can never write regardless of this setting | | JOY_API_BASE_URL | No | Defaults to production. Only change this if instructed by Joy support |

What it can do

Always available (read-only):

• Look up a member's points, tier, and profile
• List members and browse their point/reward/referral history
• View your shop's tiers, earning rules, and redemption rules
• View referral program performance

With write access enabled:

• Award or deduct points, with a mandatory reason recorded for every change
• Adjust a member's balance (always previews the change before applying it)
• Redeem points for a reward, refund a redeemed coupon, or change a member's tier
• Generate a referral invite link

Every point-changing action requires a stated reason and is recorded in your Joy activity log for audit purposes.

Security

• The server only talks to Joy's official API — it never sends your data anywhere else.
• Your API key is only sent to Joy's servers, over HTTPS.
• Read-only keys cannot perform any write operation, even if explicitly requested.
• Destructive actions (deducting points, refunds, tier changes) require your AI client's own confirmation step before running.

Support

Questions or issues: contact Joy support through your admin dashboard, or visit joy.so.