MCP Server - LootRush Documentation

What it is

The LootRush MCP server lets an AI assistant — Claude, Cursor, or any Model Context Protocol client — read your own LootRush data: your account balance, cards, card transactions, card balance (collateral) and its ledger, cashback, spending-limit auto-refills, and your account history. So you can ask your assistant “how much USDC do I have on Base right now?” or “list my card transactions at Amazon last month” without leaving the chat. If your key also carries the mcp:write scope, the assistant can create cards, change them (status, nickname, spending limit and interval) and organize them into card groups — create, rename and delete groups, move cards between them, and lock or unlock every card in a group at once. Nothing else is writable — the server moves no funds and changes no account settings.

Every tool reads only your own account. The server works out who you are from your API key, and there is no parameter for pointing a tool at anyone else.

Writing is off unless you asked for it. A read-only key connects and lists the write tools, but every call to one returns “This API key is not authorized to make changes”. Scopes are fixed when a key is created, so to start writing you’ll need a new key with MCP + Write selected — then revoke the old one. Only give mcp:write to a key you trust with your cards.

At a glance


Endpoint	`https://mcp.lootrush.com/mcp`
Transport	Streamable HTTP (JSON-RPC 2.0), stateless — one request, one response
Method	`POST` only
Auth	Your LootRush API key (see Authentication)
Access	Reads need the `mcp` scope; card writes need `mcp:write`
Rate limit	1 call per second, per operation (each tool has its own budget)

Connecting

You need two things: the endpoint above and your LootRush API key — the same per-user key that authenticates the Withdraw and History APIs. Send it as a Bearer credential on every request.

Treat your API key like a password. Anyone holding it can read your account data — and, if the key carries mcp:write, create and cancel your cards. Keep it out of any config you commit to source control, and rotate it if it leaks.

Claude Code

claude mcp add --transport http lootrush https://mcp.lootrush.com/mcp \
  --header "Authorization: Bearer YOUR_API_KEY"

Claude Desktop / Cursor / other JSON-configured clients

Add LootRush to your client’s MCP server list:

{
  "mcpServers": {
    "lootrush": {
      "url": "https://mcp.lootrush.com/mcp",
      "headers": {
        "Authorization": "Bearer YOUR_API_KEY"
      }
    }
  }
}

Some MCP clients can’t attach custom headers to a remote server. For those, the server also accepts the key as a query parameter: https://mcp.lootrush.com/mcp?token=YOUR_API_KEY. Prefer the Authorization header where you can — a key in a URL is easier to leak.

Authentication

Generate your API key at Settings → API Key. The same key works across the Withdraw, History, and MCP APIs. The server looks for it in this order:

Authorization: Bearer <api-key> header — preferred.
?token=<api-key> query parameter — fallback for clients that can’t set headers.

Cookies are not accepted.

Your key also needs the right scopes, chosen when the key is created:

mcp — required for every request. Without it, a valid key still gets 403.
mcp:write — required by every write tool, checked per call.
mcp_card_reveal — required to reveal a card number and CVV.

If your key has an IP allowlist, requests from other IPs return 403 too. You can review both at Settings → API keys.

Available tools

Tool names are called exactly as written (camelCase).

getAccountBalance

Your total account value in USD — crypto holdings, staked balances, tokenized assets, and available wallet stablecoins, exactly like the portfolio Summary. Also reports your card balance (collateral) as a separate bucket.

getUserCards

Your cards across all issuers, with aggregated balances and a normalized card balance summary. Optionally reveals a single card’s number and CVV — end-to-end encrypted, decrypted only on your client.

getUserCardTransactions

Card transactions across all cards, or a single card.

getCashbackSummary

Your LootRush Rewards cashback — what’s redeemable now, what’s still maturing, and this month’s rate.

getUserCardSummary

A point-in-time snapshot of your cards — per-card balance, status, and limits as of any instant.

getUserCardBalanceMovements

Your card balance (collateral) ledger — each entry’s running balance and previous balance, the statement-style running total transactions don’t carry.

getUserCardBalanceAutomation

Your card spending-limit auto-refill history — each automatic balance top-up (amount, status, retries, on-chain tx hash, when it ran).

getAccountHistory

Your account history — deposits, withdrawals, converts, sends, and card operations — by date window, or one transaction by hash/id.

aggregate

Totals, counts, averages, min, max and medians over your card transactions or account history — computed over the whole filtered set, without paging every row.

createUserCards

Write (mcp:write). Creates one card, or queues a batch of up to 30 and returns a batchId you poll with the same tool.

updateUserCard

Write (mcp:write). Changes one card — status (block, unblock, cancel), nickname, spending limit and interval.

updateUserCards

Write (mcp:write). Applies the same status, spending limit or interval to up to 25 cards in one call.

getCardGroups

Your card groups — card count, locked cards, total spending limit and 30-day spend.

getCardGroupJobs

Progress of a group lock, unlock or cancel running in the background — cards changed so far, and which ones failed.

getCardSpendReport

Card spend over a date range, broken down by group, by card and by who created each card.

createCardGroup

Write (mcp:write). Creates a card group.

updateCardGroup

Write (mcp:write). Renames a group or changes its description.

moveCardToGroup

Write (mcp:write). Puts a card into a group, moves it to another one, or takes it out of its group.

moveCardsToGroup

Write (mcp:write). Moves up to 25 cards into the same group — or out of their groups — in one call.

setCardGroupCardsStatus

Write (mcp:write). Locks or unlocks every card in a group at once.

deleteCardGroup

Write (mcp:write). Deletes a group — keeping its cards, or cancelling them for good.

getAccountBalance

Returns the total USD value of your account — everything shown in your portfolio Summary: crypto holdings, staked balances, tokenized assets (stocks/ETFs) plus their profit/loss, and your available wallet stablecoins — with a per token/network breakdown so the balance can be charted, not just totalled. Your card balance (collateral) is reported as a separate bucket and is not included in totalUsdValue. Takes no parameters. All values are human-readable strings. If your balance snapshot is more than 5 minutes old, the tool refreshes it on-chain before responding. (The refresh runs at most once every 5 minutes per account; if it can’t complete, you get the last snapshot.) lastFetchedAt tells you when the returned data was captured.

