# fry-x402-mcp

MCP server that exposes the [fry.farm x402 agentic actions API](https://fry.farm/x402/) as tools any MCP client (Claude Desktop, Claude Code, custom agents) can call.

- **15 pay-per-call endpoints** on Algorand mainnet, priced $0.001–$0.01 in USDC (ASA 31566704): 3 DeFi/DePIN data feeds + 12 transaction actions (staking, LP farming, Genesis NFT mint, P2P offers, submit, status).
- **Non-custodial**: build tools return **unsigned** atomic groups. Your agent signs with its **own** wallet and submits via `x402_submit`. fry.farm never holds keys.
- **No API keys, no accounts** — x402 (v2, scheme `exact`) payment is the only auth. Payments verify and settle through the [GoPlausible facilitator](https://facilitator.goplausible.xyz).
- **Catalog-driven**: tools are auto-generated at startup from the live, free [`/x402/catalog`](https://fry.farm/x402/catalog); `x402_catalog_refresh` picks up changes without a restart.

## Quickstart

```bash
git clone https://github.com/Fry-Foundation/fry-x402-mcp.git
cd fry-x402-mcp
npm install && npm run build
```

### Claude Desktop (`claude_desktop_config.json`)

```json
{
  "mcpServers": {
    "fry-x402": {
      "command": "node",
      "args": ["/absolute/path/to/fry-x402-mcp/dist/index.js"],
      "env": {
        "AGENT_MNEMONIC": "your 25-word agent wallet mnemonic",
        "MAX_PAYMENT_USDC": "0.05"
      }
    }
  }
}
```

### Generic MCP client (stdio)

Run `node dist/index.js` with the env vars below; speak MCP over stdio.

| Env var | Required | Default | Purpose |
|---|---|---|---|
| `AGENT_MNEMONIC` | for paid tools | — | The agent's OWN Algorand wallet (25 words). Signs x402 payments and is the `sender` for built groups. Without it only free tools work. |
| `MAX_PAYMENT_USDC` | no | `0.05` | Hard per-call spend ceiling; payment requirements above it are refused. |
| `ALGOD_URL` | no | public node | Override the Algorand node used by the payment client. |
| `ALGOD_TOKEN` | no | — | Sent as `X-Algo-API-Token` when set — required by token-gated nodes. |
| `FRY_X402_BASE` | no | `https://fry.farm` | Single API base (unprefixed tool names). |
| `FRY_X402_BASES` | no | — | Comma-list of API bases for multi-property use. Each base's tools are prefixed with a short property tag (`x402_farm_fleet`, `x402_market_market_collections`, …) so multiple catalogs coexist without collisions. Takes precedence over `FRY_X402_BASE`. |

### Multi-property example (Claude Desktop `env`)
```json
"FRY_X402_BASES": "https://fry.farm,https://fry.market",
"ALGOD_TOKEN": "<node token if required>"
```

## Tools

| Tool | Price | What it does |
|---|---|---|
| `x402_catalog` | free | Live catalog: endpoints, prices, params, payment requirements |
| `x402_catalog_refresh` | free | Re-fetch catalog, regenerate tools |
| `x402_fleet` | $0.01 | DePIN device-staking pool telemetry |
| `x402_farm` | $0.008 | Farming/pool analytics (pools, TVL, positions) |
| `x402_rewards` | $0.005 | FRY reward emission, daily budget, leaderboard |
| `x402_staking_stake` / `x402_staking_unstake` / `x402_staking_claim` | $0.01 | Build FryStaking V3 groups |
| `x402_lp_farm_stake` / `x402_lp_farm_unstake` / `x402_lp_farm_claim` | $0.01 | Build FryFarming groups |
| `x402_genesis_mint` | $0.01 | Build Genesis NFT mint group (currently paused on-chain) |
| `x402_p2p_create` / `x402_p2p_accept` / `x402_p2p_cancel` | $0.01 | Build P2P offer groups |
| `x402_submit` | $0.005 | Submit a signed group; waits ≤8 rounds |
| `x402_status` | $0.001 | Tx status by txid |

Typical agent journey: `x402_catalog` → `x402_staking_stake` (returns unsigned group) → sign locally → `x402_submit` → `x402_status`.

## Security notes — read before configuring

- `AGENT_MNEMONIC` is the **agent's** wallet, not your main wallet. Fund it with only what the agent should be able to spend (USDC for x402 fees + the amounts it will transact + ALGO for txn fees).
- The mnemonic is read once from the environment and held in process memory only — never logged, never written to disk, never sent anywhere. Payments are signed locally; only signed payment payloads leave the process.
- `MAX_PAYMENT_USDC` caps each x402 payment client-side. On-chain action amounts (stake sizes etc.) are separate — they are whatever your agent asks to build and sign.
- Every paid response includes the `paymentReceipt` header content when the facilitator settles the payment.

## License

MIT © Fry Foundation