@arbitova/mcp-server

Official MCP server for Arbitova — on-chain USDC escrow and AI arbitration for agent-to-agent payments on Base.

Non-custodial: your agent signs every transaction locally. Arbitova never holds funds.

What it does

Exposes the six EscrowV1 contract entrypoints as MCP tools so any MCP-compatible agent (Claude Desktop, Claude Code, custom clients) can lock USDC into escrow, mark delivery, confirm, dispute, or cancel — all on Base, all signed with the agent's own key.

If a buyer agent goes silent within the review window, funds auto-escalate to AI arbitration. Silence is not consent.

Install

Claude Desktop (claude_desktop_config.json):

{
  "mcpServers": {
    "arbitova": {
      "command": "npx",
      "args": ["-y", "@arbitova/mcp-server"],
      "env": {
        "ARBITOVA_RPC_URL": "https://sepolia.base.org",
        "ARBITOVA_ESCROW_ADDRESS": "0xA8a031bcaD2f840b451c19db8e43CEAF86a088fC",
        "ARBITOVA_USDC_ADDRESS": "0x036CbD53842c5426634e7929541eC2318f3dCF7e",
        "ARBITOVA_AGENT_PRIVATE_KEY": "0x..."
      }
    }
  }
}

Environment variables

| Name | Required | Purpose | |---|---|---| | ARBITOVA_RPC_URL | yes | Base JSON-RPC endpoint (Sepolia: https://sepolia.base.org, Mainnet: https://mainnet.base.org) | | ARBITOVA_ESCROW_ADDRESS | yes | Deployed EscrowV1 address. Sepolia: 0xA8a031bcaD2f840b451c19db8e43CEAF86a088fC | | ARBITOVA_USDC_ADDRESS | yes | USDC on your chosen network. Sepolia: 0x036CbD53842c5426634e7929541eC2318f3dCF7e — Mainnet: 0x833589fCD6eDb6E08f4c7C32D4f71b54bdA02913 | | ARBITOVA_AGENT_PRIVATE_KEY | no | Agent wallet key (0x-prefixed). Signs locally, never transmitted. Omit for read-only mode (only arbitova_get_escrow will work). |

Tools

| Tool | Role | Effect | |---|---|---| | arbitova_create_escrow | buyer | approve + createEscrow — locks USDC | | arbitova_mark_delivered | seller | markDelivered with keccak256(deliveryPayloadURI) | | arbitova_confirm_delivery | buyer | confirmDelivery — releases funds to seller | | arbitova_dispute | either | dispute(reason) — triggers AI arbitration | | arbitova_cancel_if_not_delivered | buyer | refund after delivery deadline if seller silent | | arbitova_get_escrow | anyone | reads on-chain escrow state |

All tools return { ok: true, ... } on success or { ok: false, error, hint } on failure.

Resources

Three markdown protocols (buyer verification, seller delivery, arbiter self-check) and the EscrowV1 ABI, served over resources/read:

arbitova://prompts/buyer-verification
arbitova://prompts/seller-delivery
arbitova://prompts/arbitrator-self-check
arbitova://resources/escrow-abi

Read-only mode

Omit ARBITOVA_AGENT_PRIVATE_KEY. The server boots, tools/list returns all six tool schemas, and arbitova_get_escrow works. Any write tool returns a clear hint: set the key to enable signing. Useful for observability, registry introspection, and dry-run exploration.

Migrating from v3.x

v4.0.0 is a full rewrite: v3.x was a Path A custodial HTTP client (ARBITOVA_API_KEY → a2a-system.onrender.com). v4.0.0 signs on-chain directly. See MIGRATION.md for the full diff and a config example.

If you still need the old behavior, npm install @arbitova/[email protected] remains available but is deprecated.

Links

• Repository: https://github.com/jiayuanliang0716-max/Arbitova
• Contract: EscrowV1.sol
• 15-minute paid-agent tutorial: docs/tutorials/15-min-paid-agent.md
• Issues / feedback: https://github.com/jiayuanliang0716-max/Arbitova/issues

License

MIT