Field	Description
`totalUsdValue`	Holdings + staked + tokenized assets + available wallet stablecoins (does not include your card balance)
`holdingUsdValue`	Crypto holdings (excludes operational stablecoins)
`stakedUsdValue`	Staked balances
`availableStableUsdValue`	Spendable wallet stablecoins (USDC on Base, USDT on Polygon, EURC on Ethereum), read live on-chain — the “available” balance above the portfolio in the Summary. Included in `totalUsdValue`
`tokenizedAssetsUsdValue`	Tokenized assets (stocks/ETFs)
`tokenizedAssetsPnl`	Combined realized + unrealized P/L (may be negative; `null` if unavailable). `tokenizedAssetsPnlPartial: true` is added when only one of the two P/L reads succeeded
`byToken`	Array of per-holding rows, biggest first: `{ token, network, isStake, amount, balanceUsd }` — `amount` is the human token amount, `balanceUsd` its USD value
`stableCoins`	Per-token wallet stablecoin rows backing `availableStableUsdValue`: `{ token, network, amount, balanceUsd }`
`cardBalance`	Your card collateral, shared across your cards, as its own bucket (not in `totalUsdValue`): `{ total, pendingDeposit, pendingWithdraw }`. `null` (with `cardBalanceError`) if the read failed
`cashback`	Your LootRush Rewards cashback, also its own bucket and never in `totalUsdValue`. Same shape `getCashbackSummary` returns, minus `monthProgress`. `null` (with `cashbackError`) when the read failed or your role does not grant card access
`tokenizedAssetsError`	Present only when the tokenized-asset value read failed — the total then excludes it rather than counting it as `$0`
`availableStableError`	Present only when the on-chain stablecoin read failed — the total then excludes that bucket
`cardBalanceError`	Present only when the card-balance read failed (`cardBalance` is then `null`)
`cashbackError`	Present only when the cashback read failed, or when your business role grants `balance` but not `card` — cashback is card-domain data, so it needs the `card` permission even here
`lastFetchedAt`	When the snapshot was taken (ISO 8601, or `null`)
`isStale`	`true` when the snapshot is missing or older than 24h

getUserCards

Returns your cards across all issuers plus aggregated balances. Each card carries its cardId and cardIssuerUserId — pass those to getUserCardTransactions to scope to a single card, or back into this tool (with includeCardSecrets) to reveal that card’s number and CVV. The response also carries cardBalance — your card collateral, shared across all your cards, normalized to { total, pendingDeposit, pendingWithdraw } (the same shape getAccountBalance returns; null if the balances read failed). The raw balances field sits alongside it if you need the full licensed/nonLicensed regulatory split. Each card also carries groupId and groupName — the card group it belongs to, or null when it isn’t in one. cashback comes back too — the same summary getCashbackSummary returns, minus monthProgress. If cashback can’t be read you still get your cards, with a cashbackError in place of that section.

Parameter	Type	Required	Description
`cardId`	string	No	Filter to one card (from a prior `getUserCards`)
`cardIssuerUserId`	string	No	Required alongside `cardId` to target a specific card
`groupId`	string	No	Only the cards in this card group (from `getCardGroups`)
`includeCardSecrets`	boolean	No	Reveal the card number (PAN) and CVV — encrypted (see below). Requires `cardId`, `cardIssuerUserId`, and `sessionId`
`sessionId`	string	No	Your RSA-wrapped AES key. Required when `includeCardSecrets` is `true`

Revealing card number & CVV

The server returns only the issuer’s ciphertext — the number and CVV are decrypted on your client, with a key that never leaves it. That makes this an advanced flow: your MCP client has to run a small encryption handshake, which a plain chat client can’t do. Wrap the tool in your own client (Node/Python/Bash) that implements the two steps below. Beyond the base mcp scope, revealing secrets needs the mcp_card_reveal scope on your key, read permission on the card-details feature, and a card you own. The handshake

Fetch the reveal public key with getCardRevealPublicKey. Generate a random AES-128 key locally and RSA-OAEP–wrap it with that key (SHA-1 hash). The base64 of the wrapped key is your sessionId.
Call getUserCards with includeCardSecrets: true, the target cardId / cardIssuerUserId, and your sessionId. The response carries cardSecrets.encryptedPan and cardSecrets.encryptedCvc, each { data, iv } (both base64) — AES-GCM ciphertext, where data is the ciphertext with the 16-byte auth tag appended and iv is the nonce.
Decrypt each locally with the AES key you kept in step 1.

You only need to do step 1 once. The AES key doesn’t have to be ephemeral — generate one, derive the sessionId a single time, and store both. Later reveals just pass the stored sessionId and decrypt with the stored key. Each response ships a fresh iv, so reusing the AES key never reuses a nonce. Keep that key on your side only.

Reveals share one per-account budget: 10 per minute across all your cards, not per card. Beyond that the tool returns a “too many card reveals” error — back off and retry.

A key that can reach this endpoint can read your card numbers, with no extra confirmation step. Keep it in a trusted MCP client only, never commit or sync it, and rotate it right away if it may have leaked. Every reveal is recorded in an audit log (card id and outcome only — never the number, CVV, or your session key).

Don’t hardcode the public key: getCardRevealPublicKey always serves the current one, so LootRush can rotate it without any change on your side. It also returns the wrapping algorithm (RSA-OAEP, SHA-1).

Set the OAEP hash to SHA-1 explicitly — don’t rely on your library’s default. Most crypto libraries (WebCrypto, Python cryptography, and others) default RSA-OAEP to SHA-256, and with that default the issuer cannot unwrap your sessionId. The reveal then fails server-side and cardSecrets comes back null with a cardSecretsError, rather than a clear “wrong hash” message. Always pass the hash explicitly, as the Node example below does (oaepHash: "sha1").

getCardRevealPublicKey (reveal helper)

The helper tool behind step 1. Takes no parameters; fetch it once and cache the result — it changes only when LootRush rotates the key.

