Summary

• Fixes a deadlock where every tools/call against vibe-trading-mcp hangs indefinitely while initialize and tools/list succeed.
• Pre-warms the tool registry in the main thread before mcp.run() so the first tools/call doesn't trigger heavy lazy imports inside FastMCP's asyncio worker thread.
• Affects all MCP clients (Claude Code, Cursor, etc.) — not specific to any one client.

Why

agent/mcp_server.py:68 — _get_registry() lazy-imports src.tools.build_registry and constructs the registry on first call. All 14 call sites in this file are FastMCP tool handlers, so the first tools/call triggers the lazy init inside FastMCP's asyncio worker thread. The import chain — specifically loading src.tools.shell.* — deadlocks in that thread context.

initialize and tools/list succeed because they don't touch the registry, which makes the bug confusing to diagnose: the server appears healthy until the first tool call, then hangs forever with no error.

Fix

One line in main(), right after _registry = None:

_include_shell_tools = True if args.transport == "stdio" else _env_shell_tools_enabled()
_registry = None
_get_registry()  # pre-warm: avoids deadlock when first tools/call lazy-inits inside FastMCP worker thread

_include_shell_tools is set on the line above, so the pre-warm builds the registry with the correct value for the chosen transport. _get_registry() is idempotent (if _registry is None guard at line 70), so the 14 existing call sites still hit the cached instance — unaffected.

Differential test (deterministic before/after)

Verified on Python 3.13, Windows 11, fastmcp 3.2.4 with a raw stdio MCP client:

Toggling the single line on/off flips behavior every time — root cause is conclusive.

Side effects

• No functional change to any tool's behavior or output.
• Errors during registry build now surface at startup (fail-fast) instead of at first tool call.
• Slight startup-time shift: cost previously paid on first tools/call is now paid during initialize. Net total unchanged.
• For SSE transport: HTTP server begins listening ~5–8s later. Flagging in case it matters for any healthcheck-sensitive deployment.

Test plan

• Differential test (table above) — deterministic before/after on raw stdio
• End-to-end via Claude Code MCP client — tools/call get_market_data and tools/call analyze_options both return in <2s
• Both stdio and SSE entry paths pick up the fix (pre-warm runs before either mcp.run(...) branch)

Checklist

• No changes to protected areas (agent/src/agent/, agent/src/session/, agent/src/providers/) — only agent/mcp_server.py.
• No hardcoded values.
• Code follows CONTRIBUTING.md (Conventional Commit title, no comment-preserved code).
• Documentation updated — N/A (no user-facing behavior change beyond bug fix).