ADI Chain MCP Server

MCP server for ADI Chain: canonical bridge, CCIP, and network tools for AI agents.

Agents can answer — and execute — "how do I get USDC from Ethereum onto ADI Chain?" instead of pointing a human at a bridge UI. The server encodes ADI's domain knowledge: which bridges exist, which tokens each supports, and the constraints (USDC.e is CCIP-only and stuck on ADI Mainnet; no DEX liquidity exists on ADI Mainnet).

Install

Clone, audit, install globally. Reading the source is the point. Install from the tagged release.

git clone https://github.com/ADI-Foundation-Labs/adi-mcp-server.git
cd adi-mcp-server
git checkout v1.0.1
bun i -g .          # installs globally from the audited clone
adi-mcp-server      # binary on PATH via package.json "bin"

Machines without bun: npm i -g . from the same clone. Update: git pull && git checkout v1.0.1 && bun i -g ..

Configure

Add to your MCP client (Claude Desktop, Cursor, .mcp.json, …):

{
  "mcpServers": {
    "adi": {
      "command": "adi-mcp-server",
      "env": { "ADI_MCP_PRIVATE_KEY": "0x..." }
    }
  }
}

ADI_MCP_PRIVATE_KEY is optional. Without it the server runs read-only — the four write tools (bridge_deposit, bridge_withdraw, claim_withdrawal, ccip_transfer) are not registered. The server never stores keys.

Tools

Read / query

Tool	What it returns
`get_network_info`	RPC, chain ID, explorer, bridge + CCIP contract addresses
`get_token_info`	Token addresses (L1/L2), decimals, which bridges can move it
`get_balance`	Native ADI or ERC-20 balance on ADI Chain
`get_bridge_options`	Which bridges support a token route, with constraints
`get_ccip_lanes`	CCIP lanes and supported tokens per lane
`get_bridge_status`	Finality of a tx: pending / committed / executed
`get_finality_status`	Node finality frontiers
`estimate_deposit`	L1 base cost of a canonical bridge deposit (in ADI)
`get_withdrawal_params`	Claim params for a withdrawal: batch, message index, message, Merkle proof
`list_withdrawals`	An address's L2→L1 withdrawals with claim status: stage, claimable (batch executed on L1), finalized (already claimed). Stateless — derived from on-chain state
`get_agent_profile`	ERC-8004 agent identity + reputation + validation (mainnet)

Advisory

Tool	What it returns
`plan_funding_path`	Best routes to get native ADI (or a token) onto ADI Chain, with steps, costs, caveats
`get_swap_services`	Non-custodial swap services that deliver ADI (advisory only)

Write (require `ADI_MCP_PRIVATE_KEY`)

Tool	What it does
`bridge_deposit`	Canonical bridge deposit: ADI ERC-20 (L1) → native ADI (L2). Approves the Native Token Vault (ADI) or Asset Router (ERC-20), deposits, returns L1 + canonical L2 tx hashes
`bridge_withdraw`	L2 → L1 withdrawal (native ADI or bridged ERC-20). ~75 min + claim
`claim_withdrawal`	Claim a finalized withdrawal on L1 via the Nullifier (params from `get_withdrawal_params`/`list_withdrawals`, or the tx hash to rebuild). Skips already-claimed withdrawals
`ccip_transfer`	CCIP token transfer (USDC.e, LINK on mainnet; CCIP-BnM on testnet)

Known constraints (encoded in the domain model)

ADI mainnet/testnet run nativeTokenBridgingOnly — only ADI is registered in the canonical bridge's Native Token Vault. ERC-20 deposits via the Two Bridges pattern are protocol-supported but not configured; the server rejects them with a clear error pointing to CCIP.
USDC.e is a CCIP burn/mint token — it can only move via CCIP lanes, never the canonical bridge.
No on-chain DEX with liquidity exists on ADI Mainnet — USDC.e cannot be swapped to native ADI on-chain. The multi-hop path (CCIP back to Ethereum → Uniswap → canonical bridge) is the workaround.
CCIP on ADI testnet supports only CCIP-BnM — USDC is not on ADI testnet CCIP.

Development

bun i
bun run typecheck   # tsc --noEmit
bun test            # unit tests (routing, token resolution, write policy)
bun run test/smoke.ts   # live smoke test against mainnet RPC
bun run test/write.ts   # write-tool registration + deposit tx construction (needs ADI_MCP_PRIVATE_KEY)
bun run test/live.ts    # live deposit → withdraw → claim round trip (needs ADI_MCP_PRIVATE_KEY, spends funds)

Architecture

src/
  cli.ts        MCP server entry (stdio)
  tools.ts      tool definitions + registration
  domain.ts     networks, tokens, bridges, constraints (source of truth)
  routing.ts    funding-path planning
  providers.ts  viem clients + Blockscout v1 API + zks_* RPC (L1 fallbacks)
  bridge.ts     canonical bridge deposit/withdraw/claim construction
  ccip.ts       CCIP ccipSend construction
  erc8004.ts    ERC-8004 registry reads (identity, reputation, validation)
  abis/         vendored ABIs (verified against live contracts)

All contract addresses and ABIs were verified against live RPC, the Chainlink CCIP directory, and the bridge UI bundle.

License

MIT

ADI Chain MCP Server