Upgrading BlockRun MCP

The server is run by npx, so "upgrading" means making npx fetch a newer version and the client restart into it. Which of those two is the problem depends on how it was installed.

1. Read how it was installed

claude mcp get blockrun          # registered command + args + env + scope
npm view @blockrun/mcp version   # what "latest" is on the registry right now

Registered spec	What happens at each client start
npx -y @blockrun/mcp@latest	npx re-resolves latest against the registry and downloads if newer. A client restart is the upgrade.
npx -y @blockrun/mcp (no tag)	npx reuses whatever is in ~/.npm/_npx — the version from the day it was installed. Restarting changes nothing.
npx -y @blockrun/mcp@0.39.2	Pinned on purpose. Only changes if you re-register.

The startup notice is the server telling you it is not on latest:

[BlockRun] Update available: v0.39.2 → v0.42.0
[BlockRun] Run: claude mcp add blockrun -s user -- npx -y @blockrun/mcp@latest

2. Upgrade

Registered with @latest: restart the client. Done. If the notice persists, the cache is stale or the registry was unreachable at start:

rm -rf ~/.npm/_npx          # safe — it is only a download cache

then restart again.

Registered without a tag, or pinned: re-register with @latest. claude mcp add refuses a name that already exists, so remove first — at the scope claude mcp get reported — and carry every env var and flag it printed across, one -e each, flags after the package:

claude mcp remove blockrun -s user
claude mcp add blockrun -s user \
  -e PATH="$PATH" -e BLOCKRUN_KEYCHAIN=auto -e BLOCKRUN_CONFIRM_SPEND=on \
  -- npx -y @blockrun/mcp@latest --profile trading

Codex: codex mcp remove blockrun then codex mcp add blockrun -- npx -y @blockrun/mcp@latest. JSON clients (Claude Desktop / Cursor / Windsurf): edit args to ["-y", "@blockrun/mcp@latest"].

Then quit and relaunch the client (Claude Code: /mcp reconnect blockrun respawns just this server). A running session keeps the old process until you do.

3. Prove the version

npx -y @blockrun/mcp@latest --version     # what npx would launch now, e.g. 0.42.0

That proves what npx would launch. What the client is running is the server's startup line on stderr — BlockRun MCP Server started (v0.42.0) — stdio transport — 20 tools (Claude Code: claude --debug or the MCP log; /mcp shows connection status, not the version). If the two disagree, the client was not restarted; the stderr line wins. No Update available line after it = you are current.

4. What can break

Read the CHANGELOG for the versions you are crossing: https://github.com/BlockRunAI/blockrun-mcp/blob/main/CHANGELOG.md. Each entry explains the behaviour change, not just the diff. Things that have changed across versions and are worth checking:

• Tool set / profiles — --profile names and tool membership; a trimmed profile may gain or lose a tool.
• Env-var semantics — the kind of change to look for: BLOCKRUN_KEYCHAIN arrived in 0.41; BLOCKRUN_CONFIRM_SPEND widened from one tool to all paid tools in 0.43. Read the entries for the versions you cross and re-check claude mcp get blockrun env against the README Configuration table.
• Wallet file precedence — BLOCKRUN_WALLET_KEY → agent wallet.json → ~/.blockrun/.session. An upgrade never moves or rewrites the key; if a balance "disappears", the signer changed, not the funds. blockrun_wallet prints the address.
• Polymarket approvals — new adapter grants are added over time. After an upgrade, blockrun_polymarket action:"setup" confirm:true once before trading: idempotent and gasless, but it signs on-chain approvals, so say so to the user before running it.

Your USDC and keys are in ~/.blockrun/, not in the package. Upgrading cannot lose them.

5. Refresh copied skills

Skills copied into a project or user directory do not update with the package. Marketplace-installed skills (/plugin marketplace add BlockRunAI/blockrun-mcp) refresh with /plugin marketplace update blockrun-mcp followed by /reload-plugins (or uninstall + /plugin install <skill>@blockrun-mcp). For copied ones, re-run the install with --force — it overwrites the files the package ships and leaves any other files in those directories alone:

ls .claude/skills ~/.claude/skills 2>/dev/null                 # where were they copied?
npx -y @blockrun/mcp@latest skills list                       # what this version ships
npx -y @blockrun/mcp@latest skills install --force            # ./.claude/skills
npx -y @blockrun/mcp@latest skills install --global --force   # ~/.claude/skills

--force replaces the shipped files. If the user edited their copies, diff before overwriting: skills install --to /tmp/br-skills and diff -r /tmp/br-skills .claude/skills.

Rollback

Pin the previous version and restart:

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

Versions: https://www.npmjs.com/package/@blockrun/mcp?activeTab=versions. Report what broke at https://github.com/BlockRunAI/blockrun-mcp/issues with the two version numbers.

Common mistakes

Mistake	Reality
npm install -g @blockrun/mcp to upgrade	The client runs npx, which ignores the global install. Re-register instead.
Editing ~/.npm/_npx/**/package.json	It is a cache. Delete it, don't edit it.
Restarting only the terminal	The MCP process belongs to the client session. Restart the client (or /mcp reconnect in Claude Code).
Assuming the skills upgraded too	They are files you copied. skills install --force.