Overview - LoyaltyLion

The LoyaltyLion MCP server lets AI assistants — such as Claude, Cursor, or any Model Context Protocol client — answer questions about your loyalty program using live data from your account. Connect it once and you can ask, in plain language, how your program is configured and how it’s performing.

Merchant MCP is available on the Classic plan and above.

What it can do

The MCP server exposes a small set of read-only tools:

Capability	What the assistant can do
Describe program setup	Read your program’s configuration — name, live status, sites, locales, points-expiry policy, earning rules, rewards, tiers, and referral incentive.
Analytics metrics	Pull time series for a single analytics metric — membership, points, orders, revenue, rewards, and customer lifetime value — over a date range, bucketed by day, week, or month, optionally filtered by site, rule, or reward.
Fetch customers	Look up loyalty customers by email, ID (`merchant_id`), or created/updated time range, with their points balances, enrollment state, tier, and tags.
Fetch orders	List orders by time range, order number, ID (`merchant_id`), or customer, with each order’s amounts, statuses, timestamps, points earned, and rewards used.

See Example prompts for things you can ask once it’s connected.

Endpoint

The MCP server is a streamable-HTTP endpoint served from the same host as the LoyaltyLion API:

POST https://api.loyaltylion.com/mcp

Authenticate with a Program API key (or OAuth token) passed as a Bearer token in the Authorization header. Site token & secret authentication is not accepted.

Install in Claude

If you use Claude — web, desktop, mobile, or Claude Code — install the LoyaltyLion connector from the Claude directory:

LoyaltyLion connector for Claude

Open the connector and click Connect, then sign in to LoyaltyLion to authorize access.

You don’t need an API key — the connector authorizes through your LoyaltyLion account. Claude Code picks it up too: any connector you add in Claude is automatically available in Claude Code when it’s signed in with the same claude.ai account, so there’s nothing to configure there either. Once it’s connected, Claude discovers the available tools automatically. Head to Example prompts to start asking questions.

Install in other MCP clients

Every other client connects to the endpoint directly with an API key. Create the key first, then configure your client. This is also the route for a Claude Code session that authenticates some other way — ANTHROPIC_API_KEY, Bedrock, or Vertex — since connector sync requires a claude.ai login.

1. Create an API key

Sign in to your LoyaltyLion account, go to Manage > API keys, click Create API key, and follow the steps. The token is shown only once after creation — store it somewhere secure. For more detail on API keys, see Authentication › API keys.

2. Choose scopes

The MCP server only ever reads data, and the tools available to a key depend on the scopes you grant it. Grant the read scopes that match the data you want the assistant to access:

Capability	Scope required
Describe program setup	None — any valid key works
Analytics metrics	None — any valid key works
Fetch customers	`read_customers`
Fetch orders	`read_orders`

Program setup and analytics don’t require a specific scope, so a key with no scopes can use them. To let the assistant look up customers or orders, grant read_customers and read_orders. For the full list of scopes, see the API key scopes reference.

3. Configure your client

Your API key is a long-lived credential. Keep it out of any config file that gets committed — read it from the environment, or from your client’s secret input, as the examples below do.

Each example expects the key in a LOYALTYLION_API_KEY environment variable, except VS Code, which prompts for it.

Claude Code
Cursor
VS Code
Other clients

Run the following from your terminal:

claude mcp add --transport http --scope user loyaltylion https://api.loyaltylion.com/mcp \
  --header 'Authorization: Bearer ${LOYALTYLION_API_KEY}'

The single quotes matter: they stop your shell expanding the variable, so the reference is stored in your config and resolved from the environment each time Claude Code starts. With double quotes you’d save the key itself into ~/.claude.json in plain text.--scope user makes the server available in every project. Drop it to install into the current project only. Check it connected with /mcp inside Claude Code.

Add the server to ~/.cursor/mcp.json, which applies to every project and lives outside any repo:

{
  "mcpServers": {
    "loyaltylion": {
      "url": "https://api.loyaltylion.com/mcp",
      "headers": {
        "Authorization": "Bearer ${env:LOYALTYLION_API_KEY}"
      }
    }
  }
}

A project-level .cursor/mcp.json works the same way, but it sits inside your repo — only use it with the environment reference above, never a hardcoded key.

Add the server to .vscode/mcp.json in your workspace. VS Code treats this file as shareable, so declare the key as a password input rather than inlining it — you’ll be prompted for it on first use and it’s stored in secret storage:

{
  "inputs": [
    {
      "id": "loyaltylion-api-key",
      "type": "promptString",
      "description": "LoyaltyLion API key",
      "password": true
    }
  ],
  "servers": {
    "loyaltylion": {
      "type": "http",
      "url": "https://api.loyaltylion.com/mcp",
      "headers": {
        "Authorization": "Bearer ${input:loyaltylion-api-key}"
      }
    }
  }
}

Most clients accept an HTTP server entry with an Authorization header:

