MCP tool discovery fails after restart - custom Python MCP servers not loading

Description

Custom Python-based MCP servers show as "Connected" in claude mcp list but their tools don't appear in ToolSearch or are unavailable for use after Claude Code restarts. Tools work initially but fail to load after subsequent restarts, requiring multiple restart attempts.

Environment

• Claude Code Version: (auto-detected)
• OS: Windows 11 Pro 10.0.26200
• Platform: win32
• MCP Servers Affected: 15+ custom Python pyodbc SQL servers
• MCP Script: C:/Users/twhitney/.claude/scripts/mssql_pyodbc_server.py

Steps to Reproduce

1. Configure 15+ custom Python MCP servers using the pyodbc script pattern:

``bash
claude mcp add mssql-test-ordering-v3 -s local \
-e MSSQL_SERVER=azusw2sql1t.database.windows.net \
-e MSSQL_DATABASE=Ordering_v3 \
-e MSSQL_USER=orderinguser \
-e MSSQL_PASSWORD=xxx \
-- python C:/Users/twhitney/.claude/scripts/mssql_pyodbc_server.py
``

1. Verify tools work: ToolSearch("select:mcp__mssql-test-ordering-v3__execute_sql") returns the tool
2. Use the tools successfully in a session
3. Restart Claude Code completely (Ctrl+C and relaunch)
4. Run claude mcp list - servers show "✓ Connected"
5. Try ToolSearch("select:mcp__mssql-test-ordering-v3__execute_sql") - returns "No matching deferred tools found"
6. Attempt to use tool directly - "Error: No such tool available"
7. Restart Claude Code again (sometimes 2-3 times)
8. Tools eventually load and work again

Expected Behavior

MCP tools should consistently load after every Claude Code restart if the server shows as "Connected".

Actual Behavior

• MCP servers show "✓ Connected" in claude mcp list
• Tools are not discoverable via ToolSearch
• Tools return "No such tool available" when invoked directly
• Requires multiple restart attempts before tools become available
• Works fine once loaded, but fails on subsequent restarts

Evidence

Session transcript showing:

1. Tools working successfully (queries to mcp__mssql-prod-score-na__execute_sql and mcp__mssql-prod-score-eu__execute_sql)
2. After restart: claude mcp list shows all servers as "✓ Connected"
3. After restart: ToolSearch returns "No matching deferred tools found" for all SQL MCP tools
4. Direct Python connection test proves credentials and server are valid
5. After 2nd restart: Tools load successfully again

Impact

Critical for QA workflows - blocks skills that depend on database access:

• find-demos (JenkonSU queries)
• select-test-account (Cosmos + SQL)
• setup-demos (Score DB access)
• commissions workflows
• Ad-hoc SQL diagnostics

Workaround

Direct Python connection bypasses MCP:

import pymssql
conn = pymssql.connect(server='...', user='...', password='...', database='...')
# works consistently

Suspected Root Cause

Race condition in tool discovery timing - MCP server processes start and connect successfully, but tool registration happens before the server is ready to expose its tool list.

Additional Context

• All MCP servers use the same Python script pattern
• Only affects custom Python MCP servers (Azure, Playwright MCPs load fine)
• Server count: 15+ SQL MCP servers (may be related to scale)
• Intermittent - works ~50% of restarts, requires 1-3 restart attempts