Field	Description
`publicKey`	RSA public key (PEM) to RSA-OAEP–wrap your AES key with
`algorithm`	Wrapping algorithm — `RSA-OAEP`
`hash`	OAEP hash — `SHA-1`
`usage`	Short reminder of the wrap-and-decrypt handshake

Node example

import crypto from "node:crypto";

// Fetch once from the getCardRevealPublicKey tool (result.publicKey), then cache.
const ISSUER_PUBLIC_KEY = await fetchRevealPublicKey(); // PEM

// Step 1 — build the sessionId (keep secretKeyHex; you need it to decrypt).
const secretKeyHex = crypto.randomBytes(16).toString("hex"); // AES-128 key
const wrappedKey = crypto.publicEncrypt(
  {
    key: ISSUER_PUBLIC_KEY,
    padding: crypto.constants.RSA_PKCS1_OAEP_PADDING,
    oaepHash: "sha1",
  },
  // The issuer expects the base64 of the raw key bytes, RSA-wrapped.
  Buffer.from(Buffer.from(secretKeyHex, "hex").toString("base64"), "utf8")
);
const sessionId = wrappedKey.toString("base64");

// Step 2 — call getUserCards with includeCardSecrets + sessionId (omitted here).
// Step 3 — decrypt the returned ciphertext locally.
function decryptSecret({ data, iv }, secretKeyHex) {
  const key = Buffer.from(secretKeyHex, "hex");
  const ivBytes = Buffer.from(iv, "base64");
  const blob = Buffer.from(data, "base64");
  // WebCrypto AES-GCM appends the 16-byte auth tag to the ciphertext.
  const tag = blob.subarray(blob.length - 16);
  const ciphertext = blob.subarray(0, blob.length - 16);
  const decipher = crypto.createDecipheriv("aes-128-gcm", key, ivBytes);
  decipher.setAuthTag(tag);
  return Buffer.concat([decipher.update(ciphertext), decipher.final()]).toString("utf8");
}

// const pan = decryptSecret(cardSecrets.encryptedPan, secretKeyHex);
// const cvv = decryptSecret(cardSecrets.encryptedCvc, secretKeyHex);

getUserCardTransactions

Fetches your card transactions across all issuers, or a single card’s when cardId is given.

Parameter	Type	Required	Description
`cardId`	string	No	Scope to one card. Use an id from `getUserCards` rather than building one
`cardIssuerUserId`	string	No	Required alongside `cardId`, from the same `getUserCards` row
`groupId`	string	No	Only transactions of the cards in this card group (from `getCardGroups`). Ignored when `cardId` is set
`page`	number	No	1-indexed page number (default `1`)
`pageSize`	number	No	Items per page, 1–100
`startDate`	string	No	ISO 8601 lower bound
`endDate`	string	No	ISO 8601 upper bound
`status`	string	No	One of `on_hold`, `reversed`, `declined`, `settled`
`polarity`	string	No	One of `debit`, `credit`

Card transactions carry no running balance. For the statement-style running total, use getUserCardBalanceMovements.

A cardId that matches none of your cards does not fail. You get the full cross-card listing instead, with filterMatchedNothing: true and a filterHint explaining why. Check that flag before presenting the result as one card’s transactions — otherwise a mistyped id looks like “this card has no transactions”. aggregate behaves differently and rejects the filter outright.

getCashbackSummary

Your LootRush Rewards cashback across every enrolled card-issuer account. Takes no card ids — enrollment is resolved from your identity server-side.

Parameter	Type	Required	Description
`month`	string	No	`YYYY-MM` for the rate/progress section. Omit for the current month. Does not affect the balance, which is always live

The four cashback balances

Cashback isn’t a single balance with a pending amount — it has four states, and only one of them is money you can use today:

Field	What it is
`available`	Redeemable right now
`accruing`	Already earned, still maturing — see `accruingByMonth`
`redeeming`	Held by a redemption request awaiting payout
`estimated`	Cashback of purchases still on hold: not earned yet, and not guaranteed — the purchase can still be reversed
`total`	The headline (`available` + `redeeming`), taken as-is from the same source the site shows

Also returned: currency, expiring (soonest slice about to lapse, or null), accruingByMonth (a release calendar: month, amount, releaseDate), accounts (how many accounts were folded in), and monthProgress — this month’s spend buckets with their band ladder. A meaning object restates each field in one line, so your assistant doesn’t have to guess which bucket is which.

enrolled: false is not “you earned zero”. It means no card-issuer account has cashback active, so the amounts are zero because the programme is off. Check the flag before quoting the number.

If your accounts disagree about currency, the headline amounts stay zero and a byCurrency array carries the real split — amounts in different currencies are never added together.partial: true means at least one account did not answer, so the amounts cover only the ones that did.

getUserCardSummary

A point-in-time snapshot of your cards across all issuers — each card’s balance, status, and limits as of asOf (defaults to now). Handy for “what did my cards look like at the end of last month?”.

Parameter	Type	Required	Description
`cardIssuerUserId`	string	No	Pin the snapshot to a single card-issuer account (from `getUserCards`). Omit for every issuer you hold
`groupId`	string	No	Only the cards in this card group (from `getCardGroups`)
`asOf`	string	No	ISO 8601 point-in-time for the snapshot (default now)
`page`	number	No	1-indexed page number (default `1`)
`pageSize`	number	No	Items per page, 1–100

Returns cardsSnapshot (the per-card rows) plus pagination.

The snapshot covers cards of every status, canceled ones included — read each row’s status if you only want the ones still spendable.

getUserCardBalanceMovements

Your card balance (collateral) ledger. Unlike card transactions, each movement carries a runningBalance and previousBalance — the classic statement running total. The upstream feed is per-issuer, so results are grouped by issuer to keep each running-balance series coherent.

Parameter	Type	Required	Description
`cardIssuerUserId`	string	No	Pin to a single card-issuer account (from `getUserCards`). Omit to sweep every issuer you hold
`page`	number	No	1-indexed page number (default `1`)
`pageSize`	number	No	Items per page, 1–100
`startDate`	string	No	ISO 8601 lower bound
`endDate`	string	No	ISO 8601 upper bound

