# x402 MCP Server

An [MCP (Model Context Protocol)](https://modelcontextprotocol.io/) server that exposes x402 DeFi data endpoints as tools for AI agents.

## What is MCP?

MCP is an open standard that lets AI applications (Claude, Cursor, OpenClaw, etc.) discover and use tools through a unified protocol. Think of it as a USB-C port for AI — any compliant client can plug into any compliant server.

This server wraps the x402 API (pay-per-call DeFi data) so that any MCP-compatible AI agent can:
- Discover available data endpoints
- Call them with proper parameters
- Get structured results back

## Tools

| Tool | Description |
|------|-------------|
| `get_crypto_prices` | Current prices, 24h changes, top movers |
| `analyze_whale_concentration` | Token holder concentration & whale risk (param: `token`) |
| `compare_funding_rates` | Perp funding rates across exchanges + arb opportunities |
| `list_available_endpoints` | Discover all available x402 API endpoints |

## Prerequisites

1. The x402 API server must be running at `localhost:4020` (or set `X402_API_URL`)
2. Node.js 18+

## Setup

```bash
cd x402-mcp-server
npm install
```

## Connect to Claude Desktop

Add to `~/Library/Application Support/Claude/claude_desktop_config.json`:

```json
{
  "mcpServers": {
    "x402-defi": {
      "command": "node",
      "args": ["/absolute/path/to/x402-mcp-server/src/index.js"],
      "env": {
        "X402_API_URL": "http://localhost:4020"
      }
    }
  }
}
```

## Connect to Cursor

Add to `.cursor/mcp.json` in your project (or global settings):

```json
{
  "mcpServers": {
    "x402-defi": {
      "command": "node",
      "args": ["/absolute/path/to/x402-mcp-server/src/index.js"]
    }
  }
}
```

## Connect to OpenClaw

```bash
openclaw mcp add x402-defi -- node /absolute/path/to/x402-mcp-server/src/index.js
```

## Test Locally

```bash
# Start the x402 API server first
cd ../x402-api-server && npm start &

# Test MCP server with the MCP inspector
npx @modelcontextprotocol/inspector node src/index.js

# Or pipe JSON-RPC manually:
echo '{"jsonrpc":"2.0","id":1,"method":"initialize","params":{"protocolVersion":"2024-11-05","capabilities":{},"clientInfo":{"name":"test","version":"1.0.0"}}}' | node src/index.js
```

## Architecture

```
AI Agent (Claude/Cursor/OpenClaw)
    ↕ MCP (stdio, JSON-RPC)
x402 MCP Server (this)
    ↕ HTTP
x402 API Server (localhost:4020)
    ↕ x402 protocol (HTTP 402 + USDC)
DeFi Data Sources
```

## License

MIT