@agentoracle.ai/mcp-server

Model Context Protocol (MCP) server for AgentOracle — real-time on-chain crypto market data, pay-per-call USDC on Base via x402.

Plug AgentOracle into any MCP-compatible host (Claude Desktop, Cursor, Continue, Cline, Zed, etc.) and your agent can query token prices, volume, liquidity, market cap, top movers, and per-symbol lookups — paying $0.01 USDC per call automatically. No API keys.

Tools exposed

| Tool | Purpose | | --- | --- | | agentoracle_status | Service heartbeat: token count, last ingestion, uptime, version | | agentoracle_list_tokens | List tokens with filters (chain, min liquidity, min volume, min market cap, limit, offset) | | agentoracle_top_tokens | Top N tokens by market cap (limit 1–100, default 20) | | agentoracle_movers | Top 10 gainers + top 10 losers by 24h price change | | agentoracle_get_token | Single-token lookup by ticker (case-insensitive: ETH, BTC, SOL, …) |

Every call costs $0.01 USDC on Base mainnet, settled via the official Coinbase CDP Facilitator.

Install

You don't need to install anything — npx handles it.

Configure: Claude Desktop

Edit your Claude Desktop config:

• macOS: ~/Library/Application Support/Claude/claude_desktop_config.json
• Windows: %APPDATA%\Claude\claude_desktop_config.json

Add the agentoracle entry under mcpServers:

{
  "mcpServers": {
    "agentoracle": {
      "command": "npx",
      "args": ["-y", "@agentoracle.ai/mcp-server"],
      "env": {
        "WALLET_PRIVATE_KEY": "0xYOUR_BASE_WALLET_PRIVATE_KEY"
      }
    }
  }
}

Restart Claude Desktop. The five tools will appear in the MCP tool palette.

Configure: Cursor

Cursor → Settings → MCP → Add new MCP server:

{
  "name": "agentoracle",
  "command": "npx",
  "args": ["-y", "@agentoracle.ai/mcp-server"],
  "env": {
    "WALLET_PRIVATE_KEY": "0xYOUR_BASE_WALLET_PRIVATE_KEY"
  }
}

Configure: Continue, Cline, Zed, others

Any MCP host that supports stdio transport works — point it at npx -y @agentoracle.ai/mcp-server and pass WALLET_PRIVATE_KEY in the env block.

Wallet setup

You need a Base mainnet wallet with USDC. Cheap options:

1. Coinbase Wallet → export private key → fund with $5 of USDC on Base. That's 500 calls.
2. MetaMask → switch to Base network → bridge USDC from Ethereum or Polygon, or buy directly.
3. Programmatic — generate a key with viem's generatePrivateKey(), fund via Coinbase Onramp.

The private key never leaves your machine; the MCP server uses it locally to sign EIP-3009 USDC transfers.

Environment variables

| Variable | Required | Default | Purpose | | --- | --- | --- | --- | | WALLET_PRIVATE_KEY | Yes (for paid calls) | — | Hex private key of a Base wallet with USDC. Without it, every call returns HTTP 402. | | AGENTORACLE_BASE_URL | No | https://aiagentoracle.ai | Override the API base URL (useful for self-hosted forks). |

Try it (without payment)

You can list the tools without any wallet:

WALLET_PRIVATE_KEY="" npx -y @agentoracle.ai/mcp-server

Then send {"jsonrpc":"2.0","id":1,"method":"tools/list"} over stdin — every paid tool call will return HTTP 402 explaining what's needed.

Build from source

git clone https://github.com/agentoracle/mcp-server.git
cd mcp-server
npm install
npm run build
node dist/index.js

Pricing

Every call is $0.01 USDC on Base. Settled per request — there are no subscriptions, accounts, or invoices. The pay-to address is published in the canonical x402 manifest at https://aiagentoracle.ai/.well-known/x402.

License

MIT

Links

• AgentOracle: https://aiagentoracle.ai
• x402 manifest: https://aiagentoracle.ai/.well-known/x402
• x402 protocol: https://x402.org
• Model Context Protocol: https://modelcontextprotocol.io