> For the complete documentation index, see [llms.txt](https://docs.boomerangme.cards/llms.txt). Markdown versions of documentation pages are available by appending `.md` to page URLs; this page is available as [Markdown](https://docs.boomerangme.cards/api/mcp.md).

# MCP

## Connecting the Boomerang MCP Server

The **Boomerang MCP server** lets your AI assistant talk to your Boomerang account directly.

Once connected, you can manage customers, loyalty cards, card templates, balances, and automation workflows by simply asking — in Claude, Cursor, VS Code, or any other MCP-compatible client.

It speaks the [Model Context Protocol](https://modelcontextprotocol.io) over **Streamable HTTP** and authenticates with your personal **API key**.

{% hint style="info" %}
**What you can do once connected**

* **Customers** — create, find, update, and delete customers.
* **Templates** — create loyalty card templates and add reward tiers.
* **Cards** — issue cards, look them up, update fields, and set expiration and tiers.
* **Balances** — add or subtract stamps, points, scores, visits, amounts, rewards, and purchases.
* **Workflows** — build, activate, pause, and inspect automation workflows.
* **Agencies** — search sub-accounts and act on their behalf on Agency plans.
  {% endhint %}

### Connection details

| Property           | Value                                  |
| ------------------ | -------------------------------------- |
| **Server URL**     | `https://api.digitalwallet.cards/mcp`  |
| **Transport**      | Streamable HTTP                        |
| **Authentication** | `Authorization: Bearer <YOUR_API_KEY>` |
| **Method**         | `POST`                                 |

### Before you start

* A Boomerang account on a plan that **includes API access**.
* An MCP-compatible client such as Claude Desktop, Claude Code, Cursor, or VS Code.
* For **Claude Desktop** and **Claude.ai**, [Node.js](https://nodejs.org) installed so you can run `npx`.

### Step-by-step guide

{% stepper %}
{% step %}

#### Get your API key

1. Log in to your **Boomerang dashboard**.
2. Open **Settings → API**.
3. Copy your personal **API key**.

{% hint style="warning" %}
Your API key grants **full access to your account**.

Treat it like a password. Never share it. Never commit it to a public repository. Rotate it immediately if it leaks.
{% endhint %}
{% endstep %}

{% step %}

#### Add the server to your AI assistant

Pick your client below and add the configuration.

Replace `<YOUR_API_KEY>` with the key from the previous step.

{% tabs %}
{% tab title="Claude Code" %}
Run this command in your terminal:

```bash
claude mcp add --transport http boomerang https://api.digitalwallet.cards/mcp \
  --header "Authorization: Bearer <YOUR_API_KEY>"
```

Verify it with `claude mcp list`.
{% endtab %}

{% tab title="Claude Desktop" %}
Claude Desktop does not yet accept a custom `Authorization` header in the connector UI.

Use the `mcp-remote` proxy instead.

Open **Settings → Developer → Edit Config** and add:

```json
{
  "mcpServers": {
    "boomerang": {
      "command": "npx",
      "args": [
        "-y",
        "mcp-remote",
        "https://api.digitalwallet.cards/mcp",
        "--header",
        "Authorization: Bearer <YOUR_API_KEY>"
      ]
    }
  }
}
```

Then **fully quit and reopen Claude Desktop**.

The Boomerangme tools appear in the tools menu.
{% endtab %}

{% tab title="Cursor" %}
Open or create `~/.cursor/mcp.json` for a global setup, or `.cursor/mcp.json` inside a project, and add:

```json
{
  "mcpServers": {
    "boomerang": {
      "url": "https://api.digitalwallet.cards/mcp",
      "headers": {
        "Authorization": "Bearer <YOUR_API_KEY>"
      }
    }
  }
}
```

Then **restart Cursor**.

The server appears under **Settings → MCP**.

{% hint style="info" %}
To avoid storing the key in plain text, set it as an environment variable and reference it instead:

`"Authorization": "Bearer ${env:BOOMERANGME_MCP_TOKEN}"`
{% endhint %}
{% endtab %}

{% tab title="VS Code (Copilot)" %}
Create `.vscode/mcp.json` in your workspace, or add it to your user profile:

```json
{
  "inputs": [
    {
      "id": "boomerang-token",
      "type": "promptString",
      "description": "Boomerang API key",
      "password": true
    }
  ],
  "servers": {
    "boomerang": {
      "type": "http",
      "url": "https://api.digitalwallet.cards/mcp",
      "headers": {
        "Authorization": "Bearer ${input:boomerang-token}"
      }
    }
  }
}
```

VS Code prompts for the key the first time the server starts and stores it securely, so the token does not appear in the file.
{% endtab %}

{% tab title="Other clients" %}
Most MCP clients follow one of these patterns:

* **Native remote** — point the client at `https://api.digitalwallet.cards/mcp` and add the `Authorization: Bearer <YOUR_API_KEY>` header.
* **Proxy** — for clients that only launch local commands, use `npx -y mcp-remote https://api.digitalwallet.cards/mcp --header "Authorization: Bearer <YOUR_API_KEY>"`.
  {% endtab %}
  {% endtabs %}
  {% endstep %}

{% step %}

#### Verify the connection

After restarting your client, ask:

> Use the **whoami** tool and tell me which account I'm connected to.

If the connection works, it returns your company name, tariff, currency, and locale.

You can also ask it to **list your card templates** or **list your customers** to confirm the tools work end to end.
{% endstep %}
{% endstepper %}

### Agency accounts

If your account is on an **Agency** or **Agency Partner** tariff, you also get tools to work across sub-accounts:

* `search_companies` and `get_company` — find and inspect sub-accounts and referrals.
* `impersonate_company` — switch the session to act on behalf of one sub-account.
* `stop_impersonation` — return to your own agency context.

Impersonation is **session-scoped** and expires automatically after 1 hour.

### Security best practices

* Store the API key in an **environment variable** or your client's secret store.
* Use a **dedicated key** for AI assistants so you can rotate it independently.
* **Rotate the key immediately** if you suspect it has been exposed.

### Troubleshooting

| Symptom                           | Likely cause and fix                                                                                                                          |
| --------------------------------- | --------------------------------------------------------------------------------------------------------------------------------------------- |
| `401 Unauthorized`                | The API key is missing, mistyped, or your plan does not include API access. Re-copy the key from **Settings → API** and confirm your tariff.  |
| Tools do not appear               | The client was not fully restarted. Quit and reopen it. For Claude Desktop, quit the app completely.                                          |
| `npx` or `mcp-remote` errors      | Node.js is not installed or is not on your `PATH`. Install [Node.js](https://nodejs.org) and try again.                                       |
| Connection works but actions fail | The action may not be available on your tariff, or a required field may be missing. Check the returned error message for the server response. |


---

# Agent Instructions
This documentation is published with GitBook. GitBook is the documentation platform designed so that both humans and AI agents can read, navigate, and reason over technical content effectively. Learn more at gitbook.com.

## Querying This Documentation
If you need additional information that is not directly available in this page, you can query the documentation dynamically by asking a question.

Perform an HTTP GET request on the current page URL with the `ask` query parameter:

```
GET https://docs.boomerangme.cards/api/mcp.md?ask=<question>
```

The question should be specific, self-contained, and written in natural language.
The response will contain a direct answer to the question and relevant excerpts and sources from the documentation.

Use this mechanism when the answer is not explicitly present in the current page, you need clarification or additional context, or you want to retrieve related documentation sections.