CajaGuard

A local spend gate for shopping agents. CajaGuard is an MCP proxy that sits in front of a commerce MCP server speaking the Universal Commerce Protocol (UCP) shopping tools, the same tool names Shopify documents for its Cart, Checkout and Global Catalog MCP servers. Every tool passes through, except complete_checkout. That one is checked against per-currency spend caps, a rolling window, a merchant allowlist and, above a threshold, a signed, single-use, expiring human approval. In test mode it also refuses anything that looks like a real card number or a live token before the shop sees it.

The problem

Shopping MCP servers can now create checkouts and place orders, so an agent that can browse can also pay. Teams wiring this up need proof, before any live payment credential is in play, that a human signs off above a limit, that splitting a basket does not get around it, and that a test setup never carries a real card. CajaGuard is a small, local, keyless way to get that proof against a fixture shop with the real tool shapes.

Related MCP server: acuris-agent-guard

What the real tools look like (verified 2026-10-21)

So complete_checkout is the one call that uses a payment credential and places an order. That is what CajaGuard gates.

How it works

flowchart LR
  agent[Agent] -->|UCP tools| cg[cajaguard mcp]
  cg -->|search / cart / create / update checkout| shop[commerce MCP server<br/>fixture in this repo]
  cg -->|complete_checkout| scan{test mode:<br/>real-looking credential?}
  scan -->|yes| deny[denied]
  scan -->|no| read[get_checkout from the shop<br/>business-owned total + currency]
  read --> rules{units, merchant, currency,<br/>per-transaction cap, rolling window}
  rules -->|fail| deny
  rules -->|over threshold or live mode| sig{valid signed approval<br/>for this exact payment?}
  rules -->|under threshold| shop
  sig -->|yes, once| shop
  sig -->|no| blocked[blocked + request id]
  human[Human] -->|cajaguard approve id| file[(Ed25519 approval)]
  file --> sig

1. Read, don't trust. On complete_checkout, CajaGuard calls the shop's own get_checkout and takes the total, currency, status and merchant from it. If the agent sends totals, currency or line_items on complete, the call is refused, because UCP marks those fields omit.

2. Units. Every amount must be a safe non-negative integer in minor units. A shop that reports 49.99 instead of 4999 is refused (fail closed). Caps are configured as strings in major units ("100.00") and converted with the ISO 4217 exponent; "50.005" USD is a config error. A currency without caps is refused and never converted.

3. Caps. A per-transaction cap and a rolling-window cap per currency are hard limits that no approval can lift. Completed spend, including approved spend, counts toward the window, so four USD 45.00 checkouts cannot get under a USD 50.00 threshold and past a USD 150.00 window.

4. Merchant allowlist. The merchant is the host of the shop-authored continue_url (else the first links[] URL).

5. Approval. Above approval_above (or always, in mode: "live"), the gate writes a pending request whose id comes from a SHA-256 digest of merchant, checkout id, currency, total, line items and payment handlers. A human runs cajaguard approve <id>. The CLI re-reads the checkout from the shop, refuses if it changed, shows it, asks y/N and writes an Ed25519-signed approval with an expiry. The gate accepts it once: the approval is spent before the payment call, so a decline cannot be replayed.

6. Test-mode tripwire. In mode: "test", every tool call's arguments are scanned. Instruments must use an allowlisted test handler, tokens must match the test pattern, raw pan/network_token/card credentials are refused, Luhn-valid card numbers anywhere (including free text) are refused, and secret-like fields with a live segment are refused. None of it reaches the shop.

Quickstart (keyless demo)

Needs Bun 1.4.3 (Node 24 in .nvmrc). Everything runs against the fixture shop in fixtures/, whose merchants use the reserved .example domain.

bun install --frozen-lockfile
bun run cajaguard keygen                                   # approver key in ~/.config/cajaguard (0600)
bun run demo buy "Trail socks" 2                           # USD 24.00: allowed, order placed
bun run demo buy "Day pack"                                # USD 89.00: blocked, prints cg-<id> and the checkout id
bun run cajaguard approve cg-<id> --config examples/cajaguard.demo.json   # re-reads the checkout, asks y/N, signs
bun run demo pay gid://fixture/Checkout/<n>                # allow_approved, order placed
bun run demo pay gid://fixture/Checkout/<n>                # denied: checkout already completed
bun run demo buy "Rain shell" --token "4111 1111 1111 1111"   # denied: test_mode_credential
bun run cajaguard status --config examples/cajaguard.demo.json

State (requests, approvals, spend ledger, audit log, fixture checkouts) lives in .cajaguard/, which is gitignored. Run the full local gate with bun run check.

MCP server

bun run cajaguard mcp --config examples/cajaguard.demo.json starts the stdio proxy (client config in examples/mcp-servers.json). It spawns the downstream server named in the config and lists its UCP tools plus:

