Arcagentx402 MCP Server

CRA AGENT

Payments for AI agents on Arc, Circle's USDC-native L1. One tool call and an agent can buy an API call for a fraction of a cent: the rail reads the x402 price, applies a spending policy the model cannot change, verifies the seller, pays gas-free through Circle Gateway, and writes the receipt to a ledger.

TypeScript monorepo, npm workspaces, Node 22. Site: cra-agent.tech.

Status: the buyer agent, the seller middleware and the MCP server are built and exercised end to end on Arc testnet. See docs/arc-verification.md for every value verified against docs.arc.io.

Packages

Setup

nvm use            # Node 22
npm install
cp .env.example .env   # then set DATABASE_URL and ARC_RPC_URLS
npm test
npm run db:migrate
npm run collector
npm run web:build && npm run api   # http://localhost:8791

Local Postgres (Homebrew, keg-only):

LC_ALL=en_US.UTF-8 /opt/homebrew/opt/postgresql@17/bin/pg_ctl -D /opt/homebrew/var/postgresql@17 -l /opt/homebrew/var/postgresql@17/server.log start

The agent

# .env: CRA_NETWORK=arc, CRA_KEY_FILE=.secrets/agent.key (chmod 600), CRA_POLICY=…
npm run rail -- policy
npm run rail -- quote https://api.cra-agent.tech/v1/paid/fees/forecast
npm run rail -- deposit 1      # wallet USDC into the Gateway balance
npm run rail -- pay   https://api.cra-agent.tech/v1/paid/fees/forecast
npm run rail -- ledger
npm run mcp                    # MCP server on stdio

npm run rail -- identity-register https://cra-agent.tech/.well-known/agent.json   # ERC-8004, costs gas
npm run rail -- job status 1                                                      # ERC-8183

As an MCP server, for any MCP client:

{ "mcpServers": { "cra-agent": {
    "command": "cra-agent-mcp",
    "env": {
      "CRA_NETWORK": "arc",
      "CRA_KEY_FILE": "/etc/cra-agent/agent.key",
      "CRA_POLICY": "daily=5,per_seller=0.5,per_payment=0.05,identity=required"
    }
} } }

The policy is read from the environment, not from the conversation: the model cannot raise its own limit, and never sees the key.

Selling

import { createSeller } from "@cra-agent/seller";

const seller = createSeller({ sellerAddress, network: "arc" })
  .route("GET /v1/forecast", "$0.001", { description: "Weather forecast, per call" });

app.use(seller.middleware());   // Hono; createExpressSeller() for Express

Setting SELLER_ADDRESS in .env turns on our own paid routes: the API then serves /v1/paid/* (catalogue at /v1/paid) priced per call, described for agents at /openapi.json.

A route can also be offered on a second network at the same price. The x402 discovery catalogues are filled by the facilitator that settles a payment, and no facilitator settles Arc except Circle's, which does not catalogue: DISCOVERY_FACILITATOR_URL (or CDP_API_KEY_ID / CDP_API_KEY_SECRET) adds that rail, and scripts/pay-on-network.mts <url> [network] buys a route there once so the catalogue picks it up. The Arc rail is untouched and our own buyer keeps choosing it.

Two guarantees worth knowing

• A broken endpoint costs the buyer nothing. x402's default flow verifies the payment, runs the handler, and settles only if it succeeded. Our own API exposes GET /v1/paid/selftest/fail, a priced route that always answers 500, so anyone can check it: the response is 500, the receipt reads not_charged, and the Gateway balance does not move.
• Every receipt can be checked by someone who was not there. It carries the limits the payment passed under and what had already been spent, and it is signed with the agent's key (EIP-712). cra-agent verify receipt.json recovers the signer and redoes the arithmetic, with no key and no network. Be clear about what that proves: the agent's key issued this statement and nobody altered it since. It is the rail vouching for its own decision. The independent half is the settlement.
• Every settled payment ends with a transaction anyone can check. Circle Gateway settles in batches, so the transfer reaches the seller after the response. cra-agent proof (MCP: arc_proof) matches settled payments to the on-chain USDC transfer that carried them and stores the hash in the ledger.

Collector

• Head worker: follows the chain head (250 ms poll), ingests in batches (two JSON-RPC calls per block: the full block and all its receipts), keeps a contiguous cursor in collector_state.
• Backfill worker: fills the history down to block zero and any gap the head left behind, at low priority; it pauses whenever the head worker falls behind.
• Scanner: every 10 minutes, looks for numeric holes and parent_hash discontinuities. Never auto-fixes.
• Probe: every 5 seconds asks every endpoint for latest, finalized and safe, storing head_observations (per-provider lag and latency) and evaluating alerts.
• Enrich: revert reasons by replaying failed transactions with eth_call against the parent block; runtime bytecode size and hash for deploys.
• Startup guard: every endpoint must report the expected chain id and the same genesis hash; the database binds itself to that genesis and refuses any other chain.
• Prices: for every watched pair (EURC, and the project token when TOKEN_ADDRESS is set) it records each swap against USDC at the rate it executed. Transfers are netted per pair of addresses, so a token that taxes transfers is priced correctly, and a hop that merely forwarded what it was handed is skipped instead of guessed. Served at /v1/fx?symbol= and, with the size curve and venues, at /v1/paid/fx/execution.
• Modes: COLLECTOR_MODE=light (default: blocks, per-block stats by operation, deploys, RPC observations, around 0.5 GB/day) or full (also transactions, receipts, logs and reverts).
• Health: GET :8790/health (JSON, 503 when lagging or stalled), GET :8790/metrics (Prometheus).
• Alerts: log plus optional Telegram on lag, stall, all RPCs down, open gaps, low disk.

Database summary: npm run status -w @cra-agent/collector.

Deploy

deploy/setup.sh installs everything on an Ubuntu VPS running Caddy (Node 22, Postgres 17, systemd units for the collector and the API, a Caddy site). See deploy/README.md.

Tests and migrations

• npm test runs the vitest suites in packages/*/test: property tests on the accounting module (fast-check), block parsing, RPC pool failover, spend policy, rail choice, signing, escrow mapping. CI runs them on every push together with a ledger round-trip against a real Postgres.
• Migrations live in packages/collector/sql/NNN_*.sql and are applied in order by packages/collector/src/db/migrate.ts (table schema_migrations), automatically when the collector starts or via npm run db:migrate. The ledger has its own in packages/ledger/sql, applied by PgLedger.migrate().

Publishing

npm login
scripts/publish.sh --dry-run   # then without the flag

House rules

• No arithmetic on USDC amounts outside packages/accounting.
• No mainnet deployment without explicit confirmation.
• Keys and API keys only in .env (git-ignored) or a file with chmod 600, never in chat or in code.

License

MIT.