macaroonnetwork-mcp

MCP client for Macaroon Network — a marketplace where AI agents discover and pay for live data.

Payment rail status, read before use: the live marketplace's primary payment rail is x402 (USDC on Base mainnet) — nearly every listing is settled that way today. L402 (Bitcoin Lightning) is also supported but is inactive for most live listings. This package's buyer code handles both: macaroons_execute understands the real x402 challenge shape (a base64-JSON payment-required header carrying accepts[] terms) exactly as it arrives from the live registry, alongside the existing L402 www-authenticate flow — whichever rail a listing actually gates on, this package raises the matching typed result instead of an unhandled 402. As with L402, this package never holds a wallet or signs anything itself for x402 either: it hands back the real payment terms for you to sign with your own wallet/CDP infrastructure. (Note: this x402 support has not yet been published to PyPI as of this writing — pip install macaroonnetwork-mcp still gets the L402-only 0.2.0 release until the next publish; build from this repo's mcp-distribution/ if you need it now.)

What this does

Four tools:

• macaroons_search — semantic search over the live marketplace registry by natural-language intent, including Christian evidence capabilities. Free.
• macaroons_metadata — free freshness/content-hash metadata for a feed target, before deciding whether to buy. Free.
• macaroons_purchase — pays via the Lightning L402 rail (feed-changes purchases only; see "Paying" below).
• macaroons_execute — pays via whichever rail the target listing actually uses, x402 or L402, and receives the real, predicate-verified result. See "Paying" below — by default this package holds no wallet and doesn't attempt payment for you on either rail.

Paying

This package never holds a private key or wallet credential by default, on either payment rail.

x402 (USDC on Base) — macaroons_execute only

When an x402-gated listing needs payment, macaroons_execute returns an x402_payment_required result instead of failing:

{
  "x402_payment_required": true,
  "resource_url": "https://api.macaroonnetwork.com/execute/...",
  "amount_atomic": "3000",
  "asset": "0x833589fCD6eDb6E08f4c7C32D4f71b54bdA02913",
  "network": "eip155:8453",
  "pay_to": "0x33cc...",
  "extra_name": "USD Coin",
  "extra_version": "2",
  "max_timeout_seconds": 60,
  "x402_version": 2,
  "instructions": "Sign an exact x402 payment of amount_atomic atomic units of asset on network to pay_to with your own wallet/CDP infra, then call this same tool again with identical arguments PLUS payment_signature set to the resulting signed proof."
}

Sign the exact-scheme USDC payment described above with your own wallet or Coinbase CDP infrastructure, then call macaroons_execute again with identical arguments plus payment_signature set to the resulting signed proof. Unlike the L402 flow below, this is a single retry — x402's "exact" scheme settles synchronously, there's no invoice-polling step.

L402 (Bitcoin Lightning)

When an L402-gated listing needs payment, macaroons_purchase/ macaroons_execute return a payment_required result instead of failing:

{
  "payment_required": true,
  "invoice": "lnbc...",
  "macaroon": "eyJ...",
  "amount_msat": 250000,
  "instructions": "Pay this BOLT11 invoice with your own Lightning wallet, then call this same tool again with identical arguments PLUS resume_macaroon set to the macaroon above."
}

Pay the invoice with whatever Lightning wallet you actually have, then call the same tool again with resume_macaroon set to the macaroon above. A plain retry without resume_macaroon mints a brand-new invoice instead of resuming the one you just paid — always pass it back.

If you run your own real LND node and want this package to auto-pay from it instead of returning payment_required, set:

MACAROONS_BUYER_LND_MODE=external
LND_BUYER_HOST=your-node:10009
LND_BUYER_TLS=/path/to/tls.cert
LND_BUYER_MACAROON=/path/to/admin.macaroon

This shells out to a real lncli binary on your machine — install LND's lncli separately, it isn't bundled here. There is no equivalent auto-pay mode for x402: no offline/local-key signing path exists in this package for either rail, by design (see the payment-rail status note above).

Install

pip install macaroonnetwork-mcp

Use with an MCP client

{
  "mcpServers": {
    "macaroonnetwork": {
      "command": "macaroonnetwork-mcp"
    }
  }
}

Talks to https://api.macaroonnetwork.com by default. Override with MACAROONS_REGISTRY_URL / MACAROONS_FEED_URL env vars to point at a local dev stack instead. MACAROONS_SESSION_BUDGET_SATS (default 1000) caps total spend per server process; each tool call also takes a max_spend_sats per-call cap (default 100).

License

MIT