Troubleshooting

Run the doctor first. npx @ask-llm/mcp doctor checks Node version, PATH, every provider CLI's presence + version, and env vars. It works even when MCP can't start. 90%+ of setup issues are caught here with a clear failed-check line; fix from the bottom of the report up.

npx @ask-llm/mcp doctor                       # human-readable
npx @ask-llm/mcp doctor --json                # established full JSON, exit 1 on error
npx @ask-llm/mcp doctor --format toon         # bounded, versioned agent-facing TOON pilot
npx @ask-llm/mcp doctor --format toon --full  # full TOON escape hatch

Installation Issues

"Command not found: gemini" / "codex" / "ollama"

Click to see solution

Provider CLI is not installed or not on PATH

"PATH issue": CLI works in terminal but MCP server says "not found"

Click to see solution

macOS GUI apps don't inherit your shell PATH

MCP server not responding (Claude Desktop cannot connect)

Click to see solution

Server fails to start or connection drops

EUNSUPPORTEDPROTOCOL workspace:* (npx fails to start)

Click to see solution

Stale npx cache from a pre-1.5.7 install poisons new runs. Clear it.

Connection & Auth

"Authentication failed" / "401 Unauthorized"

Click to see solution

Provider CLI isn't authenticated

Quota / rate limit errors (Gemini RESOURCE_EXHAUSTED, Codex 429)

Click to see solution

Provider quota exhausted

"Command timed out after Xs"

Click to see solution

Provider call exceeded the per-provider wall-clock timeout

Tool & API Issues

"Provider X is not available" / tool call rejects provider

Click to see solution

The orchestrator didn't detect the provider at startup

"Sub-agent silently produces 0-byte output" / brainstorm coordinator hang

Click to see solution

Provider process killed by sub-agent lifecycle

Model & Response Issues

Response gets cut off mid-stream

Click to see solution

MCP message size limits or executor timeout

Plugin Issues

Plugin slash commands not appearing in Claude Code

Click to see solution

Plugin not installed or not loaded

Debug Mode

Enable verbose logging:

{
  "mcpServers": {
    "ask-llm": {
      "command": "npx",
      "args": ["-y", "@ask-llm/mcp"],
      "env": {
        "GMCPT_LOG_LEVEL": "debug"
      }
    }
  }
}

Logs go to stderr. Claude Desktop captures them in:

• macOS: ~/Library/Logs/Claude/mcp-server-*.log
• Linux: ~/.config/claude/logs/

Getting Help

1. Run the doctor first: npx @ask-llm/mcp doctor
2. Check GitHub Issues for similar reports
3. Open a new issue with: doctor output, your client (Claude Code/Desktop/Cursor/etc.), Node version, OS, and what you ran
4. Ask in GitHub Discussions for usage questions