> 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

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 either by **signing in with your Boomerang account (OAuth)** — the recommended way — or with a personal **API key**.

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

* **Customers & segments** — create, find, update, and delete customers; list segments.
* **Templates** — create card templates and manage reward tiers, membership tiers, and feedback links.
* **Cards** — issue cards, look them up, update fields, and set expiration and membership tier.
* **Balances** — add or subtract stamps, points, scores, visits, amounts, purchases, and rewards; redeem coupons.
* **Locations** — create and manage store locations.
* **UTM links** — create and manage UTM tracking links and read their reward and enrollment stats.
* **Workflows** — build, activate, pause, run, and inspect automation workflows and their logs.
* **External services** — connect and manage third-party integrations.
* **White-label** — manage custom domains, branding, and sub-account menus for white-label setups.
* **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** | <p>OAuth 2.1 <em>(recommended)</em><br>or<br><code>Authorization: Bearer \<YOUR\_API\_KEY></code></p> |
| **Method**         | `POST`                                                                                                |

{% hint style="info" %}
**Using a white-label or custom domain?** Replace `api.digitalwallet.cards` with your own **API** host everywhere below (for example `https://api.your-brand.com/mcp`). Sign-in works the same on any domain — each host is its own issuer.
{% endhint %}

#### 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.
* [Node.js](https://nodejs.org) is only needed for the **API-key** setup on Claude Desktop (the `mcp-remote` proxy). The OAuth setup needs nothing extra.

#### Choose how to connect

There are two ways to authenticate. Pick one:

* **Sign in with OAuth&#x20;*****(recommended)*** — no key to copy. Point your client at the server URL, then sign in with your normal Boomerang login in the browser and approve access. Your client registers itself automatically and refreshes its access for you.
* **API key** — send a personal Bearer token with every request. Best for clients without OAuth support, scripts, and automation.

### Option 1 — Sign in with OAuth (recommended)

You give your client just the **server URL**. On first use it opens a browser, you log in to Boomerang and approve access, and the assistant is connected — no API key to copy or store.

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

```bash
claude mcp add --transport http boomerang https://api.digitalwallet.cards/mcp
```

Then run `/mcp`, select **boomerang → Authenticate**, and a browser window opens for you to sign in and approve. Verify with `claude mcp list`.
{% endtab %}

{% tab title="Claude Desktop / Claude.ai" %}
Open **Settings → Connectors** and click **Add custom connector**.

Give it a name (for example `Boomerang`) and paste the URL:

```
https://api.digitalwallet.cards/mcp
```

Click **Add**, then **Connect**. A browser window opens for you to sign in and approve.

No `npx`, Node.js, or API key is required with this method.
{% 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"
    }
  }
}
```

Open **Settings → MCP** and click **Authenticate** (or **Needs login**) next to the Boomerang server. A browser window opens for sign-in.
{% endtab %}

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

```json
{
  "servers": {
    "boomerang": {
      "type": "http",
      "url": "https://api.digitalwallet.cards/mcp"
    }
  }
}
```

Start the server from the **MCP: List Servers** view. VS Code opens a browser for you to sign in and approve.
{% endtab %}

{% tab title="Other clients" %}

* **Native remote with OAuth** — point the client at `https://api.digitalwallet.cards/mcp`. It discovers the sign-in flow automatically and opens a browser for you.
* **Proxy** — for clients that only launch local commands, use `npx -y mcp-remote https://api.digitalwallet.cards/mcp`. The proxy opens a browser for OAuth on first run.
  {% endtab %}
  {% endtabs %}

{% hint style="info" %}
**Permissions.** When you approve access, the assistant is granted two scopes: **`mcp:read`** for read-only tools, and **`mcp:write`** for tools that create, update, or delete data.
{% endhint %}

### Option 2 — Connect with an API key

Use this for clients that don't support OAuth, or for scripts and automation.

{% 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 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.

{% hint style="info" %}
Prefer no key at all? Use **Option 1 — Sign in with OAuth** instead: Claude Desktop connects with just the server URL and no `mcp-remote` proxy.
{% endhint %}
{% 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 %}
  {% endstepper %}

### Verify the connection

After connecting, ask your assistant:

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

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

* Prefer **OAuth** — no long-lived secret is stored in your client's config files.
* If you use an **API key**, store it 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                                                                                                                                                                  |
| --------------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| Browser sign-in doesn't finish    | Make sure you're logged in to the correct Boomerang account in that browser, then retry. Remove and re-add the server to restart the flow.                                            |
| `401 Unauthorized`                | With OAuth, re-run the sign-in. With an API key, the key is missing, mistyped, or your plan does not include API access — re-copy it 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. (Only the API-key Claude Desktop setup needs it.)                             |
| 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.                                         |