loyaltydog-mcp

MCP server for the LoyaltyDog loyalty, wallet pass, and gift card API. It speaks the Model Context Protocol over stdio, so Claude, Cursor, and any other MCP client can list programs, look up customers, and — when you allow it — issue gift cards or update records through a bearer API key.

The server is a thin client of the public REST API. It does not talk to a database. Tool calls send Authorization: Bearer <your key> to https://api.loyalty.dog/v2.

Documentation: https://docs.loyalty.dog/mcp/overview

Requirements

• Python 3.10 or newer. uv is the easiest way to run the server without a manual install.
• A LoyaltyDog API key from your dashboard. Live keys look like ld_live_... and test keys look like ld_test_....
• An account on a plan that includes API access. Plans are listed at https://loyaltydog.ai/pricing/.

Quick start

Run without installing, using uv:

uvx loyaltydog-mcp

Or with pipx:

pipx run loyaltydog-mcp

Or install into the current environment:

pip install loyaltydog-mcp
loyaltydog-mcp

The process speaks MCP on stdin/stdout and waits for a client. Configure the client with your API key as shown below. loyaltydog-mcp --version prints the installed version and exits.

Configuration

Set variables in the MCP client's env block. The installed command does not read a .env file from the working directory.

Variable	Required	Description
LOYALTYDOG_API_KEY	Yes	Bearer API key (ld_live_... or ld_test_...).
LOYALTYDOG_API_URL	No	API base URL. Default https://api.loyalty.dog/v2. A trailing slash is stripped.
LOYALTYDOG_API_TOKEN	No	Legacy alias for the API key. Used only when LOYALTYDOG_API_KEY is unset. If both are set, LOYALTYDOG_API_KEY wins.

The server starts and lists its tools even when the key is missing. The first tool call then returns an error telling you to set LOYALTYDOG_API_KEY. The key is sent only as the bearer token and is never logged.

Client setup

Use a placeholder here, then replace it with your own key. Prefer an ld_test_... key until you trust the assistant with live data.

Claude Desktop

Add this to claude_desktop_config.json (~/Library/Application Support/Claude/claude_desktop_config.json on macOS, %APPDATA%\Claude\claude_desktop_config.json on Windows):

{
  "mcpServers": {
    "loyaltydog": {
      "command": "uvx",
      "args": ["loyaltydog-mcp"],
      "env": {
        "LOYALTYDOG_API_KEY": "ld_live_your_key_here"
      }
    }
  }
}

Claude Code

claude mcp add loyaltydog --env LOYALTYDOG_API_KEY=ld_live_xxx -- uvx loyaltydog-mcp

Cursor

Add this to ~/.cursor/mcp.json:

{
  "mcpServers": {
    "loyaltydog": {
      "command": "uvx",
      "args": ["loyaltydog-mcp"],
      "env": {
        "LOYALTYDOG_API_KEY": "ld_live_your_key_here"
      }
    }
  }
}

Generic MCP client

Any client that launches a stdio server can use the same shape:

{
  "command": "uvx",
  "args": ["loyaltydog-mcp"],
  "env": {
    "LOYALTYDOG_API_KEY": "ld_live_your_key_here",
    "LOYALTYDOG_API_URL": "https://api.loyalty.dog/v2"
  }
}

pipx run loyaltydog-mcp or an installed loyaltydog-mcp work as the command in place of uvx.

Tools

The server exposes 17 tools.

Read

Tool	What it does
list_programs	List loyalty programs with names and IDs.
get_program	Program details. Requires program_id.
search_customers	Search customers in a program by email or name. Requires program_id.
get_customer	One customer's details and points. Requires program_id and customer_id.
get_customer_transactions	Points history. Requires program_id and customer_id. Optional limit (default 20), start, end.
list_passes	Wallet passes visible to the authenticated merchant.
get_pass	Passes for a pass type identifier (pass_id).
list_gift_cards	Gift cards for a program. Requires program_id. Optional status, positive_balance.
get_gift_card	One gift card. Requires program_id and card_id.
get_gift_card_transactions	Gift card ledger. Requires program_id and card_id. Optional limit (default 20).
get_gift_card_business_report	Read-only gift card totals for a program. Requires program_id.
get_system_health	API health and version.

Writes

These five tools change data. There is no undo inside the server.

Tool	Effect
issue_gift_card	Mutating. Issues a new gift card with real value. Requires program_id, merchant_id, and initial_value (0.01–10000, no default).
redeem_gift_card	Mutating. Spends value from a gift card. Requires program_id, card_id, and amount (at least 0.01, no default).
update_customer	Mutating. Updates a customer, including PII. If points is set, it overwrites the balance. Requires program_id, customer_id, and at least one field.
update_program	Mutating. Updates program-wide settings that apply to every customer. Requires program_id and at least one field.
regenerate_pass	Mutating, low risk. Pushes a wallet pass update so the device re-fetches it. Does not change balances, points, or customer data. Requires pass_type_identifier and serial_number.

Safety. Use an ld_test_... key while you are trying the server out. In your MCP client, approve each tool call yourself instead of granting blanket permission, especially for the five tools above. Amounts are required and have no default. The server checks that they are positive before it calls the API.

Troubleshooting

uvx is not found. Install uv, then open a new terminal:

curl -LsSf https://astral.sh/uv/install.sh | sh

See https://docs.astral.sh/uv/getting-started/installation/ if you would rather use a package manager.

Tool calls say LOYALTYDOG_API_KEY is not set. Create a key in the LoyaltyDog dashboard and set LOYALTYDOG_API_KEY in the MCP client config (the env block above). A key exported only in some other shell, or written only in a .env file, is not visible to the server. LOYALTYDOG_API_TOKEN still works as a legacy name.

401 or 403 from a tool. The key is present but was rejected. Confirm it is an ld_live_... or ld_test_... key for the right account, and that the account's plan includes API access (https://loyaltydog.ai/pricing/).

Development

From a checkout of this package:

pip install -e ".[test]"
pytest

Tests use a dummy key and mock HTTP. They do not call the live API.

License

MIT. Copyright (c) 2026 LoyaltyDog.

• Homepage: https://loyaltydog.ai
• Documentation: https://docs.loyalty.dog/mcp/overview