docs(grok): raise startup_timeout_sec before the first npx run (closes #144)

README.md

@@ -153,10 +153,43 @@ claude mcp add blockrun -s user -- npx -y @blockrun/mcp@latest
 | **Cursor** | 📝 Documented | ✅ | `~/.cursor/mcp.json` — JSON below |
 | **VS Code (Copilot)** | 📝 Documented | ✅ | `code --add-mcp '{"name":"blockrun","command":"npx","args":["-y","@blockrun/mcp@latest"]}'` |
 | **Gemini CLI** | 📝 Documented | ❌ | `gemini mcp add -s user blockrun npx -y @blockrun/mcp@latest` |
+| **Grok** | 📝 Documented · see the timeout note | ❌ | `grok mcp add blockrun -- npx -y @blockrun/mcp@latest` — **raise `startup_timeout_sec` first**, below |
 | **Windsurf** | 📝 Documented | ❌ | `~/.codeium/windsurf/mcp_config.json` — JSON below |
 
 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`](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](https://docs.x.ai/build/features/mcp-servers)). 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):
+
+```toml
+[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:
+
+```bash
+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](https://github.com/BlockRunAI/blockrun-mcp/issues/144) 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:
 
 ```bash

skills/blockrun-debug/SKILL.md

@@ -14,6 +14,9 @@ triggers:
   - "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"
@@ -63,6 +66,7 @@ re-added at user scope leaves a duplicate. Then, in the session: `blockrun_walle
 | 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 `BLOCKRUN_API_KEY` is set. | Unset `BLOCKRUN_API_KEY` and restart to use a wallet. |
 | 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. **Not charged** — payment settles on completion only. | Retry, or pick a faster model. Do not retry-loop; jobs take 60–180 s. |
 | `blockrun_price` with `category:"stocks"` / `"usstock"` → `Equity quotes are not served (gateway 501 …)` | The gateway withdrew equity price/history on 2026-09-05 (licensing), and the tool answers before the wallet is consulted. Not an outage. **Not charged.** | Do not retry. `action:"list" category:"stocks" market:"us"` still returns the ticker catalog for free. Equity coverage: hello@blockrun.ai. |

skills/blockrun-setup/SKILL.md

@@ -1,12 +1,15 @@
 ---
 name: blockrun-setup
-description: "Use when asked to install, add, configure, or set up the BlockRun MCP server (@blockrun/mcp) in Claude Code, Claude Desktop, Cursor, Windsurf, Codex CLI or another MCP client — including first-run wallet creation, funding with USDC, choosing a tool profile, and proving the install works. Also use when a fresh install 'doesn't show up' or a user asks how to pay for calls."
+description: "Use when asked to install, add, configure, or set up the BlockRun MCP server (@blockrun/mcp) in Claude Code, Claude Desktop, Cursor, Windsurf, Codex CLI, Grok or another MCP client — including first-run wallet creation, funding with USDC, choosing a tool profile, and proving the install works. Also use when a fresh install 'doesn't show up' or a user asks how to pay for calls."
 triggers:
   - "install blockrun"
   - "add blockrun mcp"
   - "set up blockrun"
   - "blockrun setup"
   - "claude mcp add blockrun"
+  - "grok mcp add blockrun"
+  - "blockrun unavailable"
+  - "mcp server timed out"
   - "@blockrun/mcp"
   - "fund my blockrun wallet"
   - "how do I pay for blockrun"
@@ -62,6 +65,24 @@ codex mcp add blockrun --env PATH="$PATH" -- npx -y @blockrun/mcp@latest
 For a JSON client with nvm/Homebrew Node, put the absolute `npx` path (`which npx`) in
 `command` — there is no `-e PATH` equivalent there.
 
+**Grok** — raise the startup timeout BEFORE the first run. Grok waits
+`startup_timeout_sec` (default **30**) for the server to answer, and a cold `npx -y` has
+to download this package and its dependencies first: measured 17s on a fast connection,
+42-46s on a slower box. Lose that race and the UI says `blockrun [unavailable]` for an
+install that is merely still downloading. In `~/.grok/config.toml`:
+
+```toml
+[mcp_servers.blockrun]
+command = "npx"
+args = ["-y", "@blockrun/mcp@latest"]
+enabled = true
+startup_timeout_sec = 120
+```
+
+Or sidestep it: `npm install -g @blockrun/mcp@latest` then
+`grok mcp add blockrun -- blockrun-mcp`, which launches an already-installed binary.
+Only the first run is slow either way — npx caches by exact spec.
+
 **Optional flags** (append after `@latest`): `--profile trading|research|media|chat`
 exposes a smaller tool set so the client loads fewer schemas. Omit for all <!-- br:mcp.tools -->19<!-- /br:mcp.tools --> tools.