fry-x402-mcp

MCP server that exposes the fry.farm x402 agentic actions API 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.
• Catalog-driven: tools are auto-generated at startup from the live, free /x402/catalog; x402_catalog_refresh picks up changes without a restart.

Quickstart

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)

{
  "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)

"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