Connect with sign-in

Quickstart

Nothing to install. Your MCP server URL is:

https://mcp.joy.so/mcp

You'll also find it in Settings → Developers → AI connections.

1. Add the URL to your AI tool. Follow the steps for your tool below.

2. Enter your store. Your AI tool opens a Joy page. Enter your Shopify store domain, for example your-store.myshopify.com, and select Continue.

3. Approve access. Joy opens in your Shopify admin. Choose an access level, then select Allow access:

   • Read-only — the assistant can view your loyalty data but can never change it.
   • Full access — the assistant can also adjust members' points, move members between tiers, redeem or refund rewards, and edit your loyalty page.

   Keep Remember this and skip this screen next time ticked. That's what lists the connection under AI connections, so you can disconnect it later.

   If you chose Full access, this screen can appear again when your AI tool reconnects, with Read-only selected. Pick Full access again, or the connection becomes read-only.

4. Ask your first question. Try "How is my loyalty program set up?"

You don't need to create an API key first. Joy sets up the key the connection needs when you approve it.

Set up your AI tool

Claude (web, desktop and mobile)

1. In Claude, open Customize → Connectors, select +, then Add custom connector.
2. Name it Joy Loyalty, paste https://mcp.joy.so/mcp as the server URL, and select Continue.
3. Keep the detected settings and select Continue. Under Authentication, choose Sign in now, then select Add.
4. Approve access on the Joy page that opens.
5. In a chat, open + → Connectors and make sure Joy Loyalty is turned on.

Connectors are saved to your Claude account, so Joy also works in Claude Desktop and the mobile app. On a Team or Enterprise plan, an owner adds the connector in Organization settings → Connectors, then each member selects Connect.

ChatGPT

1. In ChatGPT, open Plugins, select +, then Add custom MCP server.
2. Name it Joy Loyalty and paste https://mcp.joy.so/mcp as the MCP server URL.
3. Set authentication to OAuth, select I understand and want to continue, then select Create as a plugin.
4. Install the plugin. When ChatGPT asks you to sign in, approve access on the Joy page that opens.
5. Start a new chat, type @ and pick Joy Loyalty.

Claude Code

claude mcp add --transport http joy-loyalty "https://mcp.joy.so/mcp"

Then type /mcp in Claude Code, pick joy-loyalty, and approve access in Joy. Add --scope user to make Joy available in every project.

Cursor

Add this to ~/.cursor/mcp.json (all projects) or .cursor/mcp.json (one project):

{
  "mcpServers": {
    "joy-loyalty": {
      "url": "https://mcp.joy.so/mcp"
    }
  }
}

When Cursor asks you to sign in, approve access in Joy.

Codex

codex mcp add joy-loyalty --url "https://mcp.joy.so/mcp"
codex mcp login joy-loyalty

The second command opens Joy in your browser so you can approve access. The Codex CLI, IDE extension and desktop app share this setup. In the app or extension, select Authenticate if Codex asks you to sign in.

Other MCP clients

Add https://mcp.joy.so/mcp as a remote (HTTP) MCP server and approve access in Joy.

If your tool can't complete the sign-in, use an API key instead. This applies to VS Code / GitHub Copilot today.

Connect more than one store

Each connection belongs to one store. To use several stores from the same AI tool, add one connection per store.

With sign-in

Add one connector per store, and add ?store= with that store's domain to each URL:

• On the Joy page that opens, enter the store domain from that connector's URL, then approve in that store's admin. If the store you approve doesn't match the URL, the connector fails to connect and you need to add it again.
• Add ?store= to every Joy connector from the start, including the first one.
• Why it matters: AI tools don't allow two connectors with the same URL, and with ?store= Joy checks the store on every change: if the store the assistant names doesn't match the connector, the change is refused. Name the store in each request, and check it before you approve.

For command-line tools, give each store its own server name:

claude mcp add --transport http joy-store-a "https://mcp.joy.so/mcp?store=store-a.myshopify.com"
claude mcp add --transport http joy-store-b "https://mcp.joy.so/mcp?store=store-b.myshopify.com"

Keep the quotes: some terminals (zsh, the macOS default) treat ? as a special character.

In each store's admin, Settings → Developers → AI connections → I'm connecting more than one store gives you that store's exact URL and name.

With API keys

Add one entry per store, each with that store's App ID and key:

{
  "mcpServers": {
    "joy-store-a": {
      "command": "npx",
      "args": ["-y", "@joy-loyalty/mcp"],
      "env": {"JOY_APP_KEY": "STORE_A_APP_ID", "JOY_SECRET_KEY": "STORE_A_READ_ONLY_KEY"}
    },
    "joy-store-b": {
      "command": "npx",
      "args": ["-y", "@joy-loyalty/mcp"],
      "env": {"JOY_APP_KEY": "STORE_B_APP_ID", "JOY_SECRET_KEY": "STORE_B_READ_ONLY_KEY"}
    }
  }
}