MCP stdio server hangs indefinitely - server works fine when tested directly

Description

Custom MCP server (FastMCP, Python, stdio transport) hangs indefinitely when called through Claude Code. The same server responds in 2-5 seconds when tested directly via stdio pipe.

Environment

• Claude Code v2.1.86
• Windows 11 (10.0.26200)
• Python 3.11.9
• FastMCP (mcp package v1.26.0)
• Model: Claude Opus 4.6

Steps to reproduce

1. Register a Python MCP server that makes HTTP API calls (Azure AI Search + Azure OpenAI):

``
claude mcp add azure-brain -- python C:/path/to/server.py
``

1. Call any tool on the server from Claude Code - it hangs at "Running..." for 4-11+ minutes, never returns.

1. Test the same server directly via stdio - it works perfectly:

``bash
printf '{"jsonrpc":"2.0","id":1,"method":"initialize","params":{"protocolVersion":"2024-11-05","capabilities":{},"clientInfo":{"name":"test","version":"1.0"}}}\n{"jsonrpc":"2.0","id":2,"method":"tools/call","params":{"name":"mcp_search_thoughts","arguments":{"query":"test","limit":2}}}\n' | python server.py 2>/dev/null
``
Returns valid JSON-RPC response in ~2 seconds.

1. Test the same logic via CLI (no MCP) - works in 2-5 seconds:

``bash
python server.py --search "test" --limit 2
``

What I've tried

• Restarting Claude Code (multiple times)
• Removing and re-adding the MCP server registration (claude mcp remove + claude mcp add)
• Adding 30-second timeouts to the Azure SDK HTTP clients
• Verifying env vars are set in the MCP registration
• Confirming the server uses stderr for logging (stdout is clean JSON-RPC only)

None of these fixed the issue.

Key observations

• Other MCP servers work fine in the same session (gemini-research, graph-mcp, ms365, chrome-devtools, remote-agent)
• Server is healthy - responds correctly when tested via stdio pipe directly
• CLI works - same Python code, same Azure API calls, returns in seconds
• ToolSearch finds the tools - Claude Code can list the server's tools, just can't call them
• The server uses the same pattern as my working gemini-research server: FastMCP + mcp.run(transport="stdio") with synchronous tool functions
• The server makes multiple sequential HTTP calls per tool invocation (embed -> search, or embed -> metadata -> dedup -> upload)
• Issue persists across Claude Code restarts and MCP re-registrations

Server code pattern

from mcp.server.fastmcp import FastMCP

mcp = FastMCP("azure-brain")

@mcp.tool()
def mcp_search_thoughts(query: str, limit: int = 10) -> str:
    # Makes 1 Azure OpenAI call (embedding) + 1 Azure AI Search call
    return search_thoughts(query, limit=limit)

@mcp.tool()
def mcp_capture_thought(content: str, project: str = "") -> str:
    # Makes 2-4 Azure API calls sequentially
    return capture_thought(content, project=project)

mcp.run(transport="stdio")

Workaround

Using CLI mode (python server.py --search/--capture/--list) for all brain operations instead of MCP tools. This works reliably but loses the MCP integration benefits.