> ## Documentation Index
> Fetch the complete documentation index at: https://developers.loyaltylion.com/llms.txt
> Use this file to discover all available pages before exploring further.

# Overview

The LoyaltyLion MCP server lets AI assistants — such as Claude, Cursor, or any
[Model Context Protocol](https://modelcontextprotocol.io) 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.

<Note>Merchant MCP is available on the **Classic plan and above**.</Note>

## 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](/docs/mcp/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:

<Card title="LoyaltyLion connector for Claude" icon="plug" href="https://claude.ai/directory/connectors/loyaltylion">
  Open the connector and click **Connect**, then sign in to LoyaltyLion to
  authorize access.
</Card>

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](https://code.claude.com/docs/en/mcp#use-mcp-servers-from-claudeai)
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](/docs/mcp/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](/api-reference/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](/api-reference/authentication/api-keys#api-key-scopes)
reference.

### 3. Configure your client

<Warning>
  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.
</Warning>

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

<Tabs>
  <Tab title="Claude Code">
    Run the following from your terminal:

    ```bash theme={null}
    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.
  </Tab>

  <Tab title="Cursor">
    Add the server to `~/.cursor/mcp.json`, which applies to every project and
    lives outside any repo:

    ```json theme={null}
    {
      "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.
  </Tab>

  <Tab title="VS Code">
    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:

    ```json theme={null}
    {
      "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}"
          }
        }
      }
    }
    ```
  </Tab>

  <Tab title="Other clients">
    Most clients accept an HTTP server entry with an `Authorization` header:

    ```json theme={null}
    {
      "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.
  </Tab>
</Tabs>

Once connected, your client will discover the available tools automatically.
Head to [Example prompts](/docs/mcp/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.

<Steps>
  <Step title="Open the custom connector dialog">
    In Claude, go to `Settings > Connectors`, then click `Add custom connector`.
  </Step>

  <Step title="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.
  </Step>

  <Step title="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.
  </Step>

  <Step title="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.
  </Step>
</Steps>

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.

<Note>
  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.
</Note>

### 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`.

<Tabs>
  <Tab title="Claude Code">
    ```bash theme={null}
    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}'
    ```
  </Tab>

  <Tab title="Cursor">
    ```json theme={null}
    {
      "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}"
          }
        }
      }
    }
    ```
  </Tab>

  <Tab title="VS Code">
    One password input per program, so each key is prompted for separately and
    kept in secret storage:

    ```json theme={null}
    {
      "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}"
          }
        }
      }
    }
    ```
  </Tab>
</Tabs>

Everything else — where each file lives, and how each client references a
secret — is unchanged from
[Install in other MCP clients](#install-in-other-mcp-clients) above. The only
difference here is that there's one entry, and one key, per program.