Connect with an API key

Joy publishes its MCP server as an npm package, @joy-loyalty/mcp (opens in a new tab). Your AI tool starts it on your computer with your API key. Choose this when:

• your AI tool can't use sign-in (for example VS Code / GitHub Copilot)
• you're a developer and want Joy in your own scripts or agents
• you want to turn on settings changes

Get your keys

In Joy, go to Settings → Developers → Manage keys:

• App ID — goes into JOY_APP_KEY.
• Read-only key (starts with ro_) — select Generate read-only key. Recommended: it can never change anything, even if it leaks.
• Secret key — use it only if the assistant needs to make changes.

In the snippets below, replace YOUR_APP_ID and YOUR_READ_ONLY_KEY (or YOUR_SECRET_KEY) with your values. Settings → Developers → AI connections → API key shows the same snippets with your App ID already filled in.

Claude Desktop

Open Settings → Developer → Edit Config and add Joy to claude_desktop_config.json:

{
  "mcpServers": {
    "joy-loyalty": {
      "command": "npx",
      "args": ["-y", "@joy-loyalty/mcp"],
      "env": {
        "JOY_APP_KEY": "YOUR_APP_ID",
        "JOY_SECRET_KEY": "YOUR_READ_ONLY_KEY"
      }
    }
  }
}

If the file already has an mcpServers block, add only the joy-loyalty entry. Save, then fully quit and reopen Claude Desktop.

Claude Code

claude mcp add --env JOY_APP_KEY=YOUR_APP_ID --env JOY_SECRET_KEY=YOUR_READ_ONLY_KEY --transport stdio joy-loyalty -- npx -y @joy-loyalty/mcp

Keep --transport stdio between the last --env and the server name. Otherwise Claude Code reads the name as another variable.

Cursor

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

{
  "mcpServers": {
    "joy-loyalty": {
      "command": "npx",
      "args": ["-y", "@joy-loyalty/mcp"],
      "env": {
        "JOY_APP_KEY": "YOUR_APP_ID",
        "JOY_SECRET_KEY": "YOUR_READ_ONLY_KEY"
      }
    }
  }
}

Codex

codex mcp add joy-loyalty --env JOY_APP_KEY=YOUR_APP_ID --env JOY_SECRET_KEY=YOUR_READ_ONLY_KEY -- npx -y @joy-loyalty/mcp

Or add it to ~/.codex/config.toml:

[mcp_servers.joy-loyalty]
command = "npx"
args = ["-y", "@joy-loyalty/mcp"]
 
[mcp_servers.joy-loyalty.env]
JOY_APP_KEY = "YOUR_APP_ID"
JOY_SECRET_KEY = "YOUR_READ_ONLY_KEY"

VS Code and GitHub Copilot

Add this to .vscode/mcp.json:

{
  "servers": {
    "joy-loyalty": {
      "type": "stdio",
      "command": "npx",
      "args": ["-y", "@joy-loyalty/mcp"],
      "env": {
        "JOY_APP_KEY": "YOUR_APP_ID",
        "JOY_SECRET_KEY": "YOUR_READ_ONLY_KEY"
      }
    }
  }
}

Other MCP clients

Run npx -y @joy-loyalty/mcp as a local (stdio) server and set the environment variables below. Where the config goes depends on your client — check its docs.

Environment variables

Allow changes

The local server is read-only by default, even with your secret key. To let the assistant make changes, use your secret key and opt in:

"env": {
  "JOY_APP_KEY": "YOUR_APP_ID",
  "JOY_SECRET_KEY": "YOUR_SECRET_KEY",
  "JOY_MCP_ENABLE_WRITES": "true"
}

A read-only key can never make changes, whatever these settings say.

Allow settings changes

Settings changes let the assistant create and edit earning rules, rewards, VIP tiers, referral rewards, widget design and a few shop settings. Turn them on only when you want the assistant to help you set up or redesign your program:

"env": {
  "JOY_APP_KEY": "YOUR_APP_ID",
  "JOY_SECRET_KEY": "YOUR_SECRET_KEY",
  "JOY_MCP_ENABLE_WRITES": "true",
  "JOY_MCP_ENABLE_CONFIG_WRITES": "true"
}

Settings changes are built to preview first: the assistant shows what will change and has to call again to apply it. Joy doesn't record settings changes in your activity log. Settings changes are currently available on the local server only.

Keep your key safe

• Config files store your key as plain text. Treat the file like a password and keep it out of shared repositories.
• Use the read-only key unless you need changes. If it leaks, it can't change a single point, but it can still read your member data, so keep it private.
• To stop a local setup, select Revoke and regenerate next to that key in Manage keys. Anything using the old key stops working right away.