@blockrun/mcp

The payment layer for AI agents.

BlockRun MCP is a Model Context Protocol server that gives any AI agent (Claude, GPT, Cursor, etc.) access to 41 LLM models, real-time web search, prediction markets, crypto DEX data, whale tracking, image generation, and token swaps — all paid via x402 micropayments in USDC on Base. No API keys. No subscriptions. No accounts.

Why blockrun-mcp

Claude Code has task systems, token budgets, and multi-agent coordination. What it does not have: per-agent wallets, spending enforcement across sessions, or a way for a parent agent to delegate a budget to a child agent and block it when that budget is exhausted.

BlockRun fills this gap. Every tool call is a real micropayment — authorized locally by a wallet the agent controls. Parent agents can delegate spending limits to child agents by agent_id. Usage is auditable on-chain at any time.

This makes BlockRun the financial infrastructure layer for multi-agent systems, not just a model proxy.

Quick Start

Option 1: Hosted (zero install)

claude mcp add blockrun --transport http https://mcp.blockrun.ai/mcp

No Node.js. No npm. Works from any agent, CI/CD pipeline, or cloud environment. Pass your wallet key per-request via X-Wallet-Key header.

Option 2: Local (self-hosted, private key never leaves your machine)

claude mcp add blockrun npx @blockrun/mcp

# Optional: bring your own wallet
claude mcp add blockrun npx @blockrun/mcp --env BLOCKRUN_WALLET_KEY=0x...

A wallet is automatically created on first use. Fund it with USDC on Base network and every tool is immediately available.

What Your Agent Gets

Multi-Agent Budget Orchestration

A parent agent can allocate spending limits to child agents. Child agents self-identify via agent_id. When a child agent hits its limit, further calls are automatically blocked without any coordination logic needed in your code.

// Parent agent allocates budgets to child agents
mcp.call("blockrun_wallet", { action: "delegate", agent_id: "researcher", agent_limit: 2.00 })
mcp.call("blockrun_wallet", { action: "delegate", agent_id: "writer", agent_limit: 0.50 })

// Child agents self-identify — auto-blocked at limit
mcp.call("blockrun_chat", { message: "...", routing: "smart", agent_id: "researcher" })

// Audit spending across all agents
mcp.call("blockrun_wallet", { action: "report" })
// researcher: $1.84/$2.00 (23 calls), writer: $0.31/$0.50 (4 calls)

This pattern works across sessions. The spending record is tied to the wallet, not the process.

Smart Routing (ClawRouter)

Agents do not need to pick models. Pass routing: "smart" and ClawRouter selects the optimal model for the task based on the routing profile.

// Auto-selects optimal model — agents never need to pick
blockrun_chat({ message: "...", routing: "smart", routing_profile: "eco" })
// Returns: [nvidia/deepseek-v3.2 | SIMPLE | $0.0001 | 94% savings]

All 41 Models

OpenAI (13 models)

Anthropic (4 models)

Google (7 models)

DeepSeek (2 models)

NVIDIA (12 models — FREE)

All NVIDIA-hosted models are free via the routing_profile: "free" option or by specifying directly.

ZAI (2 models)

MiniMax (1 model)

How Payments Work

Every request is paid via the x402 protocol — an open payment standard for machine-to-machine micropayments. Payments settle in USDC on Base network. Your wallet is created automatically on first use and stored locally at ~/.blockrun/.session. The private key is used only to sign payment authorizations locally — it is never transmitted to any server. You can verify all transactions on Basescan.

Funding Your Wallet

# Get your wallet address
blockrun_wallet({ action: "balance" })
# Returns: 0x... (QR code available for mobile wallets)

Send USDC on Base network to that address. $5 gets you started — approximately 50,000 Gemini Flash requests or 125 DALL-E 3 images. There is no minimum. You pay only for what you use.

Architecture

Claude Code / Any MCP Client
        |
        | stdio (local) or HTTP (remote, coming soon)
        |
   blockrun-mcp server
        |
        | x402 micropayments (USDC on Base)
        |
   blockrun.ai gateway
        |
        +-- OpenAI
        +-- Anthropic
        +-- Google
        +-- NVIDIA
        +-- DeepSeek
        +-- ZAI / MiniMax
        +-- DexScreener / Etherscan / Polymarket / Kalshi / Exa / 0x

The MCP server runs locally (stdio transport). Each tool call that requires payment triggers a local wallet signature. The signed payment authorization is sent to the blockrun.ai gateway alongside the API request. No API keys pass through your machine.

Configuration

Wallet resolution order:

1. BLOCKRUN_WALLET_KEY environment variable
2. BASE_CHAIN_WALLET_KEY environment variable
3. ~/.blockrun/.session (auto-created on first use)

Development

git clone https://github.com/BlockRunAI/blockrun-mcp
cd blockrun-mcp
npm install
npm run build
npm run dev  # tsx watch — auto-reloads on changes

To test the server manually:

echo '{"jsonrpc":"2.0","method":"tools/list","id":1}' | node dist/index.js

Roadmap

• 14 tools covering LLMs, search, crypto, markets, image generation
• Multi-agent budget delegation via agent_id
• ClawRouter intelligent model routing
• Multi-turn conversation support
• HTTP/SSE transport (deploy to mcp.blockrun.ai — no local install needed)
• Per-tool LLM-optimized descriptions
• Official MCP registry listing
• Persistent cross-session spending records tied to wallet

Links

• Website: blockrun.ai
• npm: @blockrun/mcp
• GitHub: github.com/blockrunai/blockrun-mcp
• Issues: github.com/blockrunai/blockrun-mcp/issues
• Pricing: blockrun.ai/pricing
• Telegram: t.me/+mroQv4-4hGgzOGUx
• X: @BlockRunAI

License

MIT