blockrun-debug

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 (music, speech, modal, defi, paid realface, stock price, native claude-* chat) while active chain is Solana. Every other tool pays on either chain.	The error names it. blockrun_wallet action:"chain" chain:"base".
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. Not charged — payment settles on completion only.	Retry, or pick a faster model. Do not retry-loop; jobs take 60–180 s.
Model id 404s	Delisted upstream	blockrun_models for the live list.
Startup prints 🚨 WALLET PRIVATE KEY DETECTED IN CONFIG FILE	The key was pasted into ~/.claude.json (old hosted-auth flow)	Treat the key as compromised: move funds to a new wallet, remove it from the config.
No spend-confirmation dialog with BLOCKRUN_CONFIRM_SPEND=on	Client doesn't support MCP elicitation (Windsurf, Codex, Gemini CLI) — the server proceeds without asking, by design	Use BLOCKRUN_BUDGET_LIMIT / blockrun_wallet action:"delegate" as the guard, or use Claude Code / Cursor / VS Code where the dialog renders.
Dialog appears, user clicks OK, tool says "declined"	Only an explicit Decline stops a charge; Cancel/ESC proceeds. If it says declined, Decline was pressed.	Re-run the call; approve it.
Update available: vX → vY on stderr	Informational	Switch to the blockrun-upgrade skill.