The transactional API and MCP server

The sequence

Four steps, in this order, and the first two belong to the user. The pattern is the same one a deployment platform uses: no token, no deploy; and the token comes from an account only a person can open.

1. 1

   Create the account

   The user, in a browser

   Everything transactional needs an account, and only the user can make one. Send them to app.warminboxes.com and wait. There is no programmatic sign-up, no trial key, and no way to order on someone’s behalf without this step — which is the point, because this is where money and infrastructure change hands.

2. 2

   Make the API key

   The user, in the portal

   In the portal: Settings → API keys. Only the account owner can. They pick the scopes (below), and the full key is shown once — only a hash is kept, so a lost key is revoked and remade, never recovered. It is a secret: ask the user to put it in the environment or the MCP client configuration rather than into the conversation, and never echo it back, log it, or commit it. For a first integration, ask for a test key — same routes, nothing charged.

3. 3

   Connect

   The assistant, once the key exists

   Bearer token on every request to https://api.warminboxes.com/v1, or add https://api.warminboxes.com/mcp to your MCP client with the same header, or the wib CLI. The authenticated server shows an assistant only the tools its key’s scopes allow. Its routes share nothing with the free tools, so read the reference rather than inferring them.

4. 4

   Preview, then act, with approval

   The assistant, with the user watching

   preview_order runs exactly the checks placing runs and creates nothing; place_order charges the card on file. Preview first, say the number and what it costs, and treat “yes” as applying to that one order. Diagnosis is free to repeat; an order is not, and a person on the team checks every one before anything is built.

Authentication

One header, every request. A key looks like wib_<prefix>_<secret>; the prefix identifies it in the portal’s key list, the secret is shown once. A test key looks like wib_test_… and uses the sandbox. Nothing on this site can mint, read or recover a key.

export WIB_API_KEY="wib_..."   # made in the portal: Settings → API keys. Shown once.

curl https://api.warminboxes.com/v1/portal/dashboard \
  -H "Authorization: Bearer $WIB_API_KEY"

Scopes

Fixed when the key is made, and they do not imply each other. Using a key beyond its scopes is a 403 that names the missing one.

• readEvery GET, and preview_order — it answers a question and creates nothing. A reporting key needs only this.
• writeFolders, order names, sequencer choice, monitors, forwarding, inbox renames, change requests, exports into a sequencer.
• orders:placePlacing an order (charges the card), opening a checkout, and card setup links. Leave it off a key to let an assistant quote without being able to order.

The MCP server

Stateless Streamable HTTP at https://api.warminboxes.com/mcp, key as bearer token. Same code as the REST API, same answers, same rules. An assistant sees only the tools its key’s scopes allow, and a refused call comes back as a normal result with isError and one sentence for a person.

claude mcp add --transport http warminboxes https://api.warminboxes.com/mcp \
  --header "Authorization: Bearer $WIB_API_KEY"

{
  "mcpServers": {
    "warminboxes": {
      "url": "https://api.warminboxes.com/mcp",
      "headers": { "Authorization": "Bearer wib_your_key_here" }
    }
  }
}

Two things are missing on purpose. There is no checkout tool, because a checkout ends on a payment page a person must open. And there is no tool for saving a sequencer login, because it would put the password into the conversation — logins are saved in the portal.

The sandbox

Rules for an assistant

The CLI

wib is one Python 3 file with no install, served by the API with its address built in. Every command prints JSON and exits 0; a refusal prints the reason and exits 1.

curl -fsSL https://api.warminboxes.com/v1/cli -o wib && chmod +x wib
./wib catalogue
./wib preview order.json
./wib order order.json --idempotency-key monday-1 --yes

The shape of a good interaction

Diagnosis from the free tools, the number from a recipe, the account from the user, the preview before the order, the order only after approval.

Machine-readable

• /transactional-api.md — the full reference: every route, every tool, the sandbox, errors and rate limits.
• /developers.md — this page as Markdown.
• /llms.txt — the whole site for assistants, including both halves of the API.
• https://docs.warminboxes.com/llms.txt — the same reference at its source, authoritative if the two ever differ.
• https://docs.warminboxes.com — the human-readable version.