jungho-git/public/codex/memories/skills/mcp-startup-smoke

MCP Startup Smoke

When to use

• Use for local Codex MCP startup failures, wrapper-path drift, service/auth suspicions, or install+smoke requests.
• Use when the visible symptom is only connection closed: initialize response, Transport closed, or a failed MCP client.
• Do not use for general remote API debugging that is not an MCP launcher/startup problem.

Inputs / context to gather

1. Read the active MCP block from %CODEX_HOME%\config.toml.
2. Read the latest failure lines from %CODEX_HOME%\logs\codex-tui.log.
3. Run codex mcp list to capture the resolved command / args / cwd shape.
4. Check whether the target binary/entry file/service/auth dependency actually exists:
   • wrapper or entry file path
   • local executable path
   • token source or gh auth state if GitHub-related
   • local service state if DB-related

Procedure

1. Start from the exact failing server name and the exact launcher error.
   • Do not reason from handshake text alone.
   • Pull the first decisive stderr line from codex-tui.log.
2. Confirm the current registration shape.
   • Use codex mcp list.
   • Compare it against config.toml.
   • Watch for stale local paths, wrong wrapper targets, bad cwd, or --no-install.
3. Reproduce the real server launch as directly as possible.
   • For Bun-based launchers, run the same bun x ... or wrapper entrypoint manually.
   • If --no-install is present, test whether the package is already runnable locally before blaming the flag itself.
4. Check server-specific prerequisites.
   • commander: exact dist entry path exists.
   • github: server exe path exists and token/gh auth is usable.
   • mysql: local Windows service is running and port is reachable.
   • filesystem: every allowed directory exists at startup.
5. Fix the earliest real breakpoint only.
   • Path mismatch before auth.
   • Service state before protocol theory.
   • Missing local runnable binary before config cleanup.
6. Validate in layers.
   • parse/read config successfully
   • codex mcp list shows enabled registration
   • direct JSON-RPC initialize
   • one small tool call or narrow smoke if appropriate
7. If the user requested install + test, finish with a minimal live smoke.
   • Example validated browser flow: initialize -> tools/list -> browser_navigate(https://example.com) -> browser_close.

Efficiency plan

1. Check codex-tui.log before broad searching.
2. Use codex mcp list before reading many files; it often reveals the wrong path immediately.
3. Reproduce only the failing server, not all MCPs, unless the user reported several together.
4. Stop once one early launcher breakpoint fully explains the visible handshake failure and the direct smoke passes.
5. Cache the resolved working command shape in notes/memory if the path is machine-specific.

Pitfalls and fixes

• Symptom: connection closed: initialize response
  • Likely cause: earlier launcher failure hidden by the handshake layer.
  • Fix: inspect codex-tui.log and run the exact launcher directly.
• Symptom: Could not find an existing '<pkg>' binary to run. Stopping because --no-install was passed.
  • Likely cause: package not already runnable locally.
  • Fix: remove --no-install or make sure the runnable binary/package/cache already exists.
• Symptom: GitHub MCP fails before protocol init.
  • Likely cause: wrong exe path or missing token source.
  • Fix: repair wrapper path first, then token normalization/auth fallback.
• Symptom: MySQL MCP starts but closes with ECONNREFUSED 127.0.0.1:3306
  • Likely cause: local MySQL service stopped/disabled.
  • Fix: check Get-Service -Name MySQL and port reachability.
• Symptom: Bun stderr appears during a successful smoke.
  • Likely cause: dependency resolution noise from bun x.
  • Fix: judge by JSON-RPC success and exit code, not stderr alone.

Verification checklist

1. config.toml still parses.
2. codex mcp list shows the target MCP enabled with the expected command shape.
3. Direct JSON-RPC initialize succeeds against the target server.
4. One narrow server-specific smoke succeeds:
   • browser navigate for Playwright
   • get_me for GitHub
   • service/initialize check for MySQL
5. Final note distinguishes confirmed fix from anything still unverified, such as missing UI/session restart.