MCP server fails to start in Claude Code on macOS (stdio handshake never completes)

[paddymul]

Summary

The buckaroo-table MCP server (installed via claude mcp add) fails to connect in Claude Code CLI. The server process starts successfully and the asyncio event loop runs, but the MCP JSON-RPC handshake never completes. Claude Code reports "Failed to reconnect to buckaroo-table."

This works on another machine — need to diagnose what differs.

Install command

claude mcp add buckaroo-table -- uvx \
  --from "buckaroo[mcp]==0.12.9.dev22314929241" \
  --index-url https://test.pypi.org/simple/ \
  --extra-index-url https://pypi.org/simple/ \
  --index-strategy unsafe-best-match \
  buckaroo-table

Environment

• macOS Darwin 25.0.0 (Apple Silicon)
• Claude Code CLI (Opus 4.6)
• Python 3.13 via uv/uvx 0.9.28
• mcp package version: 1.26.0
• buckaroo[mcp] version: 0.12.9.dev22314929241

Observed behavior

What the logs show (~/.buckaroo/logs/mcp_tool.log)

The server process starts fully — all handlers register, parent watcher starts, event loop begins:

12:04:34 [INFO]  MCP tool starting — server=http://localhost:8700 session=6e90500d8185
12:04:34 [DEBUG] Initializing server 'buckaroo-table'
12:04:34 [DEBUG] Registering handler for ListToolsRequest
12:04:34 [DEBUG] Registering handler for CallToolRequest
12:04:34 [DEBUG] Registering handler for ListResourcesRequest
12:04:34 [DEBUG] Registering handler for ReadResourceRequest
12:04:34 [DEBUG] Registering handler for PromptListRequest
12:04:34 [DEBUG] Registering handler for GetPromptRequest
12:04:34 [DEBUG] Registering handler for ListResourceTemplatesRequest
12:04:34 [INFO]  Parent watcher: original ppid=95944
12:04:34 [DEBUG] Using selector: KqueueSelector

But no MCP protocol messages are ever processed — no ListToolsRequest, no initialize response. The server is alive and listening on stdio, but the handshake never happens.

What Claude Code reports

Failed to reconnect to buckaroo-table.

Manual testing works fine

Running the exact same command manually with an initialize message piped to stdin works perfectly:

echo '{"jsonrpc":"2.0","id":0,"method":"initialize","params":{...}}' | \
  uvx --from "buckaroo[mcp]==0.12.9.dev22314929241" ... buckaroo-table
# Returns valid JSON-RPC response immediately

What has been ruled out

Hypothesis	Result
uvx pollutes stdout	Ruled out — 0 bytes to stdout during install/resolution. All output goes to stderr.
Startup too slow	Ruled out — uvx launches in ~0.4s (warm cache), well under any timeout.
Port conflict on :8700	Ruled out — MCP uses stdio, data server only starts on-demand.
Code bugs in buckaroo_mcp_tool.py	Ruled out — logging goes to file only, no stdout leaks, clean stdio transport.
Python/package not found	Ruled out — process starts and event loop runs.

Suspected root cause

The stdio_server() in mcp 1.26.0 creates a new TextIOWrapper(sys.stdout.buffer) for the transport. There may be a buffering or timing issue where:

1. Claude Code sends the initialize message before the server's wrapped stdin reader is fully ready
2. The message gets consumed by the old sys.stdin wrapper and is lost before the new anyio.wrap_file() wrapper takes over
3. The server blocks waiting for a message that was already consumed, and Claude Code times out waiting for a response

This would explain why:

• Manual testing works (the message is already in the pipe when the server starts)
• Claude Desktop works (it does a probe-close-reconnect dance that retries the init)
• Claude Code fails (it may send init once and expect a response within a tight window)

Diagnostic request

This artifact works on another machine. To diagnose the difference, on the working machine please check:

1. mcp package version: python -c "from importlib.metadata import version; print(version('mcp'))"
2. buckaroo package version: python -c "from importlib.metadata import version; print(version('buckaroo'))"
3. OS and Python version
4. Contents of ~/.buckaroo/logs/mcp_tool.log — does it show protocol messages being processed?
5. uvx --version
6. Does ~/.buckaroo/logs/mcp_tool.log show Processing request of type ListToolsRequest etc. after startup?

Related

• Branch: mcp_punchlist / feat_mcp_punclist
• PR: fix: summary stats inherit alignment for count and freq rows #545

[paddymul]

Diagnosis from a working machine

I have buckaroo MCP working on another macOS machine (Darwin 22.6.0). Here's what I found comparing the two setups.

Key difference: launch method

My working config uses uv run with a local dev checkout:

{
  "command": "uv",
  "args": ["run", "--directory", "/Users/paddy/cl_buckaroo", "python", "-m", "buckaroo.mcp_tool"],
  "env": {}
}

Your broken config uses uvx with TestPyPI resolution:

