[Bug] hindsight-embed local_embedded fails to start: TypeError: FastMCP() no longer accepts 'stateless_http' with fastmcp >= 3.0

[laychiman]

Bug Report: FastMCP Compatibility — hindsight-embed 0.6.2 fails with TypeError on FastMCP(stateless_http=True)

Summary

hindsight-local-embedded mode (hindsight-embed 0.6.2) cannot start the API daemon because it passes stateless_http=True to FastMCP(...) which is removed in fastmcp >= 3.0. Downgrading fastmcp causes cascading dependency breaks.

Environment

• hindsight-embed: 0.6.2
• hindsight-api: 0.3.0 (installed via hindsight-all)
• fastmcp: 3.3.1 (latest)
• python: 3.11
• OS: macOS 15.x, Intel Mac

Steps to Reproduce

pip install hindsight-all        # installs hindsight-api 0.3.0 + hindsight-embed 0.6.2
pip install fastmcp==3.3.1       # latest
export HINDSIGHT_API_MCP_ENABLED=false
cd ~/.hermes/hermes-agent
source venv/bin/activate
python3 -c "from hindsight_embed.daemon_embed_manager import DaemonEmbedManager; DaemonEmbedManager(profile='hermes').ensure_running()"

Expected Behavior

Daemon starts, health check passes on allocated port.

Actual Behavior

Daemon crashes with:

TypeError: FastMCP() no longer accepts 'stateless_http'

(Location: hindsight_api/api/mcp.py line ~53)

Attempted Workarounds

1. HINDSIGHT_API_MCP_ENABLED=false — Still fails because mcp.py is imported at startup before the gate checks
2. fastmcp==2.12.0 — ImportError: PrivateKeyJWTAuthenticator missing
3. fastmcp==2.3.0 — ModuleNotFoundError: fastmcp.mcp_config

Root Cause

• hindsight-api pins fastmcp>=2.3.0 but does NOT cap <3.0
• hindsight_api/api/mcp.py uses stateless_http=True (removed in fastmcp 3.x)
• HINDSIGHT_API_MCP_ENABLED gate does not prevent import-time errors

Suggested Fixes

A. Update mcp.py for fastmcp 3.x API compatibility
B. Hard-pin fastmcp<3.0 in pyproject.toml until migration
C. Move MCP import inside conditional block checking HINDSIGHT_API_MCP_ENABLED

Related

• Issue Claude Code v2.1.84+ can't connect: stateless_http=True rejects GET on /mcp/ #751: Claude Code requires stateless_http configurable (closed)

[benfrank241]

@laychiman thanks for the report but it seems as though you are a few releases behind the current release of hindsight-api. In your report you say you are on 0.3.0. Could you try pip install --upgrade hindsight-api hindsight-embed hindsight-all and see if that resolves your issues?