valorem-mev-mcp

valorem-mev-mcp

Model Context Protocol (MCP) server for Valorem MEV Intelligence.

Gives any MCP-compatible LLM agent (Claude Desktop, ChatGPT, Cursor, etc.) direct access to real-time MEV and DeFi data via Valorem's x402-paid API endpoints. Payments are made in USDC on Base mainnet.

---

Tools

| Tool | Endpoint | Cost | Description | |---|---|---|---| | catalog | GET /catalog | Free | Full service catalog with all endpoints and prices | | liquidation_watchlist | GET /liquidations/watchlist | $0.50 | Aave V3 near-liquidation positions — health factors, collateral, debt | | decoded_hints | GET /hints/decoded | $0.10 | Last 50 decoded MEV-Share hints — swap direction, pool, token pair | | builder_stats | GET /builders/stats | $0.25 | Per-builder acceptance rates for Flashbots, Titan, Beaver, BuilderNet, Quasar | | agent_intelligence | GET /agents/intelligence | $1.00 | Agent wallet tracking — active wallets, x402 spend patterns, top providers | | pool_spreads | GET /pools/spreads | $0.05 | L2 arb opportunities across 125+ Base + Arbitrum pools | | token_safety | GET /tokens/safety?token= | $0.02 | Token tax/rebase/reflect classification by contract address | | rpc_health | GET /rpc/health | $0.01 | RPC provider health — latency, error rates, uptime | | rpc_proxy | POST /rpc/proxy | $0.001 | Premium Reth L1 RPC proxy (~6 ms latency) — any JSON-RPC method |

---

Payment Modes

Free Mode (default)

No private key required. When an API call returns HTTP 402, the server surfaces the payment requirements to the agent as a formatted message. The agent or user can then pay externally and retry.

npx valorem-mev-mcp

Paid Mode (auto-pay)

Set the PRIVATE_KEY environment variable to an EVM private key with USDC on Base mainnet. The server uses @x402/fetch + @x402/evm to automatically sign and submit payments, then retries the request transparently.

PRIVATE_KEY=0xYourPrivateKeyHere npx valorem-mev-mcp

Security: Never commit your private key. Use a dedicated spending wallet with only the USDC you intend to spend. The key never leaves your machine.

---

Installation

Global install

npm install -g valorem-mev-mcp
valorem-mev-mcp

npx (no install)

npx valorem-mev-mcp

Local development

git clone https://github.com/advalorem/valorem-mev-mcp
cd valorem-mev-mcp
npm install
node src/index.js

---

Connecting to Claude Desktop

Edit ~/Library/Application Support/Claude/claude_desktop_config.json (macOS) or %APPDATA%\Claude\claude_desktop_config.json (Windows):

Free mode

{
  "mcpServers": {
    "valorem-mev": {
      "command": "npx",
      "args": ["valorem-mev-mcp"]
    }
  }
}

Paid mode

{
  "mcpServers": {
    "valorem-mev": {
      "command": "npx",
      "args": ["valorem-mev-mcp"],
      "env": {
        "PRIVATE_KEY": "0xYourPrivateKeyHere"
      }
    }
  }
}

Restart Claude Desktop after editing. The tools will appear in the tool selector.

---

Connecting to ChatGPT (Actions / Plugins)

ChatGPT plugins and Actions use an HTTP-based transport. To bridge this MCP server to HTTP, use mcp-proxy or the OpenAI MCP adapter:

# Install the bridge
npm install -g @modelcontextprotocol/proxy

# Run valorem-mev-mcp behind an HTTP proxy on port 3000
mcp-proxy --port 3000 -- npx valorem-mev-mcp

Then point your ChatGPT Action or plugin manifest at http://localhost:3000.

---

Connecting to Cursor / Windsurf / Other Clients

Most IDE-based MCP clients accept a command + args configuration identical to Claude Desktop. Add this to your client's MCP server list:

{
  "command": "npx",
  "args": ["valorem-mev-mcp"],
  "env": {
    "PRIVATE_KEY": "0xOptionalForAutoPay"
  }
}

---

Tool Usage Examples

Get service catalog (free)

Use the catalog tool to show me what MEV data is available.

Check near-liquidation positions

Call liquidation_watchlist and tell me which Aave V3 positions are closest to liquidation.

Classify a token

Use token_safety to check if 0xA0b86991c6218b36c1d19D4a2e9Eb0cE3606eB48 is a tax token.

Proxy an eth_call

Use rpc_proxy to call eth_blockNumber with params [].

---

Architecture

Claude / ChatGPT / Cursor
        │
        │  MCP stdio transport (JSON-RPC 2.0)
        ▼
valorem-mev-mcp  (this server)
        │
        │  HTTPS + optional x402 payment header
        ▼
https://18-220-76-66.nip.io/engine-api/x402
        │
        ▼
Valorem MEV Intelligence API (Base mainnet USDC payments)

x402 Payment Flow

1. Server calls API endpoint (no payment header)
2. API returns HTTP 402 with X-PAYMENT-REQUIRED header
3a. FREE mode: 402 details returned to agent as text
3b. PAID mode: @x402/fetch parses requirements, signs USDC EIP-712 permit
                with viem private key account, retries with X-PAYMENT header
4. API verifies payment, returns 200 with data

---

Environment Variables

| Variable | Required | Description | |---|---|---| | PRIVATE_KEY | No | EVM private key (hex, 0x-prefixed or raw) for auto-payment in paid mode |

---

Requirements

• Node.js ≥ 18
• npm ≥ 8

---

License

MIT — see LICENSE

---

Links

• Valorem: https://advalorem.io
• x402 Protocol: https://x402.org
• MCP Specification: https://modelcontextprotocol.io
• @modelcontextprotocol/sdk: https://www.npmjs.com/package/@modelcontextprotocol/sdk