Returns balanceMovements: an array of { cardIssuerUserId, movements, pagination } groups, where each movement carries runningBalance and previousBalance.

getUserCardBalanceAutomation

Your card balance-automation history: spending-limit auto-refills. Each entry is one automatic top-up of your card’s spending limit — its amount, status, retry count, on-chain transaction hash, and when it executed.

Parameter	Type	Required	Description
`cardIssuerUserId`	string	No	Pin to a single card-issuer account (from `getUserCards`). Omit to sweep every issuer you hold
`page`	number	No	1-indexed page number (default `1`)
`pageSize`	number	No	Items per page, 1–100
`startDate`	string	No	ISO 8601 lower bound
`endDate`	string	No	ISO 8601 upper bound

Returns autoRefillHistories (the per-top-up rows) plus pagination.

getAccountHistory

Your account history as report transactions — deposits, withdrawals, converts, sends, and card operations, joined with their source records (amounts human-readable). Newest first. Pass filterByHash or filterByOrderId to fetch a single transaction (this replaces the date window); otherwise you get the window bounded by startDate/endDate, capped by limit.

Parameter	Type	Required	Description
`filterByHash`	string	No	Fetch only the transaction(s) with this on-chain transaction hash
`filterByOrderId`	string	No	Fetch only the transaction(s) with this order id (the source record id)
`startDate`	string	No	ISO 8601 lower bound (ignored when a filter is set)
`endDate`	string	No	ISO 8601 upper bound (ignored when a filter is set)
`showFee`	boolean	No	Include fee lines (default `true`)
`limit`	number	No	Max transactions to return (default `100`, max `500`). Response sets `truncated: true` when the cap is hit

aggregate

Computes a total over your data without paging every row. getUserCardTransactions and getAccountHistory return rows; this returns the number those rows add up to, across the whole filtered set rather than the page you happened to fetch. You describe the slice — column, grouping, filters — and get back the figure.

Parameter	Type	Required	Description
`op`	string	Yes	One of `sum`, `count`, `avg`, `min`, `max`, `median`
`datasetId`	string	No	The `datasetId` a listing call returned — reuses that call’s filters, so the total covers exactly the slice you just listed
`source`	string	No	Required when `datasetId` is omitted. One of `cardTransactions`, `accountHistory`
`filters`	object	No	The same filters the listing tool for that source accepts. Ignored when `datasetId` is given
`column`	string	No	The column to aggregate. Required for every op except `count`. See `aggregatable` on the listing response
`groupBy`	string	No	Break the result down by a column. See `groupable` on the listing response
`timeBucket`	string	No	Break down by time instead: `day`, `week` or `month`. Ignored when `groupBy` is set
`where`	object	No	Filters the rows must match. Keys and values are restricted per source; `merchantName` takes free text and is matched loosely
`whereNot`	object	No	Filters the rows must not match — for “everything except X”. Same keys as `where`
`limit`	number	No	Max groups returned, largest first (default `25`)

The response carries byGroup (one entry per group, with its value and row count), plus rowsCovered, totalCount and complete.

Check complete before quoting the number. When it is false the result covers only part of the slice — rowsCovered of totalCount rows — and note suggests how to narrow the query.

Amounts in different currencies come back as separate entries and are never added together. Card money columns are also split by status unless you pin one: a declined transaction is an attempt, not spend, and only settled (and on_hold, still authorising) is money that actually left the account.

Two ways to call it — reuse a listing’s slice, or describe it directly:

// After a getUserCardTransactions call that returned datasetId "ds_a91f2c"
{ "datasetId": "ds_a91f2c", "op": "sum", "column": "amount", "groupBy": "merchantName" }

// Or straight to the number, with no listing call at all
{ "source": "cardTransactions", "op": "sum", "column": "amount",
  "where": { "status": "settled", "polarity": "debit" },
  "filters": { "startDate": "2026-07-01", "endDate": "2026-07-31" } }

Filtering and grouping by merchant

Card networks don’t send a clean merchant name. What arrives is a settlement descriptor — a brand fragment, an acquirer prefix and a per-transaction reference, truncated at 25 characters:

FACEBK* WGBD9SZ2T2         FACEBK* QNNJLSV2T2        Google ADS8407433152
SQ *KONA ISLAND COFFEE     BKG*Hotel at Booking.c    TIKTOK ADS / TikTok Ads

Two rows from the same merchant rarely look alike, so aggregate canonicalises them. groupBy: "merchantName" returns one group per merchant, and each group carries a few of the raw descriptors behind it under samples so you can check the grouping. For the same reason, where/whereNot on merchantName take the brand as a person would say it — "facebook", "tiktok" — and match loosely enough to reach the abbreviations the networks send. Don’t pass a descriptor copied off a row: that filters down to the single transaction it came from.

// "how much did I spend on facebook this month"
{ "source": "cardTransactions", "op": "sum", "column": "amount",
  "where": { "status": "settled", "merchantName": "facebook" },
  "filters": { "startDate": "2026-07-01", "endDate": "2026-07-31" } }

// "total everything EXCEPT facebook"
{ "source": "cardTransactions", "op": "sum", "column": "amount",
  "where": { "status": "settled" },
  "whereNot": { "merchantName": "facebook" } }

Merchant terms must be 3–64 characters. whereNot works on cardTransactions only — accountHistory rejects it rather than silently ignoring it.

Grouping by card nickname

cardNickname is groupable too, and matched the same loose way. It’s the name you gave the card, not cardName — that one carries the embossed legal name, which is identical on every card of a business account. So if you name cards per campaign or per person (DAVID LORRAN 15), one call totals them:

{ "source": "cardTransactions", "op": "sum", "column": "amount",
  "where": { "status": "settled", "cardNickname": "DAVID" } }

Unlike merchants, nicknames are grouped verbatim — canonicalising them would merge cards you deliberately named apart.

Grouping by card group

groupName works the same way as cardNickname: grouped verbatim, matched loosely in where/whereNot. Spend on cards that aren’t in any group lands in its own (no group) entry.

