/blockrun-debug

name: blockrun-debug
description: "Use when the BlockRun MCP server (@blockrun/mcp) is installed but misbehaving — 'Failed to connect', spawn npx ENOENT, blockrun missing from claude mcp list, HTTP 402 / Insufficient balance, fetch failed, video or music timeouts, a 501 'not served' error or 'API error after payment' while the balance never moved, spend-confirmation dialogs not appearing, or a Polymarket buy/redeem failing after funding. Symptom → cause → fix, plus what never to do."
triggers:
  - "blockrun failed to connect"
  - "blockrun not working"
  - "spawn npx ENOENT"
  - "402 payment required"
  - "insufficient balance"
  - "blockrun 402"
  - "fetch failed blockrun"
  - "video generation timed out"
  - "api error after payment"
  - "equity quotes are not served"
  - "sports markets 500"
  - "501 not implemented"
  - "blockrun unavailable"
  - "server timed out"
  - "startup_timeout_sec"
  - "refusing to sign it"
  - "quoted a different price"
  - "polymarket buy failed"
  - "insufficient allowance"
  - "redeem reverts"
  - "debug blockrun"

Debugging BlockRun MCP

Find the row, run the fix, stop. Most "broken" reports are one of the first three rows.

Rules before touching anything

1. **A 402 / "Insufficient balance" is a funding state, not a bug.** Call `blockrun_wallet` first. Never retry the failing tool in a loop — it will 402 identically every time and the failed attempts cost nothing, but they burn turns. 2. **Never delete or regenerate `~/.blockrun/.session`.** It is the only copy of the key that holds the user's USDC and their Polymarket deposit wallet. There is no recovery. 3. **Never advise withdrawing from Polymarket to "start over".** Every post-funding trade failure seen so far was a missing approval; a withdraw does not fix it and costs a round trip. 4. Reproduce with the **free** call `blockrun_wallet` before anything paid.

Run these first (read-only, 10 seconds)

node -v && which npx                     # runtime present, ≥ 20.19?
claude mcp get blockrun                  # registered command, env, AND scope (-s user / project / local)
npx -y @blockrun/mcp@latest --version    # does the package itself run? (prints e.g. 0.43.0)

Use the scope `claude mcp get` reports in every `remove`/`add` below — the examples say `-s user` because that is the documented install, but a project-scoped install re-added at user scope leaves a duplicate. Then, in the session: `blockrun_wallet` (free) → `blockrun_models` (free) → the tool that failed, **once**.

Symptom → cause → fix

| Symptom | Cause | Fix | |---|---|---| | `claude mcp list` → `blockrun … ✗ Failed to connect`, or logs show `spawn npx ENOENT` | The client's launcher can't find `node`/`npx` — nvm, Homebrew, fnm, volta. Interactive shell has them; the spawner does not. | `claude mcp remove blockrun -s user` then `claude mcp add blockrun -s user -e PATH="$PATH" -- npx -y @blockrun/mcp@latest`. Quit and relaunch the client. Codex: `codex mcp add blockrun --env PATH="$PATH" -- …`. JSON clients (Claude Desktop / Cursor / Windsurf): set `"command"` to the output of `which npx`; file paths are in the `blockrun-setup` skill. | | `blockrun` absent from `claude mcp list` | Wrong scope, or Node < 20.19, or a corrupt npx cache | `node -v` (≥ 20.19). `claude mcp get blockrun`. `rm -rf ~/.npm/_npx`. Re-run the install line. | | Connects, but every paid tool → `HTTP 402` / `Insufficient balance` | Wallet is empty (or on the wrong chain for this tool) | `blockrun_wallet` → read balance + chain. `blockrun_wallet action:"setup"` → address + QR. Fund with USDC **on Base** (or switch to Solana). Then retry **once**. | | 402 although balance shows funds | Chain mismatch: a Base-only tool (`defi`, `modal`, `claude-*` chat with `thinking`) while active chain is Solana. Everything else — plain `claude-*` chat, music, speech, RealFace, price, media — now pays on either chain. | The error names it. `blockrun_wallet action:"chain" chain:"base"`. | | 402 from `api.blockrun.ai` | Not a wallet problem: the server is on an API key and the ACCOUNT is out of credit. | Top up at <https://user.blockrun.ai/dashboard/credits>. Do not look for a wallet. | | 401 from `api.blockrun.ai` | `BLOCKRUN_API_KEY` rejected. | Check the key at <https://user.blockrun.ai/dashboard/keys>. | | "needs wallet mode" on Polymarket / wallet / realface list | Keypair-only capability while the server is on an API key (from `BLOCKRUN_API_KEY` or `~/.blockrun/.api-key`). | Do what the refusal says: it names the key's actual source. Unset `BLOCKRUN_API_KEY` and/or remove `~/.blockrun/.api-key`, then restart. | | Startup error "not a valid BlockRun API key" | `BLOCKRUN_API_KEY` is malformed. It deliberately fails loudly rather than silently spending USDC from a wallet instead. | Fix the value or unset it. | | Grok (or any client with a startup timeout) shows `blockrun [unavailable]`, and `mcp doctor` says `server timed out (no response within 30s)` | NOT broken: a cold `npx -y` is still downloading the package and its dependency tree when the client gives up. Grok's `startup_timeout_sec` defaults to 30; the cold start measured 17s on a fast connection and 42-46s on a slower box. Nothing is charged — the server never started. | Raise it in `~/.grok/config.toml` (`[mcp_servers.blockrun]` … `startup_timeout_sec = 120`), or `npm install -g @blockrun/mcp@latest` and point the client at `blockrun-mcp`. Confirm the package itself is fine first: `npx -y @blockrun/mcp@latest` in a terminal answers an `initialize` line. Only the first run is slow — npx caches by exact spec. | | `fetch failed` / balance-check timeout | Base RPC blip; the tool rotates through 3 public RPCs | Wait 30 s, retry once. Persistent → a local proxy/firewall is blocking outbound RPC. | | `Video`/`Music generation timed out` | Upstream queue. **Base wallet: not charged** — payment settles on completion. **Solana music / account rail: charged at submit** — the error names th