uvx --from "buckaroo[mcp]==0.12.9.dev22314929241" \
  --index-url https://test.pypi.org/simple/ \
  --extra-index-url https://pypi.org/simple/ \
  --index-strategy unsafe-best-match \
  buckaroo-table

Environment comparison

Factor	Working (my machine)	Broken (your machine)
Launch method	uv run --directory <local-project>	uvx --from <test-pypi-pkg>
macOS	Darwin 22.6.0 (Ventura)	Darwin 25.0.0 (Tahoe)
uv version	0.6.16	0.9.28
mcp version	1.26.0	1.26.0
Entry point	python -m buckaroo.mcp_tool (module)	buckaroo-table (console_scripts)

Log comparison

Working — full handshake completes immediately:

11:07:03 [DEBUG] Using selector: KqueueSelector
11:07:03 [DEBUG] Received message: root=InitializedNotification(...)
11:07:03 [INFO]  Processing request of type ListToolsRequest
11:07:03 [INFO]  Processing request of type ListPromptsRequest
11:07:03 [INFO]  Processing request of type ListResourcesRequest

Broken — startup completes but no messages are ever received:

12:04:34 [DEBUG] Using selector: KqueueSelector
(... nothing after this ...)

Three candidate causes

1. uvx vs uv run — Biggest suspect. uvx creates an ephemeral virtual environment and may interact with stdin/stdout differently during package resolution/setup. The working machine avoids this entirely by using uv run against a pre-built local .venv. The newer uvx (0.9.28 vs 0.6.16) may have changed how it sets up stdio file descriptors before handing off to the entry point.

2. Entry point difference — The working machine runs python -m buckaroo.mcp_tool (direct module execution). The broken machine runs the buckaroo-table console_scripts entry point. Console_scripts goes through a generated wrapper script, which adds another layer that could interfere with stdio inheritance.

3. macOS version — Darwin 22.6.0 vs 25.0.0. Less likely to be primary cause, but macOS Tahoe (25.0) may have different default buffering behavior for pipes.

Suggested next steps to isolate the cause

1. Try the working configuration on your machine: clone the repo, checkout mcp_punchlist branch, then use uv run --directory <local-checkout> python -m buckaroo.mcp_tool as the MCP config. If this works, it's the uvx/entry-point path that's broken.
2. Try uvx on your machine but with python -m to isolate whether it's the entry point wrapper or uvx itself: uvx --from "buckaroo[mcp]==0.12.9.dev22314929241" --index-url ... python -m buckaroo.mcp_tool
3. Downgrade uv to 0.6.x on your machine to test the uv version hypothesis.

[paddymul]

Findings from the "broken" machine (Darwin 25.0.0, uv 0.9.28)

TL;DR — The MCP handshake works fine. The /Users/paddy/buckaroo project has a misconfigured MCP command.

Tests performed

I tested all three launch methods suggested in the issue, sending an MCP initialize JSON-RPC message via stdin and reading stdout:

Method	Result	Time
uv run --directory <local-checkout> python -m buckaroo_mcp_tool	PASS — valid serverInfo response	~0.3s
uvx --from "buckaroo[mcp]" python -m buckaroo_mcp_tool	PASS	~0.3s
uvx --from "buckaroo[mcp]" buckaroo-table (entry point)	PASS	~0.3s
uvx --from "buckaroo[mcp]==0.12.9.dev22314929241" --index-url ... buckaroo-table (TestPyPI)	PASS	~0.3s

All four methods work. The MCP server itself is not broken on this machine.

Root cause: misconfigured MCP command in /Users/paddy/buckaroo project

The Claude Code settings (~/.claude.json) for the /Users/paddy/buckaroo project have:

{
    "command": "uvx",
    "args": ["--reinstall", "buckaroo[mcp]", "buckaroo-table"]
}

This is broken uvx syntax. Testing it:

$ uvx --reinstall "buckaroo[mcp]" buckaroo-table
warning: Tools cannot be reinstalled via `uvx`; use `uv tool upgrade --all --reinstall`...
An executable named `buckaroo` is not provided by package `buckaroo`.
The following executables are available:
- buckaroo-table
Use `uvx --from buckaroo buckaroo-table` instead.

Two problems:

1. --reinstall is a uv tool flag, not valid for uvx
2. Without --from, buckaroo[mcp] is treated as the command name, not the package

The fix

Change the MCP config for /Users/paddy/buckaroo to either:

Option A — uvx with --from (recommended for installed packages):

{
    "command": "uvx",
    "args": ["--from", "buckaroo[mcp]", "buckaroo-table"]
}

Option B — uv run against local checkout (recommended for development):

{
    "command": "uv",
    "args": ["run", "--directory", "/Users/paddy/code/buckaroo", "python", "-m", "buckaroo_mcp_tool"]
}

What about /Users/paddy/code/claude_buck_test?

