@zerohooktrade/mcp

A Model Context Protocol server that lets an agent trade on Robinhood Chain (chain id 4663) through the Zerohook routing engine (@zerohooktrade/sdk), under a spending policy enforced before any calldata leaves the server.

• Read-only and calldata only. The server never holds a key, never signs and never sends. The agent's own wallet signs what build_swap returns.

• Best price across Uniswap v3 (all four fee tiers), v4 and hooked v4 pools, with splits and two-hop routes through USDG or ETH.

• Spending policy: per-trade cap, rolling 24 h cap, token allowlist, max slippage, max price impact, pinned contracts and hooks, and an eth_call simulation from the agent wallet. The same rules as the agent-mode page of the app; the policy JSON it exports loads here unchanged.

• stdio transport. Logs go to stderr only.

Links: app dapp.zerohook.trade · docs docs.zerohook.trade · site zerohook.trade.

Install

The server depends on the SDK as a sibling folder (file:../zhook-sdk):

git clone https://github.com/zerohooktrade/zhook-sdk.git
git clone https://github.com/zerohooktrade/zhook-mcp.git
(cd zhook-sdk && pnpm install && pnpm build)
cd zhook-mcp && pnpm install && pnpm build

Requires Node 20 or later.

Related MCP server: @krypsisnetwork/mcp

Connect an MCP client

Any client that launches stdio servers works. A typical mcpServers entry:

{
  "mcpServers": {
    "zerohook": {
      "command": "node",
      "args": ["/absolute/path/to/zhook-mcp/dist/index.js"],
      "env": {
        "ZHOOK_POLICY_FILE": "/absolute/path/to/policy.json",
        "ZHOOK_LEDGER_FILE": "/absolute/path/to/spend-ledger.json"
      }
    }
  }
}

Configuration

The SDK's bundled default pool set is always loaded; the pools file and discovery add to it.

Spending policy

{
  "name": "trading-agent",
  "perTradeUsd": 250,
  "dailyUsd": 1000,
  "allowlist": [
    { "symbol": "ETH", "address": "ETH" },
    { "symbol": "USDG", "address": "0x5fc5360D0400a0Fd4f2af552ADD042D716F1d168" }
  ],
  "allowVerifiedStockTokens": false,
  "maxSlippageBps": 50,
  "maxPriceImpactPct": 1,
  "hooks": true,
  "pinnedHooksOnly": true,
  "requireSimulation": true
}

This is the built-in default. Fields:

Every pinned contract (Universal Router, Permit2, v4 PoolManager, quoters, v3 factory, WETH9, USDG) must match its recorded codehash, always.

The trade's USD size is added to the ledger when build_swap returns calldata, whether or not the agent then sends it, so the cap can only be under-used, never exceeded.

Tools

Tokens are addresses on Robinhood Chain, or "ETH" for native ETH. Amounts are decimal strings in whole-token units.

Typical flow

1. quote to see the route and whether the policy would allow it.

2. build_swap with the agent wallet as from.

3. If needs_approval: sign and send the approvals, then call build_swap again.

4. Sign and send tx before deadline. The router reverts if fewer than minOut tokens arrive.

Limits

• Exact-input swaps only; one chain (Robinhood Chain).

• The ledger is per server process unless ZHOOK_LEDGER_FILE is set. Two servers sharing one wallet should share one ledger file, and not run at the same time.

• Prices for the caps come from live Uniswap quotes; USDG is counted as 1 USD.

• Public RPCs rate-limit; set ZHOOK_RPC_URLS for heavy use.

• v4 routing covers the pool list in use (default set, pools file, discovery). See the SDK README for routing limits.

Development

pnpm lint && pnpm typecheck && pnpm build && pnpm test

Tests drive the real MCP protocol through an in-memory client against a deterministic engine, and spawn the built server over stdio to check that stdout carries only JSON-RPC.

License

MIT © Zerohook