Immutable. This exact content is served forever at /api/v1/blob/1a09a1a8e3edeaa9.
---
name: triage
description: Diagnose and fix broken MCP servers in mcptoon — doctor, health, per-server probes, and the common failure playbook.
---
# 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 or `./relative`; never a shell string |
| everything dead after edit | config overwritten by hand in agent dir | re-edit `~/.mcptoon/config.json`, run `mcptoon sync` |
## After fixing
```bash
mcptoon sync # push the repaired config to all agents
mcptoon health # prove it is green
```