1. Install

Claude Code (recommended)

claude mcp add blockrun -s user -- npx -y @blockrun/mcp@latest

-s user installs globally (available in every project). The -- separator ensures -y is passed to npx, not parsed by claude mcp add.

💡 Homebrew / nvm users: if the server doesn't connect, Claude Code likely can't find node/npx on its launcher PATH. Pass your shell PATH through — works on CLI and desktop:

> claude mcp add blockrun -s user -e PATH="$PATH" -- npx -y @blockrun/mcp@latest
> 

See Troubleshooting if it persists.

Every MCP client — one command or one JSON block. Verified = we ran the published package on that client and saw the tools listed (client version · date). Documented = install path from the client's own docs; not run by us yet — tell us if it works. The Spend dialog column is whether the client renders the human-in-the-loop payment prompt; on ❌ clients paid calls proceed without asking and BLOCKRUN_BUDGET_LIMIT is the guard.

Any other MCP client that can spawn a stdio server works the same way: command: npx, args: ["-y", "@blockrun/mcp@latest"]. With nvm/Homebrew Node on a JSON-configured client, put the absolute path from which npx in command. Spend-dialog sources and what "proceeds without asking" means: docs/spend-confirmation.md.

Grok — raise the startup timeout before you install, or the first run looks broken. Grok waits startup_timeout_sec for an MCP server to answer, and it defaults to 30 (xAI's MCP docs). A first npx -y run has to download this package and its dependency tree before the server can say anything, and that is a race: measured cold, with an empty npm cache, it took 17s on a fast connection and 42-46s on a slower shared box. Lose the race and grok mcp doctor blockrun says server timed out (no response within 30s) and the UI shows blockrun [unavailable] — an install that is working, timing out, and indistinguishable from broken.

Give it room in ~/.grok/config.toml (or .grok/config.toml for one project):

[mcp_servers.blockrun]
command = "npx"
args = ["-y", "@blockrun/mcp@latest"]
enabled = true
startup_timeout_sec = 120

Or skip the cold download entirely, which is faster every run after the first:

npm install -g @blockrun/mcp@latest
grok mcp add blockrun -- blockrun-mcp

Only the FIRST run pays this: npx caches by exact spec, so the next start is warm (~9s here). The same trap exists on any client with a startup timeout — if a fresh install shows as unavailable and npx -y @blockrun/mcp@latest runs fine in a terminal, raise the client's timeout or install globally before looking for anything else. Thanks to @0xCheetah1 for the report.

OpenClaw: the published npx package was verified end-to-end on 2026.8.2: all 20 tools were projected (19 since the Surf delisting), free calls worked, and paid x402 calls settled. Add a hard session cap while installing:

openclaw mcp set blockrun '{"command":"npx","args":["-y","@blockrun/mcp@latest"],"env":{"BLOCKRUN_BUDGET_LIMIT":"2"}}'
openclaw mcp doctor blockrun --probe

Spend confirmation depends on the OpenClaw runtime and chat surface. Its Codex harness supports MCP form elicitation, but an unmappable prompt is returned as an explicit decline; in the WebChat → Codex route tested here, BLOCKRUN_CONFIRM_SPEND=on declined paid calls without presenting an actionable dialog. Keep confirmation off on that route and rely on BLOCKRUN_BUDGET_LIMIT plus OpenClaw's own tool-approval mode.

<details> <summary><strong>JSON for Claude Desktop, Cursor, Windsurf</strong></summary>

{
  "mcpServers": {
    "blockrun": { "command": "npx", "args": ["-y", "@blockrun/mcp@latest"] }
  }
}

Add "env": { "BLOCKRUN_CONFIRM_SPEND": "on" } inside the server object to turn on the spend dialog where the client supports it.

</details>

5. Install the agent skills (optional)

The package ships 16 skills — which tool answers what, worked examples, and a setup / debug / upgrade trio so the agent can install, troubleshoot and update the server on its own.

/plugin marketplace add BlockRunAI/blockrun-mcp            # Claude Code
npx -y @blockrun/mcp@latest skills install                 # any project → ./.claude/skills
npx -y @blockrun/mcp@latest skills install --global        # ~/.claude/skills
npx -y @blockrun/mcp@latest skills install --to ~/.codex/skills

skills list shows what ships; --only a,b picks; --force refreshes copies after an upgrade.

---

Pay on Solana *(default for new installs)*

blockrun_wallet action:"setup"    # shows the Solana address + funding QR

Send USDC (SPL) on the Solana network — from Coinbase (pick "Solana"), Phantom, Solflare, or Backpack.

Quick Start

Key use cases

1. Prediction-market consensus → "Polymarket's odds for the next Fed decision?" — blockrun_markets
2. Signal → trade (the full loop, self-custody) → "If 'hold' is under 30%, put $2 on Yes." — blockrun_markets reads, blockrun_polymarket action:"buy" places. Gasless, confirm-gated.
3. Smart-money forensics → "This Polymarket whale — who are they, which wallets are theirs, what's their P&L?" — blockrun_markets polymarket/wallet/identity/:wallet + .../cluster
4. Cited research → "5 most-cited papers on speculative decoding, last 90 days." — blockrun_exa
5. Image generation with on-image text → "Poster announcing GPT-5.5, retro-futuristic, headline 'NOW LIVE'." — blockrun_image
6. Give your agent a voice → "Speak this with the sarah voice." — blockrun_speech
7. Voice phone-out → "Call +1-415-… and confirm Friday at 3pm." — blockrun_phone
8. Multi-agent research, capped → "Spawn 3 agents on competing L1 narratives. Cap each at $0.50." — blockrun_wallet delegate × 3
9. Raw chain reads, 40 chains → "Latest Base block, and this contract's USDC balance." — blockrun_rpc

---

Demo

User: What's Polymarket saying about the Fed rate decision next month?

Claude: According to Polymarket, the market puts a 73% probability on the Fed holding rates steady, 24% on a 25bp cut, 3% on a hike. 24h volume: $2.1M. The "Hold" contract last traded at $0.73. (via blockrun_markets · cost: $0.0085 on Base — $0.0075 + the $0.001 network fee)

---

User: Polymarket has Hawley at ~13% to announce a 2026 presidential run — put $1 on Yes.

Claude: Done — bought 7.63 shares of Yes at $0.131 ($1.00, market FOK). Real on-chain order, settled in pUSD from your gasless Polymarket deposit wallet; I'm tracking the position now. (signal via blockrun_markets, trade via blockrun_polymarket — one self-custody wallet, gasless · on-chain tx 0x7ca8…)

---

Showcase

Posters generated through blockrun_image with openai/gpt-image-2 — each a single API call routed through BlockRun, paid in USDC on Base.

<p align="center"> <img src="assets/posters/gpt-5-5-launch.png" width="600" alt="gpt-5.5 — now live on BlockRun. Pay per call. No subscription. No keys."> </p>

Prompts and a worked example are in skills/image-prompting/SKILL.md.

---

2. Choose a tool profile (optional)

Expose a trimmed tool set so the client loads fewer schemas into context. Pass --profile <name> (or set BLOCKRUN_MCP_PROFILE); omit for the full set.

blockrun_surf was removed in 0.49.0: the gateway has answered every Surf (asksurf.ai) path with 410 since 2026-09-06, so the tool could only ever return an error, and its schema cost every agent context on every turn. Those questions go to blockrun_price, blockrun_defi, blockrun_markets and blockrun_dex; the surf skill maps each former endpoint to its replacement.

```bash claude mcp add blockrun-trading -s user -- npx -y @blockrun/mcp@latest --profile trading

Configuration

<details> <summary><strong>Environment variables & files</strong></summary>

Chain selection priority (src/utils/wallet.ts), highest first: .chain preference → SOLANA_WALLET_KEY → .chain-auto pin → non-empty .solana-session → Solana key in the OS keychain → an existing Base wallet keeps Base → otherwise Solana (a fresh install with no wallet at all).

That second-to-last step is the upgrade guard: without it, flipping the default to Solana would move every existing Base-only user onto an empty wallet, and their next paid call would fail on a zero balance with nothing on screen explaining why. None of this applies in account mode — BLOCKRUN_API_KEY has no chain.

The server runs a non-blocking npm registry check at startup and prints an Update available notice to stderr when a newer @blockrun/mcp exists — re-run the install command to upgrade.

</details>

---

Why not just use the APIs directly?

One wallet. All sources. No dashboards.

---

How it compares

✓ One wallet · ✓ Pay-per-call · ✓ Reads and trades · ✓ Multi-chain · ✓ Agent-ready · ✓ Open source

---

Troubleshooting

🤖 Hand this to the agent: the blockrun-debug skill carries every row below as symptom → cause → fix, plus the diagnostics it can run itself. blockrun-setup and blockrun-upgrade cover the other two halves. Install: npx -y @blockrun/mcp@latest skills install.

- Insufficient balance / HTTP 402 after retry → Run blockrun_wallet action:"setup", send USDC on Base (or Solana). - blockrun doesn't connect / "MCP server failed" / spawn npx ENOENT → Almost always a PATH issue: Claude Code can't find node/npx on its launcher PATH (common with Homebrew / nvm, on CLI and desktop). Fix by passing your shell PATH at install:

  claude mcp remove blockrun -s user
  claude mcp add blockrun -s user -e PATH="$PATH" -- npx -y @blockrun/mcp@latest
  

---

FAQ

What is BlockRun MCP? An open-source MCP server that gives Claude and other agents 19 tools for real-time data and real actions (trading, media, on-chain), paid per call — from a self-custody wallet or a BlockRun account key.

Do I need an API key or an account? No. A wallet is auto-created locally on first run; you fund it with USDC and there are no signups, dashboards or keys to rotate.

But you can have one. If your team can't hand a wallet to an agent, sign in at user.blockrun.ai, mint a key at Dashboard → Keys, top up at Dashboard → Credits, and set BLOCKRUN_API_KEY. You then get post-paid billing at exact usage — no $0.001 per-call minimum, no per-call network fee — and a per-call ledger at Dashboard → Activity. Everything works except the parts that genuinely need a keypair: Polymarket trading, wallet balances/top-ups, and the wallet-indexed blockrun_realface action:"list".

Which is cheaper? Account billing, slightly — it charges exact metered usage with no per-call minimum and no $0.001 transaction fee. Wallet mode buys you self-custody and Polymarket trading instead.

How much does it cost? Pay-per-call — fractions of a cent to a few cents. The free tier (blockrun_chat mode:"free", blockrun_dex, crypto blockrun_price, blockrun_models) is $0. $5 of USDC covers thousands of queries.

Is it safe / non-custodial? Yes. Your private key never leaves your machine (~/.blockrun/.session by default, 0600). x402 payments and Polymarket orders are signed locally — BlockRun forwards signed payloads and cannot move your funds.

Which clients work? Any MCP client that can spawn a stdio server. Verified on Claude Code and Codex CLI, in daily use on OpenClaw; install paths documented for Claude Desktop, Cursor, VS Code, Gemini CLI and Windsurf — see the client table. The spend-confirmation dialog additionally needs MCP elicitation (Claude Code, Cursor, VS Code).

Does it have a UI? On MCP-Apps hosts (Claude Desktop, claude.ai, VS Code, Cursor) the Polymarket preview is a live order card and the wallet is a panel — see MCP Apps ↑. Terminal clients get the same information as text.

Can I make the agent ask before it spends? Yes — BLOCKRUN_CONFIRM_SPEND=on. Every paid tool pauses with the estimated charge and nothing is signed until you approve. Human-in-the-loop payments ↑

Can it really place real bets? Yes. blockrun_polymarket places real, USDC-settled orders on Polymarket's CLOB — confirm-gated and capped. Read the odds with blockrun_markets, place with blockrun_polymarket.

Base or Solana? Both. Switch instantly with blockrun_wallet action:"chain". A few media/paid tools settle on Base only (noted above).

---