// "how much did each card group spend this month"
{ "source": "cardTransactions", "op": "sum", "column": "amount",
  "groupBy": "groupName",
  "where": { "status": "settled" },
  "filters": { "startDate": "2026-09-01", "endDate": "2026-09-30" } }

// "how much did the Marketing group spend"
{ "source": "cardTransactions", "op": "sum", "column": "amount",
  "where": { "status": "settled", "groupName": "marketing" } }

To total one group by its id instead, pass groupId in filters, or list it with getUserCardTransactions and reuse the datasetId.

A card is counted under the group it is in now. Moving a card to another group moves its past spend with it.

The card group in these calls is unrelated to groupBy and byGroup, which are the aggregate’s own breakdown of the result.

Reading `matched`

Every response that used a loose match carries matched — the canonical names each term actually selected, keyed by column and then term:

{ "byGroup": [ { "group": "all", "currency": null, "value": 9792.14, "count": 9792 } ],
  "matched": { "merchantName": { "facebook": ["FACEBK", "FACEBOOKAD"] } } }

When a term in where resolves to an empty array, nothing by that name was found — which is a different fact from spending nothing there, and the accompanying note says so. Don’t present that 0 as spend at the merchant; use groupBy: "merchantName" to see which merchants exist.An empty array for a whereNot term is harmless — there was nothing to remove, so the “everything except X” total is still exactly right.

What each source can aggregate

Source	Aggregatable columns	Notes
`cardTransactions`	`amount`, `localAmount`, `estimatedCashback`	`amount` is in your account currency; `localAmount` is the merchant’s original currency and is always split by it
`accountHistory`	`amount`, `netChange`	Token amounts, converted to whole tokens and grouped by `tokenSymbol`

accountHistory has no fiat column to aggregate — that column is stored in different scales depending on the transaction type, so a total over it would add incompatible units. Use the token columns, or aggregate cardTransactions for spend in your account currency.

The `datasetId` handle

Listing responses carry a datasetId alongside their rows, plus the columns you can aggregate and group by:

Response	Carries
`getUserCardTransactions`	`datasetId`, `aggregatable`, `groupable`, `filterableText`, `aggregateFilterHint`
`getAccountHistory`	`datasetId`, `aggregatable`, `groupable`, `ops`

filterableText names the keys that take free text in where/whereNot, and aggregateFilterHint says how to phrase them. ops lists the operations that source can answer, and appears only where a source supports fewer than all six — treat its absence as “all of them”. The handle stores that call’s filters, never its rows, and expires after 15 minutes. Passing it to aggregate re-runs the same filters with the aggregation applied, so the total covers the same slice you were shown rather than just the page you fetched. A listing sometimes returns no datasetId — one pinned to a single cardId, for example, which the aggregate can’t reproduce. Pass source and filters yourself in that case.

Writing — creating and changing cards

The card tools below and the card group write tools are the only ones that change anything, and all of them need a key carrying the mcp:write scope. Without it the tool returns This API key is not authorized to make changes (missing the mcp:write scope). and nothing is created or changed. You usually don’t pass cardIssuerUserId. Most accounts have a single card-issuer account and it’s filled in for you, so you can leave the parameter out. If your account holds more than one, the tool asks for it and lists the ids you can use. An account with no approved card-issuer account can’t create or change cards yet, and the tool says so.

Write limits

Like every operation, each write tool gets one call per second on its own budget — see Rate limits. createUserCards and updateUserCard don’t compete with each other, or with any read. Locking, unlocking or cancelling a whole card group is one call, however many cards the group holds. Card creation carries one more limit that counts cards, not calls: 300 cards per hour. A request that would cross the ceiling is refused whole — no partial batch — and the message tells you how many you’ve used and how many are left. Because it counts cards, a single call for 30 spends 30. A refused request spends nothing, so asking for 30 when only 5 fit doesn’t burn those 5 — ask for 5 and they go through. The refusal is an error tool result rather than an HTTP status, and nothing is created, so it’s safe to retry once the window rolls over.

One kind of error is not safe to retry blind. If a call fails on its way to the card issuer — dropped connection, or a server error from the issuer — the response tells you the outcome is not known: the card may or may not have been created, and a change may or may not have applied. Check with getUserCards before sending it again, because creating a single card carries no idempotency key and retrying a request that actually succeeded leaves you with two cards. A timeout means the same thing.A rejected request is different, and says so: nothing was created, and the message names what to fix — the holder name (a full name, not initials), the spending limit, the interval.

“Card changes through the MCP are temporarily unavailable.” LootRush can pause card writes — for maintenance, an investigation, or unusual activity on one account. Nothing is changed when you see this: the request stops before it is sent, so there’s no half-created card and it’s safe to retry later. Reading keeps working, and so does checking a batch you already queued.

createUserCards

Creates a single card, or queues a batch of up to 30. batchId decides which mode you’re in:

batchId omitted — creates. quantity: 1 (the default) returns the card itself; a higher quantity queues the batch and returns a batchId.
batchId given — a pure status read of that batch. Nothing is created, and an id that isn’t a valid batch id is an error rather than a fall-through to creating cards.

Parameter	Type	Required	Description
`batchId`	string	No	Status mode: read back a batch queued earlier. Use a value this tool returned
`quantity`	number	No	How many cards to create, 1–30 (default `1`)
`holder`	string	When creating	Name printed on the card. Letters, numbers, spaces, dots and hyphens only — any other character is rejected. Only the first 26 characters are printed
`spendingLimit`	number	When creating	Spending limit in USD, per card
`spendingInterval`	string	When creating	Window the limit applies to: `daily`, `weekly`, `monthly`, `all_time`
`nickname`	string	No	Nickname for the card. On a batch it repeats on every card — prefer `nicknamePrefix`
`nicknamePrefix`	string	No	Names each card of a batch `<nicknamePrefix><number>`. Taken literally, so any separator is part of it (`"Store-"`). Overrides `nickname`
`nicknameStartAt`	number	No	First number of that sequence (default `1`)
`nicknamePadding`	number	No	Zero-pads the number to this width, so `7` with `3` reads `007` (0–12)
`cardIssuerUserId`	string	No	Only when your account has several approved card-issuer accounts
`groupId`	string	No	Create the card(s) inside this card group (from `getCardGroups`). The card is created on the group’s card-issuer account, so you don’t need `cardIssuerUserId`

