AgentShield MCP Server

MCP server providing live DeFi data tools for AI agents on Base chain. Six tools powered by real Uniswap V3 on-chain data, with x402 micropayment gating.

Live endpoint: https://agentshield-mcp-377492254889.europe-west1.run.app

Tools

Supported pairs: ETH/USDC, ETH/USDT, WETH/DAI, USDC/USDbC, cbETH/WETH

Architecture

┌─────────────────────────────────────────────────┐
│  Claude Desktop / Any MCP Client                │
└────────────────────┬────────────────────────────┘
                     │ stdio (JSON-RPC)
┌────────────────────▼────────────────────────────┐
│  src/mcp-server.js  (MCP stdio server)          │
│                                                 │
│  Standalone mode (default):                     │
│    reads on-chain data directly via Base RPC    │
│                                                 │
│  Bridge mode (RESOURCE_SERVER_URL set):         │
│    proxies requests → resource server           │
└────────┬────────────────────┬───────────────────┘
         │                    │
         │  (standalone)      │  (bridge mode)
         ▼                    ▼
┌─────────────────┐  ┌────────────────────────────┐
│  Base Mainnet   │  │  src/resource-server.js     │
│  (public RPC)   │  │  (Express HTTP + x402)      │
│                 │  │                              │
│  Uniswap V3    │  │  Cloud Run:                  │
│  pools          │  │  agentshield-mcp-377492254889│
│  (slot0)        │  │  .europe-west1.run.app       │
└─────────────────┘  └────────────┬────────────────┘
                                  │  x402 payment gate
                                  │  (Coinbase CDP facilitator)
                                  ▼
                     ┌────────────────────────────┐
                     │  Base Mainnet              │
                     │  Uniswap V3 pools          │
                     └────────────────────────────┘

Source files

Quick Start

git clone https://github.com/yeick010/agentshield-mcp
cd agentshield-mcp
npm install

MCP server (for Claude Desktop)

npm start
# or
node src/mcp-server.js

Resource server (HTTP, with x402 payment gates)

npm run server
# or
node src/resource-server.js

Local server starts on http://localhost:4021.

Run tests

npm test

54 tests covering all tools, edge cases, and on-chain data validation.

Claude Desktop Configuration

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

{
  "mcpServers": {
    "agentshield": {
      "command": "node",
      "args": ["/absolute/path/to/agentshield-mcp/src/mcp-server.js"]
    }
  }
}

After saving, restart Claude Desktop. The six tools will appear in the tools panel.

REST API

Base URL: https://agentshield-mcp-377492254889.europe-west1.run.app

GET /health

Service health check. Returns version, network, x402 status, and pricing table.

GET /pairs

Returns all supported trading pairs with pool addresses and fee tiers. Free.

GET /oracle/:pair

Live Uniswap V3 spot price. Prices cached for 30 seconds.

curl https://agentshield-mcp-377492254889.europe-west1.run.app/oracle/ETH%2FUSDC

{
  "pair": "ETH/USDC",
  "price": 2235.83,
  "price_display": "USDC per WETH",
  "source": "uniswap_v3",
  "pool_address": "0xd0b53D9277642d899DF5C87A3966A349A798F224",
  "fee_tier": 500,
  "network": "base",
  "cached": false
}

GET /liquidity/:pair

Pool TVL from on-chain liquidity data.

curl https://agentshield-mcp-377492254889.europe-west1.run.app/liquidity/ETH%2FUSDC

GET /score/:address

On-chain agent utility score (0–100). Free.

GET /identity/:address

ERC-8004 agent registry lookup. Free.

GET /knowledge/:query

DeFi knowledge base search across 15 curated entries.

Topics: Flash Loans, AMMs, Uniswap V3, MEV, x402 Protocol, ERC-8004, Base Chain, Aave V3, Impermanent Loss, Liquidations, Oracle Manipulation, Gas Optimization, Aerodrome, sqrtPriceX96 Math, MCP Protocol

x402 Payment Gating

Payments flow through the x402 protocol using Coinbase CDP as facilitator. Funds are sent to the AgentVault on Base mainnet.

Graceful degradation: If the facilitator is unavailable or CDP keys are not configured, the server runs with all endpoints free. The /health endpoint reports the current x402 status.

Cloud Run Deployment

Deploy using the included script:

bash deploy-cloudrun.sh

Or run Step 3 only (image already built):

gcloud run deploy agentshield-mcp \
  --image gcr.io/arbitrage-agent-prod/agentshield-mcp \
  --project arbitrage-agent-prod \
  --region europe-west1 \
  --platform managed \
  --allow-unauthenticated \
  --cpu 0.5 --memory 256Mi \
  --min-instances 0 --max-instances 1 \
  --concurrency 1 --timeout 30s \
  --port 8080

Cost: ~€0/month at low traffic (min-instances=0, scales to zero).

CDP secrets are read from Google Cloud Secret Manager (CDP_API_KEY_ID, CDP_API_KEY_SECRET).

On-Chain Contracts (Base Mainnet)

License

MIT