mimirapi-mcp

Local BYO-wallet MCP stdio bridge to MimirAPI's paid shelf — pay-per-call tools for agents over x402 (USDC on Base). No API key, no signup: your wallet is the identity.

You run this on your own machine with your own wallet key. It wraps the zero-dependency mimirapi client, plugging an EIP-3009 signer (the standard @x402/* + viem libraries) into the client's Settler port. When a tool answers HTTP 402, the bridge checks its policy pins, signs a USDC authorization locally, and retries — your key never leaves the process and is never logged.

Runtime: Node ≥ 20 CLI. This package deliberately targets Node — it is a local bridge the buyer runs, not a Cloudflare Worker (the Factory Workers-runtime constraints do not apply here, same as this repo's scripts/). The exported modules still avoid Node built-ins so they can be reused from any runtime; only the un-exported cli bin entry touches process.

Quickstart

// .mcp.json (Claude Code) or claude_desktop_config.json (Claude Desktop)
{
  "mcpServers": {
    "mimirapi": {
      "command": "npx",
      "args": ["-y", "mimirapi-mcp"],
      "env": { "MIMIR_BUYER_WALLET_KEY": "${MIMIR_BUYER_WALLET_KEY}" }
    }
  }
}

Without a key the server still runs: the free tools work and every paid tool declines with a clear message instead of a payment.

Environment

| Variable | Default | Meaning | |---|---|---| | MIMIR_BUYER_WALLET_KEY | (unset) | Your EVM private key (hex, 0x optional). Unset ⇒ free tools only. Never logged, never echoed — diagnostics report its length only. | | MIMIRAPI_MAX_PRICE_USD | 0.25 | Hard per-call spend ceiling. A quote above it is refused before the signer ever sees the challenge. An unparseable value refuses to start (it never silently becomes a different ceiling). | | MIMIRAPI_ENABLE_SMS | (off) | Exactly true adds the sendSms tool. See below. | | MIMIRAPI_TOOL_ALLOWLIST | (all) | Comma-separated tool names; anything not listed is not exposed. An unknown name refuses to start (typo protection). | | MIMIRAPI_BASE_URL | https://mimirapi.com | Counter override for staging/testing. |

Policy before payment

Every pin runs before a payment signature exists. A challenge failing any pin is declined — nothing is signed, nothing is paid:

• Protocol pinned to x402 v2.
• Scheme pinned to exact.
• Network pinned to Base mainnet (eip155:8453).
• Asset pinned to native USDC on Base (0x833589fCD6eDb6E08f4c7C32D4f71b54bdA02913).
• Price capped per call by MIMIRAPI_MAX_PRICE_USD; an unknown or unparseable quoted price is never treated as free.

Successful paid calls return the counter's PAYMENT-RESPONSE settlement receipt (transaction hash, network, payer) as a second content block, so the calling agent can cite its own settlement evidence.

Tools

Mirrors the MimirAPI n8n node operation table; prices are the live catalog's (catalog re-checks them any time).

| Tool | Price | What it does | |---|---|---| | catalog | free | Every live SKU with price and input/output schema | | health | free | Counter liveness and SKU counts | | ping | $0.001 | Paid liveness probe — cheapest proof your payment wiring works | | qr | $0.002 | Deterministic QR SVG | | chart | $0.01 | 800×400 line/bar chart SVG | | ogImage | $0.01 | 1200×630 Open Graph card SVG | | visualReview | $0.01 | Real-browser screenshot + axe-core accessibility audit | | phoneIntel | $0.03 | Carrier/line-type intelligence for any number | | routePrice | $0.03 | Live token spot price, provider-routed and normalized | | walletScreen | $0.05 | Chainalysis sanctions-oracle read for an EVM address | | ephemeralDb | $0.25 | Real Postgres database with a TTL | | provenanceCert | $0.25 | Signed chain-of-custody license certificate | | x402Audit | $0.25 | Weigh any x402 counter end to end |

sendSms is off by default — deliberately

Sending SMS moves real carrier cash per call and is TCPA/10DLC-regulated, which makes it an abuse magnet through a broad automation surface. It is excluded from the default toolset (same ruling as the n8n node) and appears only when you set MIMIRAPI_ENABLE_SMS=true. If you enable it, consent for the recipient is on you. The allowlist can never add it — only the flag can.

Wallet hygiene

• Use a dedicated hot wallet holding spending money only — a few dollars of USDC on Base. Never a wallet that holds anything you would mind losing.
• No ETH needed: the exact scheme signs an EIP-3009 authorization and the seller's facilitator settles it, so the buyer pays no gas.
• The key stays in your process's environment. The bridge never logs it, never puts it in an error message, and reports presence by length only — this is pinned by tests (src/server.test.ts "key hygiene").
• Rotate by funding a fresh wallet and swapping the env var.

Programmatic use

import { buildServer } from 'mimirapi-mcp';

const { server, diagnostics } = buildServer({ env: process.env });
// connect `server` to any MCP transport; `diagnostics` is one stderr-safe line

createPinnedSettler is also exported on its own — a policy-pinned Settler for the mimirapi client, usable outside MCP entirely.

Provenance

Decision record: docs/decisions/2026-08-17-mimir-mcp-payment-story.md (ruling MCP-PAY1) — why a local BYO-wallet bridge and not a house wallet, prepaid keys, or in-band paid MCP tools.