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

mcptoon doctor

Catches: invalid JSON, unknown fields, missing binaries for stdio commands, malformed URLs. Fix anything reported before deeper probing.

2. Check connectivity

mcptoon health            # every server, human-readable
mcptoon health --json     # CI/CD friendly, exit 1 if any dead

3. Probe the tool layer

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

mcptoon sync        # push the repaired config to all agents
mcptoon health      # prove it is green