A batch never blocks. Thirty cards take longer to issue than the request may stay open, so the tool hands back a handle instead of waiting:

{ "batchId": "9f1c…", "status": "queued", "totalCards": 30,
  "hint": "Call createUserCards again with this batchId to see how far it got." }

Calling it again with that batchId returns the batch’s progress — status, totalCards, cardsCreated, cardsFailed, and cardIds for the cards issued so far.

Retrying a batch does not double it. If a batch is still running with the same recipe and the same size, that batch is returned (with alreadyRunning: true) instead of a second one being queued — so retrying on a dropped connection is safe without an idempotency key.

Bulk creation is a business-account feature. If your account doesn’t have it enabled, a quantity above 1 creates one card rather than the batch. The response says so — created: 1, requested: 30, bulkUnavailable: true, alongside the card. That card is real and already exists, so create the rest one at a time (or ask support to enable bulk creation) rather than re-sending the same request.

updateUserCard

Changes one card per call. Pass cardId plus at least one of status, nickname, spendingLimit, spendingInterval.

Parameter	Type	Required	Description
`cardId`	string	Yes	The card to change, from `getUserCards`
`status`	string	No	`active`, `inactive`, `locked` or `canceled`
`nickname`	string	No	New nickname
`spendingLimit`	number	No	New spending limit in USD
`spendingInterval`	string	No	`daily`, `weekly`, `monthly`, `all_time`
`cardIssuerUserId`	string	No	Only when your account has several approved card-issuer accounts

The response carries updated: true and the card’s state after the change, read back for you:

{ "updated": true, "card": { "id": "…", "status": "inactive", "…": "…" } }

canceled is permanent. A canceled card can never be used again, and no call brings it back. To stop a card temporarily — usually what “block my card” means — use inactive or locked, both reversible with active.

If the change lands but the read-back fails, the response still says updated: true and adds a note telling you not to retry — the write already happened, and repeating it would apply it twice.

updateUserCards

Applies the same change to up to 25 cards in one call. Use it instead of calling updateUserCard once per card. Pass cardIds plus at least one of status, spendingLimit, spendingInterval.

Parameter	Type	Required	Description
`cardIds`	string[]	Yes	1 to 25 cards, from `getUserCards`, each listed once
`status`	string	No	`active`, `inactive` or `locked`
`spendingLimit`	number	No	New spending limit in USD
`spendingInterval`	string	No	`daily`, `weekly`, `monthly`, `all_time`
`cardIssuerUserId`	string	No	Only when your account has several approved card-issuer accounts

Canceling and nicknames are not available here: cancel a card with updateUserCard, one card at a time. Each card gets its own result, in the order you sent them:

{
  "requested": 3, "updated": 2, "failed": 1, "notAttempted": 0,
  "results": [
    { "cardId": "…", "status": "updated" },
    { "cardId": "…", "status": "updated" },
    { "cardId": "…", "status": "failed", "code": "NOT_FOUND" }
  ],
  "note": "…"
}

updated — the change was applied.
failed — that card was not changed. NOT_FOUND means the card does not exist on that card account or is outside the groups you can manage.
failed with UNCERTAIN — the card may or may not have changed. Check it with getUserCards before sending it again.
notAttempted — the call ran out of time before reaching that card. It was not changed; send it again in a new call.

One card failing does not stop the others, so a call can come back partly done. Send again only the cards that were not updated.

Card groups

Card groups organize cards — per team, per campaign, per client. Every card belongs to at most one group, and a group belongs to one card-issuer account, so a card can only join a group on the same account. Reading groups needs only the mcp scope. Every change needs mcp:write, like the card writes above.

getCardGroups

Lists your card groups across every card-issuer account.

Parameter	Type	Required	Description
`search`	string	No	Only groups whose name or description contains this text
`page`	number	No	1-indexed page number (default `1`)
`pageSize`	number	No	Groups per page, 1–100 (default `100`)
`cardIssuerUserId`	string	No	Only the groups of one card-issuer account. Omit for all of them

Each group in cardGroups carries:

Field	Meaning
`id`	The `groupId` every other group tool takes
`name`, `description`	As you set them
`cardCount`, `lockedCardCount`	Cards in the group, and how many of them are locked
`cardLimit`	Sum of the spending limits of the group’s cards
`spend30Days`	Settled spend of the group over the last 30 days
`cardIssuerUserId`	The card-issuer account the group belongs to

cardLimit and spend30Days are decimal strings, so the amounts arrive exactly. If the spend can’t be read — or your role can’t read card transaction history — you still get the groups, with spend30Days: null and a spendError explaining why.

getCardGroupJobs

Locking, unlocking or cancelling a group’s cards runs in the background, a page of cards at a time. Those calls return a jobId right away; this tool tells you how far it got.

Parameter	Type	Required	Description
`jobId`	string	No	One run, by the `jobId` a group lock, unlock or delete returned. Omit to list recent runs
`groupId`	string	No	Only the runs of this group
`statuses`	string[]	No	Only runs in these states: `pending`, `running`, `completed`, `failed`
`since`	string	No	ISO 8601 — only runs started at or after it

A run reads like this:

{ "job": { "id": "…", "groupId": "…", "targetStatus": "LOCKED", "status": "RUNNING",
  "eligibleTotal": 120, "updatedCards": 40, "failedCount": 0, "failedCards": [],
  "createdAt": "…", "finishedAt": null } }

status is PENDING, RUNNING, COMPLETED or FAILED.
eligibleTotal is how many cards the run set out to change, known once its first page has run (null until then). updatedCards counts those already changed.
failedCards lists the cards that couldn’t be changed and why — the first 200; failedCount is the full number.
A listing searches the account’s 100 most recent runs. When it reaches that, the answer carries listingCapped: true — filter by statuses to reach older runs in those states.

Right after starting a run, getCardGroupJobs can take a few seconds to find it. A “not found” at that moment isn’t final — wait a moment and ask again.

getCardSpendReport

