Skip to content

codex-mcp-failured_notes.md

Latest commit

 

History

History
95 lines (70 loc) · 3.37 KB

codex-mcp-failured_notes.md

File metadata and controls

95 lines (70 loc) · 3.37 KB

Codex MCP failure notes (taskbeacon)

Symptom

You see something like:

  • MCP client for taskbeacon failed to start: ... handshaking ... connection closed: initialize response

That message means: the MCP client spawned the server process, but the server exited (or the stdio streams closed) before it replied to the MCP initialize request.

What I verified on this machine

  • Running D:\Python310\python.exe -u E:\xhmhc\TaskBeacon\taskbeacon-mcp\taskbeacon_mcp\main.py --stdio from a normal shell exits quickly with no output.
    • This is expected when the process has no MCP client connected: MCP stdio servers read JSON-RPC lines from stdin. If stdin is closed/empty, the server can exit.
  • When launched via an MCP stdio client (keeps stdin open and sends initialize), the server works.
    • initialize.protocolVersion = 2025-06-18
    • tools: Build_task, download_task, localize, list_voices, list_tasks
    • prompts: ransform_prompt, localize_prompt, choose_template_prompt, choose_repo_prompt

So: this is typically a client launch/config issue or an environment/import issue, not a protocol mismatch in askbeacon_mcp.

Most common root causes

  1. Missing Python dependencies in the exact interpreter you configured

    • If D:\Python310\python.exe doesn’t have the deps, the process can crash on import and the client reports a handshake failure.

  2. Client is not actually running stdio transport correctly

    • If the client closes stdin immediately (or never sends JSON-RPC), the server can exit and you’ll see the same handshake error.

  3. Wrong config / wrong entrypoint path

    • Wrong file path, wrong python, or a config format mismatch can all lead to a process that exits instantly.

The smoke test (recommended)

This reproduces the client/server handshake locally and prints the tool list.

Run in PowerShell:

`powershell @' import anyio from mcp import StdioServerParameters, stdio_client, ClientSession

SERVER = StdioServerParameters( command=r"D:\Python310\python.exe", args=[ "-u", r"E:\xhmhc\TaskBeacon\taskbeacon-mcp\taskbeacon_mcp\main.py", # optional; this server ignores --stdio, but keeping it doesn't hurt "--stdio", ], )

async def main(): async with stdio_client(SERVER) as (r, w): async with ClientSession(r, w) as s: await s.initialize() tools = await s.list_tools() print([t.name for t in tools.tools])

anyio.run(main) '@ | D:\Python310\python.exe - `

Expected output includes:

  • ['build_task', 'download_task', 'localize', 'list_voices', 'list_tasks']

If this fails, the printed traceback is your real root cause.

Fix: install deps into that interpreter

From repo root:

powershell D:\Python310\python.exe -m pip install -e E:\xhmhc\TaskBeacon\taskbeacon-mcp

Recommended Codex config

In C:\Users\Zhipeng.codex\config.toml, prefer the module entrypoint instead of a direct .py path:

oml [mcp_servers.taskbeacon] command = "D:\\Python310\\python.exe" args = ["-u", "-m", "taskbeacon_mcp.server"]

Notes:

  • --stdio is not required for this server (it always runs stdio).
  • If you keep the .py entrypoint, it should still work.

Where to look for details (Codex)

Codex log:

  • C:\Users\Zhipeng.codex\log\codex-tui.log

Search for:

  • MCP client for + Failed to start
  • MCP server stderr

Those lines usually contain the actual exception (import error, path error, etc.).