Caravan MCP

Give Claude, Cursor, or any MCP client a wallet and the whole Algorand x402 Bazaar — safely.

Caravan is the safety layer of the Algorand x402 Bazaar: every paid endpoint gets a trust score from 2-hourly patrols, every merchant gets verified by purchase, and every payment your AI makes runs through a spend policy it cannot talk its way around.

This repo is the MCP connector. The trust patrols, verification robots, and paid gateway live at https://caravan-sable-nine.vercel.app (live economy, receipts on-chain).

What your AI gets

Default policy: max $0.25 per call · $1.00 per day · 200 calls per day · anything above $0.10 needs human approval · endpoints tiered Unreachable are refused. The model cannot forge approvals (HMAC tokens bound to host + price, 10-minute window).

Related MCP server: Tilde x402 MCP Server

Install (2 minutes)

git clone https://github.com/OJ-IRO/caravan-mcp
cd caravan-mcp && npm install && npm run build
npm run gen-wallet        # prints an Algorand address + writes the mnemonic to .env

Fund the wallet with a little ALGO (network fees) and USDC on Algorand. Sub-cent calls mean $5 lasts a long time. To try it with free faucet money first, use CARAVAN_NETWORK=testnet and the faucets at https://lora.algokit.io/testnet/fund (ALGO) and https://faucet.circle.com (USDC → "Algorand Testnet").

Add to your MCP client config (Claude Desktop: claude_desktop_config.json; Cursor: MCP settings):

{
  "mcpServers": {
    "caravan": {
      "command": "node",
      "args": ["/absolute/path/to/caravan-mcp/dist/mcp/server.js"],
      "env": {
        "CARAVAN_MNEMONIC": "<25-word mnemonic from .env>",
        "CARAVAN_NETWORK": "mainnet"
      }
    }
  }
}

Restart the client. Ask your AI: "Find me a paid weather API on Algorand and check its trust score before you buy."

Environment

How payments work

x402 v2 over the GoPlausible facilitator: the service answers 402 with its price, the connector checks the Quartermaster policy against the real quoted price, signs an exact-amount USDC transfer, and retries with the payment header. Settlement is on Algorand; the receipt (txid) is returned to the model and written to the ledger.

Safety model

• Policy is evaluated on the quoted price, not the model's claim.

• Approval tokens are HMAC-signed by the server for a specific host + price; the model cannot mint them.

• The ledger is append-only and lives outside the model's reach.

• Trust tiers come from independent patrols, not merchant self-description.

License

MIT