Settled card spend over a date range, with the breakdowns a spend review needs: which group spent the most, which cards, and who created them. Needs your role’s read permission for card transaction history.

Parameter	Type	Required	Description
`startDate`	string	Yes	First day, `YYYY-MM-DD` (UTC)
`endDate`	string	Yes	Last day, `YYYY-MM-DD` (UTC), inclusive. At most 366 days after `startDate`
`cardIssuerUserId`	string	No	Only one card-issuer account. Omit for the whole account

The answer carries:

Field	Meaning
`totalSpend`	Settled spend in the range, across every card
`cardsWithSpend`, `totalCards`	Cards that spent something, out of all your cards
`averageSpendPerActiveCard`	`totalSpend` divided by `cardsWithSpend`
`topGroup`	The first row of `byGroup` — the group that spent the most. `null` when no group has cards or spend in the range
`byGroup`	Per group: `groupId`, `name`, `cardCount`, `spend` — largest first
`byCard`	Per card: `cardId`, `name`, `lastFourDigits`, `groupName`, `spend`
`byCreator`	Per person who created cards: `userId`, `name`, `cardCount`, `spend`

Amounts are decimal strings. A canceled card still counts toward the spend it made; its name may come back null. On a very large account the report may come back with incomplete: true: totalSpend is still exact, but card counts and some card names are not — pass cardIssuerUserId to report one account at a time.

The report covers the whole account, so a role limited to specific card groups can’t run it. Use aggregate with groupBy: "groupName" for the groups you can see.

createCardGroup

Parameter	Type	Required	Description
`name`	string	Yes	Up to 255 characters. Must be unique on the account
`description`	string	No	Up to 1,000 characters
`cardIssuerUserId`	string	No	Only when your account has several approved card-issuer accounts

Returns the new group as cardGroup. Add cards to it with moveCardToGroup, or create them inside it with createUserCards and groupId.

updateCardGroup

Pass groupId plus name, description or both. Anything you leave out stays as it is.

Parameter	Type	Required	Description
`groupId`	string	Yes	The group to change, from `getCardGroups`
`name`	string	No	New name
`description`	string \| null	No	New description. `null` removes it

Returns the group after the change as cardGroup.

moveCardToGroup

Moves one card per call.

Parameter	Type	Required	Description
`cardId`	string	Yes	The card, from `getUserCards`
`groupId`	string \| null	Yes	The group to move it into — or `null` to take the card out of its group

groupId is required even when you are removing a card: send null explicitly. Returns the card after the move as card.

moveCardsToGroup

Moves up to 25 cards into the same group in one call — or takes them all out of their groups. Use it instead of calling moveCardToGroup once per card.

Parameter	Type	Required	Description
`cardIds`	string[]	Yes	1 to 25 cards, from `getUserCards`, each listed once
`groupId`	string \| null	Yes	The group to move them into — or `null` to take them out of their groups
`cardIssuerUserId`	string	No	Only with `groupId: null`, and only when your account has several approved card-issuer accounts

The response lists every card as moved (with the card after the move), failed (with a code) or notAttempted, the same way as updateUserCards. A card on a different card account than the group fails with NOT_FOUND. Send again only the cards that were not moved.

setCardGroupCardsStatus

Locks or unlocks every card in a group.

Parameter	Type	Required	Description
`groupId`	string	Yes	The group, from `getCardGroups`
`status`	string	Yes	`locked` stops the cards from spending; `active` lets them spend again

Both are reversible. Canceled cards stay canceled. The call returns as soon as the run has started:

{ "job": { "id": "…", "status": "PENDING", "targetStatus": "LOCKED", "…": "…" },
  "hint": "This runs in the background. Call getCardGroupJobs with this jobId…" }

Follow it with getCardGroupJobs. Asking again while that run is still going returns the same run rather than starting a second one. A group can run only one kind of change at a time, so an unlock sent while a lock is still running is refused — wait for the lock to finish.

To stop a single card, use updateUserCard instead.

deleteCardGroup

Parameter	Type	Required	Description
`groupId`	string	Yes	The group to delete, from `getCardGroups`
`cancelCards`	boolean	No	`true` also cancels every card in the group, permanently. Default `false`

It works two very different ways:

cancelCards omitted or false — the group is deleted right away. Its cards keep working; they’re just no longer in a group. The response is { "deleted": true, "detachedCards": 4 }.
cancelCards: true — every card in the group is cancelled in the background, and the group is deleted once none is left. The response is { "deleted": false, "cancelRunQueued": true, "job": { … } } — follow the job with getCardGroupJobs. If any card can’t be cancelled, the run ends as FAILED, lists those cards, and the group is kept.

cancelCards: true cannot be undone. Every card it reaches can never be used again, and no call brings them back. Leave it out unless the cards themselves should stop existing — to only pause them, use setCardGroupCardsStatus with locked.

Like the card writes, a group write that fails on its way to the card issuer says the outcome is not known. Check getCardGroups — or getCardGroupJobs for a lock, unlock or cancel — before sending it again.

Access & scoping

Your account, always. It’s resolved from your API key when you connect, and every tool is scoped to it.
Business roles are honored. If you’re a member of a business, a tool that reads a resource runs only when your role grants read permission for that feature, and a tool that changes one only when your role grants write — you are authorized as yourself, not as the account’s owner. Individual accounts and business owners are unrestricted over their own data.
Roles limited to some card groups see only those. If your role covers specific groups, every tool answers for those groups’ cards alone — listings, transactions, group runs and totals. A group or card outside them reads as “not found”. Such a role can’t create, rename or delete groups, or take a card out of its group.
Deleting a card group needs delete permission. On a business account, creating a group needs your role’s write permission for cards, changing a group or its cards needs update, and deleting a group — with or without its cards — needs delete.
Writes are limited to cards and card groups. The server moves no funds, opens no withdrawals, and changes no account settings.

Rate limits

One call per second, per operation. Every tool has its own budget, so getUserCards running at its ceiling leaves getAccountHistory and createUserCards untouched. tools/list and the connection handshake have their own budgets too. In practice you can run different tools back to back without throttling, and only repeated calls to the same tool wait a second.

