Diagnose MCP servers with grok mcp doctor

grok mcp doctor [name] diagnoses MCP configuration and connectivity. Official: MCP Servers.

CLI doctor

1. List configured servers: grok mcp list.
2. Diagnose all servers, or one by name:

grok mcp doctor
grok mcp doctor filesystem

3. Add --json when you want machine-readable output from list or doctor:

grok mcp list --json
grok mcp doctor filesystem --json

4. For a stdio server that starts but fails to connect, read stderr at ~/.grok/logs/mcp/<name>.stderr.log.
5. Cold-start npx servers that download packages on first launch may need a higher startup_timeout_sec in ~/.grok/config.toml (default 30).

[mcp_servers.filesystem]
command = "npx"
args = ["-y", "@modelcontextprotocol/server-filesystem", "/path/to/dir"]
startup_timeout_sec = 60

TUI checks

Control	What it does
/mcps	Open the MCP tab of the extensions modal
Space	Toggle a server
r	Refresh after config edits
i	Authenticate OAuth servers
a / x	Add or remove

grok inspect shows every loaded server and its origin (including merged ~/.claude.json, .cursor/mcp.json, and project .mcp.json entries under config.toml priority).

Pitfalls

• Skipping stderr logs when a stdio server dies after spawn — the path is ~/.grok/logs/mcp/<name>.stderr.log.
• Leaving the default 30s startup_timeout_sec on a cold npx install that needs a longer first download.
• Expecting Bot marketplace Ahrefs failures to clear through Build grok mcp doctor — that connector lives on Grok Bot; see When the Ahrefs connector fails to load in Grok Bot.