Joy Loyalty MCP server
Joy Loyalty has an MCP server. MCP (Model Context Protocol) is the open standard that AI assistants use to connect to the tools you run your business on. Connect your assistant to Joy, then ask about your loyalty program in plain language. If you allow it, the assistant can also make changes for you.
The assistant works with live data from your store: members, points, VIP tiers, earning and redemption rules, referrals, coupons and analytics. It reads the same data your Joy admin shows.
Fastest way to connect: in Joy, go to Settings → Developers → AI connections, pick your AI tool, and copy the snippet. It's already filled in for your store.
Overview
What you can do
- Look things up. "How many points does [email protected] have?" · "Who is about to reach Gold?"
- Find out why. "Why didn't order #1234 earn points?" · "Is this member abusing referrals?"
- Measure. "How much revenue did loyalty drive last month vs last year?" · "What's my redemption rate?"
- Act, with your approval. Award or correct points, redeem rewards, move a member's tier, update your loyalty page.
Two ways to connect
| Sign in (recommended) | API key (local server) | |
|---|---|---|
| How it works | Add Joy's URL to your AI tool, then approve access in Joy | Your AI tool runs Joy's server on your computer with your API key |
| Setup | Paste one URL | Paste a config snippet and your key |
| Works with | Claude (web, desktop, mobile), ChatGPT, Claude Code, Cursor, Codex | Claude Desktop, Claude Code, Cursor, Codex, VS Code, and any MCP client that runs local servers |
| Your API key | Stays in Joy | Saved in a file on your computer |
| Access level | You choose Read-only or Full access when you approve | Read-only unless you turn on changes |
| Needs Node.js | No | Yes, version 20 or later |
| Turn it off | Disconnect in Joy | Remove the config entry, or regenerate the key in Joy |
Both reach the same Joy data with the same tools, with two exceptions:
settings changes are currently available on the local server only,
and on the local server the loyalty page and Redeem in Cart tools need @joy-loyalty/mcp
0.4.0 or later.
Before you start
A paid Joy plan. Every request the assistant makes goes through Joy's API, which is included with every paid plan. Your plan sets how many requests the assistant can make:
| Joy plan | AI connections | Request limit |
|---|---|---|
| Starter (free) | Not included | — |
| Professional / Essential | Included | 30 requests per 10 seconds, 200 per day |
| Advanced | Included | 60 requests per 10 seconds, 2,000 per day |
| Ultimate | Included | No daily limit (up to 120 requests per 10 seconds) |
One question can use several requests. Limits count every request to your store's Joy API, including other AI connections and integrations. Daily limits reset at 00:00 UTC.
On a free plan, the Joy approval screen blocks the connection and asks you to upgrade.
Access to the Joy app in Shopify. You approve the connection inside the Joy app in your store's Shopify admin. To see or disconnect connections later, you need Settings → Developers.
An AI account that allows custom connectors. Your AI tool's plan or workspace settings decide this. For example, Claude's free plan allows one custom connector, so connecting several stores needs a paid Claude plan.
For the local server only: Node.js (opens in a new tab) 20 or later on the computer running your AI tool, and your App ID and a key from Settings → Developers → Manage keys.