Document Grok MCP install timeout workaround

[0xCheetah1]

Summary

When adding BlockRun MCP to Grok bot with the normal npx config, first-time users can see the MCP server show as unavailable because Grok's default MCP startup timeout is too short for a cold npx install.

Repro

On a clean machine/cache:

grok mcp add blockrun -- npx -y @blockrun/mcp@latest
grok mcp doctor blockrun

Observed:

blockrun (stdio: npx -y @blockrun/mcp@latest)
  ✓ command found (/usr/bin/npx)
  ✓ server started (0.0s)
  ✗ server timed out (no response within 30s)
  → try increasing startup_timeout_sec in config.toml

In the Grok UI this appears as:

blockrun [unavailable]

Cause

Grok waits about 30 seconds for the MCP server to handshake. With the npx -y @blockrun/mcp@latest form, the first run may need to download/install the package and its dependency tree before the MCP server can start.

In testing on the shared testbed, cold npx startup took around 42-46 seconds. After the npm cache was warm, it started fast enough and passed.

Suggested docs

For Grok users who want the non-global npx install, document this config:

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

This allows the first cold install to complete and handshake successfully.

Alternative

Users can avoid the cold npx startup cost by installing globally:

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

That makes Grok launch the already-installed blockrun-mcp binary directly.

Why this matters

New users following the simple grok mcp add blockrun -- npx -y @blockrun/mcp@latest instruction may think BlockRun MCP is broken when it is only timing out during first install. Adding Grok-specific instructions would make the first-run experience clearer.

[VickyXAI]

Confirmed and documented — PR #146.

I checked the load-bearing details against xAI's own MCP docs before writing them down: ~/.grok/config.toml, the [mcp_servers.<name>] table, and startup_timeout_sec defaulting to 30 are all exactly as you have them. Their docs even call out the npx-first-run download case.

Then I measured the cold start here rather than repeating your number:

	handshake
Cold, empty npm cache, fast connection	16.6s
Warm, same cache	8.8s
Your shared testbed, cold	42-46s

That spread is the real finding. Under 30 on one machine, well over it on another, so a user hits this intermittently and reasonably concludes the package is broken. The docs give the range and the cause instead of one machine's number.

Three places, per your suggestion:

• README — Grok now has a row in the client table plus a note with the startup_timeout_sec = 120 config and the npm install -g alternative, and says only the first run pays it (npx caches by exact spec).
• skills/blockrun-setup — same guidance where someone installing actually reads, with grok mcp add blockrun and blockrun unavailable as triggers so the skill fires on the symptom.
• skills/blockrun-debug — a symptom row that leads with nothing was charged, since the server never started, and gives the check that separates "still downloading" from "actually broken": run npx -y @blockrun/mcp@latest in a terminal and see whether it answers.

One thing added beyond the report: the note says this is not Grok-specific. Any client with a startup timeout can lose the same race against our dependency tree — Grok is just where it bites hardest, because 30s is the tightest default we know of.

Good catch. This is the failure mode that costs users before they ever reach a tool call.