The MCP config for this project uses the correct --from syntax with TestPyPI index URLs, and it works — I can see the buckaroo-table tools (view_data, buckaroo_table, buckaroo_diagnostics) in my current Claude Code session.

Diagnostic output

Buckaroo MCP Startup Diagnostics
Timestamp: 2026-02-23 12:31:10 EST

Python:       3.13.11 (Clang 21.1.4)
Platform:     macOS-26.0.1-arm64-arm-64bit-Mach-O
uvx:          0.9.28

uvx stdout pollution: 0 bytes — OK
uvx startup timing:   cold=0.05s warm=0.05s
MCP handshake:        0.32s — OK, got serverInfo
Port 8700:            nothing listening

Protocol note

The MCP Python SDK (mcp package) stdio transport uses newline-delimited JSON (one JSON object per line), NOT HTTP-style Content-Length framing. The initial diagnostic script and tests I wrote used Content-Length framing, which caused the server to log validation errors. Fixed now.

New tests & diagnostics added

On branch mcp_punchlist:

• tests/unit/server/diagnose_mcp_startup.py — standalone diagnostic script (run on any machine)
• tests/unit/server/test_mcp_uvx_install.py — 5 integration tests exercising the real uvx install path
• tests/unit/server/test_mcp_tool_cleanup.py — added TestStdoutSafety::test_no_stdout_during_import

All 6 new tests pass. Run with: .venv/bin/python -m pytest tests/unit/server/test_mcp_uvx_install.py tests/unit/server/test_mcp_tool_cleanup.py::TestStdoutSafety -v

[paddymul]

Implementation Plan

Overview

Fix the MCP stdio transport so the JSON-RPC handshake completes successfully on macOS.

Steps

1. Diagnose the hang — add debug logging at the MCP server entry point to trace:

   • Is sys.stdin readable? (check if it's a pipe vs TTY)
   • Is the JSON-RPC initialize request arriving?
   • Is the response being written to sys.stdout?
   • Is stdout buffered? (common macOS issue with Python stdio)

2. Fix stdout buffering — likely root cause: Python buffers stdout by default. Add at server startup:

   • sys.stdout = io.TextIOWrapper(sys.stdout.buffer, write_through=True) or
   • os.environ['PYTHONUNBUFFERED'] = '1' before subprocess launch
   • Or use sys.stdout.buffer.write() + flush() for MCP responses

3. Fix stdin reading — ensure the MCP server reads from stdin in a non-blocking asyncio-compatible way:

   • Use asyncio.StreamReader wrapping sys.stdin.buffer
   • Don't use synchronous input() or sys.stdin.readline() in the async event loop

4. Test — add a CI test that starts the MCP server via stdio transport, sends an initialize request, and verifies a response within 5 seconds.

Files to modify

• buckaroo/mcp_tool.py or MCP server entry point — stdio buffering fix
• MCP transport layer — asyncio stdin/stdout handling

@codex

[chatgpt-codex-connector]

Summary

• Added MCP stdio preflight hardening in both MCP entrypoint modules by:
  • classifying stdin/stdout stream types for diagnostics, and
  • forcing stdout write-through + line buffering before MCP runtime starts, to reduce handshake stalls caused by buffering. buckaroo_mcp_tool.pyL43-L87 buckaroo_mcp_tool.pyL488-L491 buckaroo/mcp_tool.pyL43-L87 buckaroo/mcp_tool.pyL488-L491
• Added unit tests to verify stdio configuration behavior:
  • main() invokes stdio setup before starting watcher/runtime, and
  • _configure_stdio_for_mcp() calls reconfigure(line_buffering=True, write_through=True) when available. tests/unit/server/test_mcp_tool_cleanup.pyL486-L516
• Added a slow integration test (gated by BUCKAROO_MCP_CMD) that launches the real stdio MCP command and asserts initialize receives a JSON-RPC response within 5 seconds. tests/unit/server/test_mcp_server_integration.pyL206-L259

Testing

• ✅ pytest -q tests/unit/server/test_mcp_tool_cleanup.py -k 'StdioConfiguration or no_stdout_during_import'
• ⚠️ pytest -q tests/unit/server/test_mcp_server_integration.py -k initialize_responds_within_5_seconds -m slow (skipped because BUCKAROO_MCP_CMD is not configured in this environment)
• ✅ python -m py_compile buckaroo_mcp_tool.py buckaroo/mcp_tool.py

Committed on current branch as:
cc7a6c7

Also created the follow-up PR entry via make_pr with title:
“Harden MCP stdio startup and add initialize timing coverage”.

View task →

[paddymul]

Related: PR #578

PR #578 (merged, commit e392c78): "fix: MCP + server reliability, observability, and hardening" — this significantly improved MCP server reliability including:

• Server startup hardening
• Better error reporting and observability
• Reliability improvements for the stdio transport

Worth verifying if this issue still reproduces on the latest release. If the stdio handshake now completes, recommend closing.