Triage Agent Skill

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