> ## 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}"
    ```

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