triage

# Triage MCP server failures with mcptoon Work top-down; stop as soon as the layer with the fault is found. ## 1. Read the config layer first ```bash mcptoon doctor ``` Catches: invalid JSON, unknown fields, missing binaries for stdio commands, malformed URLs. Fix anything reported before deeper probing. ## 2. Check connectivity ```bash mcptoon health # every server, human-readable mcptoon health --json # CI/CD friendly, exit 1 if any dead ``` ## 3. Probe the tool layer ```bash mcptoon list # is the server even registered? mcptoon manifest --compact # do its tools appear at all? mcptoon inspect <server> <tool> # full schema of one tool mcptoon call <server> <tool> '{}' --toon # minimal live call ``` `list` shows it but `manifest` does not → the server answers initialize but fails tools/list: read the server's own logs (run its command manually). ## Common failures → fixes | Symptom | Likely cause | Fix | |---|---|---| | doctor: binary not found | command not on PATH | fix PATH, or install the package, or use npx/uvx | | health: timeout | server hangs on startup | raise timeout, or fix slow startup; try running the command directly | | call: unknown tool | tool toggled off | check the toggle on that tool in config, then `mcptoon sync` | | call: schema error | wrong args shape | `mcptoon inspect` the tool and match the inputSchema exactly | | stdio: spawn ENOENT | bad command token | command must be one token on PATH ...