Operation	Rate	Also limited by
`getAccountBalance`	1 / second	—
`getUserCards`	1 / second	10 card reveals per minute, per account, when using `includeCardSecrets`
`getUserCardTransactions`	1 / second	—
`getUserCardSummary`	1 / second	—
`getUserCardBalanceMovements`	1 / second	—
`getUserCardBalanceAutomation`	1 / second	—
`getCashbackSummary`	1 / second	—
`getAccountHistory`	1 / second	`limit` caps a call at 500 transactions (default 100)
`aggregate`	1 / second	—
`getCardRevealPublicKey`	1 / second	—
`createUserCards`	1 / second	300 cards per hour, per account — counts cards, not calls. See Write limits
`updateUserCard`	1 / second	—
`updateUserCards`	1 / second	Up to 25 cards per call
`getCardGroups`	1 / second	—
`getCardGroupJobs`	1 / second	—
`getCardSpendReport`	1 / second	—
`createCardGroup`	1 / second	—
`updateCardGroup`	1 / second	—
`moveCardToGroup`	1 / second	—
`moveCardsToGroup`	1 / second	Up to 25 cards per call
`setCardGroupCardsStatus`	1 / second	One call covers every card in the group
`deleteCardGroup`	1 / second	One call covers every card in the group, with `cancelCards`
`tools/list`, `initialize`, other JSON-RPC methods	1 / second each	—

createUserCards with a batchId reads a batch back rather than creating anything, but it’s the same operation and draws on the same row — so poll a batch at most once per second. Beyond the limit, the server returns a 429 with JSON-RPC error code -32005, naming the operation you exceeded:

{
  "jsonrpc": "2.0",
  "error": {
    "code": -32005,
    "message": "Rate limit exceeded for getUserCards (one call per second). Each operation has its own budget, so a different tool is not affected."
  },
  "id": null
}

Nothing is created or changed when you hit it, on read or write, so a 429 is always safe to retry after waiting.

Tips for staying under it

Ask for a batch, not a loop. createUserCards takes a quantity up to 30 in one call. Thirty separate calls take thirty seconds and hit the limit twenty-nine times; one call takes one.
Page with pageSize, not with parallel calls. The listing tools accept up to 100 rows per page.
Total instead of paging. aggregate computes a sum, count or average over the whole filtered set in a single call — it exists precisely so you don’t page thousands of rows to add them up.
Reading a batch back doesn’t count as a write. createUserCards with a batchId spends the read budget for that tool, so following a batch you just queued never blocks the next creation.

Errors

Errors come back as a standard JSON-RPC 2.0 error envelope.

HTTP	JSON-RPC code	Meaning
`401`	`-32001`	`Unauthorized` — missing, invalid, or expired API key
`403`	`-32003`	Valid key, but it lacks the `mcp` scope (or `mcp_card_reveal` for a reveal)
`403`	`-32004`	Valid key, but this request’s IP isn’t in the key’s IP allowlist
`429`	`-32005`	`Rate limit exceeded` — see Rate limits
`405`	`-32000`	Method not allowed — this is a stateless server; only `POST /mcp` is supported

Request bodies are capped at 256 KB.

A missing mcp:write is not an HTTP error. The key is valid for the server, so the request succeeds and the refusal comes back as a normal tool result marked as an error — “This API key is not authorized to make changes”. Check the tool result, not the status code. The same goes for every other rejection a write tool reports: an unknown batchId, a card-issuer account you don’t own, bulk creation not being enabled, or a groupId that isn’t one of your groups.

Support

Happy to help if you get stuck:

Email: [email protected]
Dashboard: LootRush Dashboard

​What it is

​At a glance

​Connecting

​Claude Code

​Claude Desktop / Cursor / other JSON-configured clients

​Authentication

​Available tools

getAccountBalance

getUserCards

getUserCardTransactions

getCashbackSummary

getUserCardSummary

getUserCardBalanceMovements

getUserCardBalanceAutomation

getAccountHistory

aggregate

createUserCards

updateUserCard

updateUserCards

getCardGroups

getCardGroupJobs

getCardSpendReport

createCardGroup

updateCardGroup

moveCardToGroup

moveCardsToGroup

setCardGroupCardsStatus

deleteCardGroup

​getAccountBalance

​getUserCards

​Revealing card number & CVV

​getCardRevealPublicKey (reveal helper)

​getUserCardTransactions

​getCashbackSummary

​The four cashback balances

​getUserCardSummary

​getUserCardBalanceMovements

​getUserCardBalanceAutomation

​getAccountHistory

​aggregate

​Filtering and grouping by merchant

​Grouping by card nickname

​Grouping by card group

​Reading matched

​What each source can aggregate

​The datasetId handle

​Writing — creating and changing cards

​Write limits

​createUserCards

​updateUserCard

​updateUserCards

​Card groups

​getCardGroups

​getCardGroupJobs

​getCardSpendReport

​createCardGroup

​updateCardGroup

​moveCardToGroup

​moveCardsToGroup

​setCardGroupCardsStatus

​deleteCardGroup

​Access & scoping

​Rate limits

​Tips for staying under it

​Errors

​Support

What it is

At a glance

Connecting

Claude Code

Claude Desktop / Cursor / other JSON-configured clients

Authentication

Available tools

getAccountBalance

getUserCards

Revealing card number & CVV

getCardRevealPublicKey (reveal helper)

getUserCardTransactions

getCashbackSummary

The four cashback balances

getUserCardSummary

getUserCardBalanceMovements

getUserCardBalanceAutomation

getAccountHistory

aggregate

Filtering and grouping by merchant

Grouping by card nickname

Grouping by card group

Reading `matched`

What each source can aggregate

The `datasetId` handle

Writing — creating and changing cards

Write limits

createUserCards

updateUserCard

updateUserCards

Card groups

getCardGroups

getCardGroupJobs

getCardSpendReport

createCardGroup

updateCardGroup

moveCardToGroup

moveCardsToGroup

setCardGroupCardsStatus

deleteCardGroup

Access & scoping

Rate limits

Tips for staying under it

Errors

Support