Ophis MCP

@ophis/mcp-server

Agent-facing MCP server for the Ophis DEX, deployed as a Cloudflare Worker with the Streamable-HTTP transport at https://mcp.ophis.fi/mcp.

Current server release: v0.2.0, with 13 tools across 15 configured EVM chains (14 mainnets plus Sepolia).

It exposes the Ophis trading surface to autonomous agents and MCP clients without making them re-derive the fork's non-obvious, easy-to-get-wrong details (non-canonical settlement contracts on the Ophis-operated chains, the self -hosted Optimism, Unichain, Robinhood Chain, and Arc orderbook hosts, the CIP-75 partner-fee appData shape, and receiver pinning).

Arc (5042) charges the 1 bp base fee and supports routed-volume indexing and referral attribution. Server referral defaults apply; a per-call code overrides the default, and an empty string opts out. After an order is accepted, submit_order enrolls the owner for indexing and the live trade-rewards campaign.

The tools operate on configured EVM orderbooks. list_chains reports configuration, not a live availability probe. The standalone app's externally funded NEAR source flow is separate; these tools do not create or fund those deposits. See network and funding coverage.

Security model

The server holds no private keys and never signs. build_order returns a bounded, ready-to-sign EIP-712 payload with the order receiver pinned to the owner (the #1 autonomous-agent drain vector); the agent signs with its own key and submits. This is the V1 "bounded capability" pattern, an off-chain misuse guard, not an on-chain authorization boundary. It is public and unauthenticated: every backing endpoint is already public, and the tools are read/build-only.

Tools

Tool	Purpose
parse_intent	Plain-English swap request → structured intent (LibertAI Qwen via swap.ophis.fi/api/intent).
resolve_token	Resolve a token symbol to its canonical address from the trusted Ophis list; fails closed (anti-spoof).
list_chains	Supported chains, orderbook hosts, settlement contracts, partner-fee config.
get_quote	Best-execution quote from the chain's Ophis orderbook (/api/v1/quote).
expected_surplus	Estimate price improvement versus a public aggregator (KyberSwap), in basis points.
build_order	A bounded, ready-to-sign CoW order: correct per-chain settlement + orderbook, CIP-75 partner fee in appData, receiver pinned to owner.
submit_order	Relay a pre-signed order to the orderbook (/api/v1/orders). No keys held here.
get_integrator_earnings	Routed volume, the Ophis base fee, and the integrator's own fee on CoW-hosted chains, by appCode (rebates.ophis.fi/earnings/:appCode).
get_balances	Native + ERC-20 balances for an address on one chain.
get_portfolio	Native + ERC-20 balances across multiple chains.
get_gas	Current gas price for a chain (informational; offchain order signatures are gasless, approvals and other wallet transactions are not).
get_token_chart	OHLCV price history for a token.
validate_order	Offline preflight for an externally-built order (no network, no keys): catches wrong appCode, orderbook host, EIP-712 domain, appData hash mismatch, unpinned receiver, and expired or non-zero-fee orders.

Typical agent flow

parse_intent("swap 100 USDC for WETH on Optimism")
  → resolve_token({ chainId, symbol }) for BOTH the sell and buy symbols   // canonical addresses, fails closed (anti-spoof); for a native-coin request like ETH, resolve the wrapped symbol (WETH)
  → get_quote({ chainId, sellToken, buyToken, kind:'sell', amount, from })
  → build_order({ chainId, owner, sellToken, buyToken, sellAmount, buyAmount /* slippage-adjusted */, kind })
  → (agent confirms with the user, then signs `order` as EIP-712 using `signing`)
  → submit_order({ chainId, order, signature, from, fullAppData })

Develop

pnpm --filter @ophis/mcp-server test         # unit tests (pure logic)
pnpm --filter @ophis/mcp-server typecheck
pnpm --filter @ophis/mcp-server dev          # wrangler dev (local Streamable HTTP)
npx @modelcontextprotocol/inspector@latest   # point at http://localhost:8787/mcp

dev / deploy / dry-run auto-build the workspace SDK first (pre* scripts), so a clean checkout works without a manual @ophis/sdk build.

Deploy

Auto-deploys on push to main via .github/workflows/mcp-deploy.yml, using the least-privilege CLOUDFLARE_WORKERS_TOKEN secret (Workers Scripts + Routes only). Manual:

pnpm --filter @ophis/mcp-server deploy        # builds the SDK, then wrangler deploy → mcp.ophis.fi

Custom domain mcp.ophis.fi is provisioned from wrangler.jsonc (routes).

After the main deployment succeeds, an organization admin creates the matching mcp-v<x.y.z> tag. .github/workflows/mcp-registry-release.yml verifies that the live /health version matches, then publishes server.json to the official MCP Registry. See the release runbook.