[BUG] MCP connection crashes persistently when calling ha_search_entities tool

[lucianconstantin]

---

Bug Summary

MCP connection crashes persistently when calling ha_search_entities tool and only way to fix it is to restart Claude Code session. Restart of HA-MCP addon doesn't fix it.

What happened

When calling ha_search_entities (especially with multiple parallel calls), the MCP connection hangs and then all subsequent calls fail with "No valid session ID provided" errors. The only way to recover is to restart Claude Code completely.

What you expected

The ha_search_entities tool should return results without crashing the MCP connection.

Steps to reproduce

1. Connect to HA via ha-mcp from Claude Code
2. Call ha_search_entities (often with multiple parallel calls)
3. MCP connection drops, subsequent tool calls fail with session ID errors
4. Must restart Claude Code to restore connection

Error messages

No valid session ID provided

Environment (auto-populated)

• ha-mcp Version: 6.0.0
• Installation Method: addon
• Platform: Linux 6.12.51-haos (x86_64)
• Python Version: 3.13.11
• Home Assistant Version: 2026.1.0
• Connection Status: Connected
• Entity Count: 970
• Time Zone: Europe/Bucharest

---

Note: The crash happens before it can be logged, so the recent tool calls only show successful ha_rename_entity calls from before the crash.

---

🚀 Startup Logs (if relevant)

Details

[01/09/26 10:08:36] INFO Starting MCP server 'ha-mcp' with server.py:2582 transport 'streamable-http' on http://0.0.0.0:9583/private_U7hq3QU1 ki734-PTKi2HFw INFO: Started server process [1] INFO: Waiting for application startup. INFO: Application startup complete. INFO: Uvicorn running on http://0.0.0.0:9583 (Press CTRL+C to quit) INFO: 10.0.1.81:45798 - "POST /private_U7hq3QU1ki734-PTKi2HFw HTTP/1.1" 400 Bad Request

---

[julienld]

Note: This is an automated triage based on the analysis of this code base and public search (Web, Home Assistant Source code, ...).

I'm sorry you're experiencing these persistent crashes. This is a frustrating issue, especially since restarting the add-on doesn't fix it. Based on my research, this appears to be related to known issues with the MCP streamable-http transport and parallel tool calls.

What's Happening:

When you call ha_search_entities with multiple parallel calls, the MCP session appears to be getting into an invalid state, resulting in "No valid session ID provided" errors. This is particularly problematic because:

1. Session State Issues: The streamable-http transport maintains session state on the server side, and this session can get corrupted or lost
2. Parallel Call Problems: FastMCP has documented issues with parallel tool calls (see Issue #1625)
3. Connection Pool Limits: The httpx client used by ha-mcp doesn't explicitly configure connection pool limits, which could lead to resource exhaustion under parallel load

Workarounds Until Fixed:

• Avoid making multiple parallel calls to ha_search_entities - make them sequential instead
• If you must search multiple things, use a single call with broader query terms
• As you've discovered, restarting Claude Code is currently the only way to recover

Technical Analysis (for maintainers)

Codebase Analysis

Affected Files:

• src/ha_mcp/__main__.py: Lines 432 - runs streamable-http transport via main_web()
• src/ha_mcp/client/rest_client.py: Lines 79-86 - creates httpx.AsyncClient without explicit connection limits
• src/ha_mcp/tools/tools_search.py: Lines 115-398 - ha_search_entities implementation

Current Implementation:

The REST client creates an httpx.AsyncClient with default settings:

self.httpx_client = httpx.AsyncClient(
    base_url=f"{self.base_url}/api",
    headers={
        "Authorization": f"Bearer {self.token}",
        "Content-Type": "application/json",
    },
    timeout=httpx.Timeout(self.timeout),
)

No connection limits are specified, so it uses httpx defaults:

• max_connections: 100
• max_keepalive_connections: 20

Root Cause Analysis:

Based on web research, this is likely a combination of:

1. FastMCP Session Management Bug: Parallel calls fail intermittently with initialization errors
2. MCP Protocol Session State: Streamable-http sessions require sticky routing in load-balanced scenarios (Issue #880)
3. Resource Exhaustion: Multiple parallel get_states() calls (which ha_search_entities uses) could exhaust connection pools or cause race conditions

The startup log shows:

INFO:     10.0.1.81:45798 - "POST /private_U7hq3QU1ki734-PTKi2HFw HTTP/1.1" 400 Bad Request

This 400 error before the crash suggests the session ID was rejected by FastMCP's streamable-http handler.

Implementation Assessment

This requires multiple decisions from maintainers:

Option 1: Mitigate at ha-mcp Level

Approach: Add connection pool limits and request queuing

Changes:

• Configure httpx with explicit limits:

  self.httpx_client = httpx.AsyncClient(
      base_url=f"{self.base_url}/api",
      headers={...},
      timeout=httpx.Timeout(self.timeout),
      limits=httpx.Limits(
          max_connections=50,
          max_keepalive_connections=20
      )
  )

• Add semaphore-based rate limiting for get_states() calls
• Implement retry logic with exponential backoff

Pros:

• Can implement immediately without external dependencies
• Provides some protection against resource exhaustion
• Doesn't require FastMCP fixes

Cons:

• May not fully solve FastMCP session management bugs
• Could impact performance with artificial throttling
• Doesn't address root cause in FastMCP

Option 2: Work Around FastMCP Limitations

Approach: Detect parallel calls and serialize them automatically

Changes:

• Add request queue/lock in ha_search_entities tool
• Detect concurrent calls via AsyncIO primitives
• Force sequential execution with minimal user impact

Pros:

• Transparent to users (no API changes)
• Avoids FastMCP parallel call bugs
• Maintains backward compatibility

Cons:

• Slower when multiple searches are needed
• Adds complexity to tool implementation
• Doesn't fix underlying transport issue

Option 3: Report and Wait for FastMCP Fix

Approach: File detailed bug report with FastMCP team

Changes:

• Create minimal reproduction case
• Report to FastMCP issues
• Document workaround in ha-mcp docs
• Monitor for upstream fix

Pros:

• Addresses root cause
• Benefits entire FastMCP ecosystem
• No workarounds needed in ha-mcp code

Cons:

• Users suffer until fixed
• No control over fix timeline
• May require FastMCP architecture changes

Option 4: Switch to SSE Transport

Approach: Use Server-Sent Events transport instead of streamable-http

Changes:

• Modify main_sse() to be the default web transport
• Update documentation to prefer SSE for add-on use
• Keep streamable-http as fallback option

Pros:

• SSE is more mature and stable
• Avoids streamable-http session complexity
• May have better parallel call handling

Cons:

• SSE has its own limitations (no CORS, HTTP/2 issues)
• Requires user migration
• May hit different bugs

Priority Assessment

Priority: High

This is a critical user-facing bug that:

• Blocks normal usage: Multiple parallel tool calls are common in AI workflows
• Poor UX: Requires full Claude Code restart (add-on restart doesn't help)
• Affects production: Running on latest stable versions (HA 2026.1.0, ha-mcp 6.0.0)
• Known upstream issue: FastMCP has P1 bug for parallel calls

Comparing to other open issues:

• More severe than [BUG] ha_bulk_control returns empty operation list #385 (empty operation list) - that's a data issue, this crashes the server
• Similar severity to Investigate and fix flaky E2E tests in CI workflows #366 (flaky E2E tests) - but this affects real users in production
• Less severe than security issues would be, but still blocks core functionality

Labels Applied

• needs-choices: Multiple valid implementation approaches requiring stakeholder decision
• priority: high: Critical bug blocking normal usage patterns
• triaged: Analysis complete
• bug: Already applied

---

Automated triage by Claude Code

[lucianconstantin]

Is there a way to turn the addon's log level to debug? would that help?

I will try to force the crash again and get more info, because for now I explicitly told Claude to stop using ha_search_entities entirely and use other tools instead like hass-cli but the thing about parallel calls is something the AI agent added. To me it seemed it crashed any time it tried to do ha_search_entities because of the large response or the large number of entities.

Also, here is Claude's own analysis if it helps. Might be surface-level and wrong though.

● Found relevant info from FastMCP docs:

Key findings:

1. FastMCP's streamable-http transport uses session state
2. There's an EventStore feature for session resumability - but it needs to be explicitly configured
3. Sessions can be lost due to timeouts or connection issues
4. Without EventStore, clients can't resume after disconnection

The likely issue:
ha-mcp may not have EventStore configured, so:

• Session state exists only in memory
• Any disruption (timeout, network blip, HA restart) invalidates sessions
• Client (Claude Code) doesn't know to reconnect with new session

Two potential bugs to report:

1. ha-mcp (https://github.com/homeassistant-ai/ha-mcp/issues):
   - Should configure EventStore for session persistence
   - Should handle session resumability across restarts
2. Claude Code (https://github.com/anthropics/claude-code/issues):
   - MCP client should detect 400 "invalid session" errors
   - Should automatically re-establish session instead of requiring restart

● Confirmed! Looking at the ha-mcp source code:

In _run_http_with_graceful_shutdown():

server_task = asyncio.create_task(
_get_mcp().run_async(
transport=transport,
host=host,
port=port,
path=path,
show_banner=show_banner,
)
)

No event_store parameter is passed. Compare to what FastMCP docs recommend:

Recommended for session persistence:

event_store = EventStore()
app = mcp.http_app(
event_store=event_store,
retry_interval=2000,
)

This confirms:

1. ✅ ha-mcp does NOT configure EventStore
2. ✅ Sessions exist only in server memory
3. ✅ Any session loss (network blip, timeout, internal error) = permanent until client restart

The bug is clear: ha-mcp should add EventStore for session persistence. This would allow:

• Sessions to survive brief disconnections
• Clients to reconnect without full restart
• Better resilience overall

[lucianconstantin]

OK, I think Claude Code managed to find the root cause. Let me know if I should open another bug report. The issue is caused because I'm running HassOS via Proxmox in a KVM VM on a quite old CPU.

Bug Report: ha_search_entities crashes with SIGILL on CPUs without AVX/SSE4 support

Bug Summary

ha_search_entities tool crashes with SIGILL (illegal instruction) on systems with older CPUs or VMs that lack AVX/SSE4 instruction support.

What happened

When calling ha_search_entities, the MCP server crashes and restarts. The tool hangs for several minutes before the connection breaks with error:
MCP error -32001: AbortError: The operation was aborted. <-- user aborts it because it hangs for very long

After the crash, subsequent MCP calls fail with:
Streamable HTTP error: Error POSTing to endpoint: Bad Request: No valid session ID provided

What I expected

The search should complete successfully or fail gracefully with an error message.

Root Cause Analysis

After extensive debugging, we traced the crash to NumPy 2.4.0 which is imported by textdistance during fuzzy search:

ha_search_entities
→ smart_entity_search
→ textdistance.Levenshtein
→ textdistance.algorithms.edit_based
→ import numpy
→ numpy._core.multiarray (SIGILL crash)

Direct reproduction inside container:
docker exec -it <ha_mcp_container> python3 -c "import numpy"

Exit code 132 (SIGILL), "timeout: the monitored command dumped core"

The NumPy wheel in the addon is compiled with AVX/SSE4 SIMD instructions. CPUs without these instructions crash with SIGILL.

Environment (auto-populated)

• ha-mcp Version: 6.0.0
• Installation Method: addon (slug: 81f33d0f_ha_mcp)
• Platform: Linux 6.12.51-haos (x86_64)
• Python Version: 3.13.11
• Home Assistant Version: 2026.1.0
• NumPy Version: 2.4.0
• textdistance Version: 4.6.3
• Entity Count: 968

CPU Information

model name: Common KVM processor
flags: fpu vme de pse tsc msr pae mce cx8 apic sep mtrr pge mca cmov pat pse36 clflush mmx fxsr sse sse2 ht syscall nx lm constant_tsc nopl xtopology cpuid tsc_known_freq pni cx16 x2apic hypervisor lahf_lm cpuid_fault pti

Note: CPU only supports SSE/SSE2, missing: sse4_1, sse4_2, avx, avx2

Steps to reproduce

1. Run Home Assistant on a VM or system with CPU lacking AVX/SSE4 support
2. Install ha-mcp addon v6.0.0
3. Call ha_search_entities with any query
4. Observe crash and server restart

Suggested fixes

1. Use numpy wheel built for baseline x86_64 (no AVX/SSE4 requirement)
   - PyPI provides numpy wheels with different optimization levels
   - Or build from source with NPY_DISABLE_SVML=1 and baseline SIMD
2. Make textdistance/numpy optional for fuzzy search
   - Fall back to pure-Python Levenshtein or rapidfuzz (which works fine)
   - rapidfuzz was tested and works on this CPU
3. Catch SIGILL at process level and provide graceful degradation

Workaround

Users can configure their hypervisor to expose a CPU with SSE4/AVX support (e.g., host-passthrough or a modern CPU model in KVM/QEMU).

Additional context

• Other tools (ha_get_system_version, ha_get_state, etc.) work perfectly
• Individual libraries (rapidfuzz, jellyfish, pyxDamerauLevenshtein) work fine when imported directly
• Only numpy import crashes
• The crash was traced using python3 -v verbose import logging

[julienld]

I will implement a try/catch with a fallback to an other library (we already doing this for Windows on ARM processor). Should be on the dev version of the add-on tonight or tomorrow.

[julienld]

Update: Root Cause Identified

My earlier investigation was incorrect. The actual issue is not related to MCP session management.

Real Root Cause: NumPy 2.4.0 crashes with SIGILL on CPUs without AVX/SSE4 support (found by @lucianconstantin).

When ha_search_entities imports textdistance → numpy, the process crashes with illegal instruction on older CPUs or VMs. This causes the server to restart and invalidate the session.

Fix in progress: @julienld will implement fallback logic (similar to existing Windows ARM handling) to avoid NumPy on incompatible CPUs.

Removing my earlier upstream references as they were based on incorrect analysis. This is a ha-mcp-specific CPU compatibility issue.