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

Tool	Description	Price
get_dex_price	Live Uniswap V3 spot price on Base	$0.01 USDC
get_pool_liquidity	Pool TVL from on-chain liquidity data	$0.01 USDC
list_trading_pairs	Discover all supported trading pairs	Free
compute_agent_score	On-chain agent utility score (0–100)	Free
lookup_agent_identity	ERC-8004 agent registry lookup	Free
search_defi_knowledge	Keyword search over 15-entry DeFi knowledge base	$0.001 USDC

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

File	Purpose
src/mcp-server.js	MCP stdio server — entry point for Claude Desktop
src/resource-server.js	Express HTTP server with x402 — deployed to Cloud Run
src/oracle.js	Uniswap V3 price reading (slot0()) + pool liquidity + 30s cache
src/scoring.js	Agent utility scoring (balance + tx count + ERC-8004 registry)
src/knowledge.js	DeFi knowledge base (15 entries) + keyword search
src/config.js	Pool addresses, constants, configuration

---

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.

Component	Max	Criteria
balance_score	30	ETH held (linear, capped at 1 ETH = 30)
tx_count_score	40	Outgoing transactions (100+ = max)
registry_score	30	Registered in ERC-8004 agent registry

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

Endpoint	Price	Network
/oracle/:pair	$0.01 USDC	Base
/liquidity/:pair	$0.01 USDC	Base
/knowledge/:query	$0.001 USDC	Base
/pairs, /score, /identity	Free	—

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)

Contract	Address
Uniswap V3 Factory	0x33128a8fC17869897dcE68Ed026d694621f6FDfD
ETH/USDC Pool (0.05%)	0xd0b53D9277642d899DF5C87A3966A349A798F224
ETH/USDT Pool (0.05%)	0xd92E0767473D1E3FF11Ac036f2b1DB90aD0aE55F
WETH/DAI Pool (0.05%)	0x93e8542E6CA0eFFfb9D57a270b76712b968A38f5
USDC/USDbC Pool	0x06959273E9A65433De71F5A452D529544E07dDD0
cbETH/WETH Pool	0x257fcbae4Ac6B26A02E4FC5e1a11e4174b5Ce395
ERC-8004 Registry	0x4f2c88C60709a2FA987e84E8305Ab1a0CA293b7A
AgentVault (payee)	0xeaE922306EFbD86eAA37aDAd8c66af511F139803

---

License

MIT