Any other downstream tool is hidden and refused (tool_not_allowed). No tool can approve.

Verdicts: allow (within_caps), allow_approved (signed_approval), blocked (pending_approval, approval_expired, approval_untrusted_key, approval_bad_signature, approval_already_used, ...), denied (over_per_transaction_cap, over_window_cap, merchant_not_allowed, currency_not_allowed, amount_not_minor_units, request_field_not_allowed, checkout_not_ready, test_mode_credential, approval_denied, bad_request, tool_not_allowed).

Config

{
  "mode": "test",
  "home": "../.cajaguard",
  "downstream": { "command": "bun", "args": ["fixtures/commerce-server.ts"], "cwd": "..", "env": {} },
  "merchants": ["demo-outfitters.example", "tokyo-tea.example"],
  "caps": {
    "USD": { "approval_above": "50.00", "per_transaction": "100.00", "window": "150.00" },
    "JPY": { "approval_above": "5000", "per_transaction": "12000", "window": "20000" }
  },
  "window_hours": 24,
  "approvals": { "trusted_keys": ["~/.config/cajaguard/approver.pub.pem"], "max_ttl_minutes": 15 },
  "test_mode": { "handler_ids": ["fixture_test_handler"], "token_pattern": "^cg_test_[A-Za-z0-9_]{8,}$" }
}

mode: "live" drops the test-token rules and requires a signed approval for every complete_checkout, whatever the amount. It is tested only against the fixture shop (see Limits).

CLI

Measured

Produced by bun run report (scripts/report.ts) from a real keyless run: real Ed25519 keys and signatures, the real file store, the fixture shop in-process for the scenarios and over stdio for the MCP timing. Source: reports/cajaguard.md, reports/cajaguard.json. "Reached shop" means the complete_checkout call was forwarded to the shop.

Generated by bun run report on 2026-10-21 (Bun 1.4.3, @modelcontextprotocol/sdk 1.32.1, UCP spec v2026-08-25). Fixture shop only, real Ed25519 keys.

Caps: USD approval above 50.00, per transaction 100.00, window 150.00 / 24h; JPY approval above 5000, per transaction 12000, window 20000 / 24h.

Scenarios as expected: 25/25.

MCP proxy spawn + initialize + tools/list (also spawns the fixture shop): 321.4 ms.

Keys and environment

No API keys. Nothing here talks to a real store, a payment provider or the network; CI runs the same keyless gate. No .env is needed (.env.example lists the one optional variable).

Limits

• Fixture shop, not Shopify. Tool names and argument shapes follow the pinned UCP spec and Shopify's docs, and tests check the fixture's required params against mcp.openrpc.json. The fixture's catalog responses are simplified, and its totals only have subtotal and total (no tax, shipping or discounts). Nothing was run against a real Shopify store, Checkout MCP's Bearer-token auth, or a real payment handler.

• Shop Pay tokens are not recognized as such. The idea talks about "live Shop Pay tokens". We could not verify a Shop Pay credential or token format in the UCP spec or Shopify's docs. CajaGuard blocks them indirectly: in test mode only allowlisted test handlers and cg_test_... tokens pass, so a shop_pay instrument is refused by handler id. In live mode every payment needs a human signature.

• The tripwire is pattern based. Luhn card numbers, live segments in secret-like fields, raw card credential types and non-matching tokens. A real token with no recognizable shape, sent with an allowlisted test handler id, would pass the scan if it matched your token pattern. Keep the pattern strict.

• The approver key and .cajaguard/ are the trust root. An agent that can read the key, or write the config, spend ledger or consumed.jsonl, can get around the gate. See SECURITY.md.

• Only calls through the proxy are gated. An agent with the shop endpoint, a browser or a stored card has other ways to pay.

• The shop's numbers are trusted. Price and currency come from get_checkout. If a shop charges more than it reported, CajaGuard records the higher total and logs a mismatch after the fact; it cannot undo a charge.

• Window is per currency, across merchants, local to one machine. There is no FX conversion and no shared ledger across agents or hosts.

• Approval is a terminal prompt. No phone or Slack approval flow, and MCP elicitation is not used since a client could answer it without a human. --yes exists for scripted demos.

• Default caps are examples, not a recommended policy.

Credits

• Universal Commerce Protocol (Apache-2.0): spec files vendored in spec/ucp/

• Model Context Protocol TypeScript SDK (MIT)

• gethelio/helio (Apache-2.0): the MCP governance proxy with spend budgets and approvals that inspired this lab; not bundled or called

• Building blocks from the SkilledDragon labs blastconfirm-gate and agent-flight-recorder (see NOTICE)

Not affiliated with Shopify, the Universal Commerce Protocol project, Helio, Anthropic or the Model Context Protocol project.

License

Apache-2.0. See LICENSE and NOTICE. Contact: hello@skilleddragon.com.

Built by SkilledDragon LLC, skilleddragon.com