{
  "mcpServers": {
    "loyaltylion": {
      "type": "http",
      "url": "https://api.loyaltylion.com/mcp",
      "headers": {
        "Authorization": "Bearer YOUR_API_KEY"
      }
    }
  }
}

The exact format varies — consult your client’s documentation for where MCP servers are configured, how to supply request headers, and how to reference a secret rather than pasting the key in.

Once connected, your client will discover the available tools automatically. Head to Example prompts to start asking questions.

Connect multiple loyalty programs

Every MCP connection is scoped to a single loyalty program: an API key belongs to one program, and an OAuth authorization covers the one program you choose on the consent screen. If you run more than one program, add one connection per program and give each a name that identifies it — your assistant surfaces the tools of each connection under its name, so that’s how you (and it) tell them apart.

Add extra programs in Claude

The connector from the directory can only be connected once, so it covers your first program. For each additional program, add a custom connector pointing at the same endpoint with a query string on the end:

https://api.loyaltylion.com/mcp?program=uk-store

The query string exists only to make the URL unique — Claude identifies connectors by URL, so a second connector needs a URL that differs from the first. The MCP server ignores it entirely and resolves the program from the credentials the connector authorizes with, so the value is yours to choose; something recognizable like your store name keeps things clear.

Open the custom connector dialog

In Claude, go to Settings > Connectors, then click Add custom connector.

Name it after the program

Use a name that makes the program obvious, such as LoyaltyLion (UK store). Claude shows this name alongside the connector’s tools, and it’s what you’ll refer to when you want a question answered from that program.

Enter the URL with a distinct query string

Use https://api.loyaltylion.com/mcp?program=uk-store, replacing uk-store with your own label. Each connector needs a different value here.

Connect and pick the program

Click Connect and sign in to LoyaltyLion. If your LoyaltyLion account has more than one program, you’ll be asked which program to authorize — choose the one this connector is for.

Repeat for each additional program. Once they’re all connected, mention the program in your prompt — “compare points issued last month for the UK store and the US store” — and Claude will call the matching connector for each.

Programs that live in separate LoyaltyLion accounts need a separate LoyaltyLion login each, so you can only authorize them from Claude one account at a time. If that’s your setup, use API keys in a client that supports them instead.

Add extra programs in other MCP clients

Clients configured from a file already namespace each server by the name you give it, so no query string is needed — add one entry per program, each with its own name and its own API key. Create the key from within each program: switch program in LoyaltyLion, then go to Manage > API keys.

Claude Code
Cursor
VS Code

claude mcp add --transport http --scope user loyaltylion-uk https://api.loyaltylion.com/mcp \
  --header 'Authorization: Bearer ${LOYALTYLION_UK_API_KEY}'

claude mcp add --transport http --scope user loyaltylion-us https://api.loyaltylion.com/mcp \
  --header 'Authorization: Bearer ${LOYALTYLION_US_API_KEY}'

{
  "mcpServers": {
    "loyaltylion-uk": {
      "url": "https://api.loyaltylion.com/mcp",
      "headers": {
        "Authorization": "Bearer ${env:LOYALTYLION_UK_API_KEY}"
      }
    },
    "loyaltylion-us": {
      "url": "https://api.loyaltylion.com/mcp",
      "headers": {
        "Authorization": "Bearer ${env:LOYALTYLION_US_API_KEY}"
      }
    }
  }
}

One password input per program, so each key is prompted for separately and kept in secret storage:

{
  "inputs": [
    {
      "id": "loyaltylion-uk-api-key",
      "type": "promptString",
      "description": "LoyaltyLion API key (UK store)",
      "password": true
    },
    {
      "id": "loyaltylion-us-api-key",
      "type": "promptString",
      "description": "LoyaltyLion API key (US store)",
      "password": true
    }
  ],
  "servers": {
    "loyaltylion-uk": {
      "type": "http",
      "url": "https://api.loyaltylion.com/mcp",
      "headers": {
        "Authorization": "Bearer ${input:loyaltylion-uk-api-key}"
      }
    },
    "loyaltylion-us": {
      "type": "http",
      "url": "https://api.loyaltylion.com/mcp",
      "headers": {
        "Authorization": "Bearer ${input:loyaltylion-us-api-key}"
      }
    }
  }
}

Everything else — where each file lives, and how each client references a secret — is unchanged from Install in other MCP clients above. The only difference here is that there’s one entry, and one key, per program.

​What it can do

​Endpoint

​Install in Claude

LoyaltyLion connector for Claude

​Install in other MCP clients

​1. Create an API key

​2. Choose scopes

​3. Configure your client

​Connect multiple loyalty programs

​Add extra programs in Claude

​Add extra programs in other MCP clients

What it can do

Endpoint

Install in Claude

Install in other MCP clients

1. Create an API key

2. Choose scopes

3. Configure your client

Connect multiple loyalty programs

Add extra programs in Claude

Add extra programs in other MCP clients