doronkatz MCP Doctor
Use this skill for Codex-home tool startup and connector hygiene.
Workflow
- Read the relevant
~/.codex/config.tomlblock and the failing startup output before changing anything. - Classify the failure: TOML syntax, unsupported config key, missing binary, broken symlink, stale plugin cache path, auth/401, network/package fetch, initialize-response failure, or skill-loader warning.
- Validate narrowly:
- TOML with
tomllib. - Skill frontmatter with a YAML parser.
- Symlinks with
find skills -type l ! -exec test -e {} ; -print. - Configured commands with
command -vor explicit path checks.
- TOML with
- Fix the smallest surface that explains the failure.
- Re-run the narrow validator. If a full startup check hangs, stop it and report the hang rather than waiting indefinitely.
Guardrails
- Do not delete unrelated MCP entries.
- Do not expose or commit secrets.
- Prefer official package paths and current configured binaries over guesses.
- Mention restart requirements when Codex needs to reload skills, plugins, or MCP registrations.