# 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](https://facilitator.goplausible.xyz/discovery/resources): 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

| Tool | What it does |
|---|---|
| `discover_services` | Curated, junk-filtered catalog of live paid x402 services (with trust tiers) |
| `get_service` | Inspect one service: price, input/output schema, settle count |
| `check_trust` | Trust Index report for any endpoint — uptime history, latency, conformance, tier |
| `call_paid_service` | Pay a service in USDC and return the result + on-chain receipt. Optionally via Caravan's **relay** (failed calls are never charged) |
| `get_policy` / `set_policy` | The Quartermaster spend policy: per-call cap, daily budget, call count, minimum trust tier, allow/deny lists, human-approval threshold |
| `get_ledger` | Append-only audit ledger of every payment, block, and approval |
| `wallet_status` / `create_wallet` | Balance / opt-in status; generate a local wallet |

**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).

## Install (2 minutes)

```bash
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):

```json
{
  "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

| Variable | Default | Purpose |
|---|---|---|
| `CARAVAN_MNEMONIC` | — | 25-word Algorand mnemonic of the paying wallet (required for paid calls) |
| `CARAVAN_NETWORK` | `mainnet` | `mainnet` or `testnet` |
| `CARAVAN_GATEWAY` | `https://caravan-sable-nine.vercel.app` | Gateway used for the Trust Index and the relay |
| `CARAVAN_HOME` | `~/.caravan` | Where the policy and ledger are stored |

## How payments work

x402 v2 over the [GoPlausible facilitator](https://facilitator.goplausible.xyz): 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