Repository navigation
MCP tools discovered but not exposed to agent in TUI mode #41625
Description
Bug Description
MCP server tools are successfully discovered by hermes mcp test (3 tools found), but they do not appear in the agent's available tool list during a TUI session. The agent cannot call MCP tools even though the server is connected and tools are registered.
Steps to Reproduce
- Configure an MCP server in
~/.hermes/config.yamlwith HTTP transport (url-based) - Start the MCP server (confirm the port is listening)
- Run
hermes mcp test <name>→ succeeds, discovers tools - Start a TUI session (
hermes) - The agent does not see or cannot call MCP tools
Expected Behavior
MCP tools should be available as first-class tools in the agent session after successful discovery.
Investigation
Looking at the source code, I suspect a race condition in the TUI startup path:
hermes_cli/main.py:_prepare_agent_startup()skips inline MCP discovery for TUI launches (_is_tui_chat_launchreturns True →_run_inline_mcp_discovery = False)- The comment says: "The TUI launcher hands off to a dedicated startup path that already backgrounds MCP discovery with a bounded join before the first tool snapshot."
- In
hermes_cli/mcp_startup.py,wait_for_mcp_discovery()has a timeout of only 0.75 seconds - If the MCP server takes longer than 0.75s to connect and enumerate tools, the tool snapshot is taken before MCP tools are registered
hermes mcp testworks because it runs synchronously with its own timeout
The 0.75s timeout in wait_for_mcp_discovery() is likely too short for HTTP-based MCP servers, especially on first connection.
Environment
- OS: Windows 10
- Hermes Agent: latest (via
hermes update) - MCP server: HTTP transport (url-based config)
- Shell: git-bash / MSYS
Possible Fix
Either increase wait_for_mcp_discovery() timeout (e.g. to 5-10s), or add a mechanism to inject MCP tools into an already-running agent session after late discovery completes (similar to what /reload-mcp does).
Activity
liuhao1024 commentedon Jun 8, 2026
This is fixed by #41630 — increases wait_for_mcp_discovery timeout from 0.75s to 3.0s so MCP tools register before the first tool snapshot.
dsgvo-dev commentedon Jun 8, 2026
I updated to upstream 4219a91 and also verified/patched the TUI discovery timeout manually.
Before patch:
~/.hermes/hermes-agent/tui_gateway/entry.py:
def wait_for_mcp_discovery(timeout: float = 0.75) -> None:
After local patch:
def wait_for_mcp_discovery(timeout: float = 3.0) -> None:
Gateway was restarted. However, the issue persists.
One-shot still fails as well:
hermes -t "hermes-cli,dsms-knowledge" -z "Du darfst kein Terminal, kein Python, kein Execute Code, kein Write File und kein Read File verwenden. Rufe ausschließlich das MCP-Tool search_knowledge des Servers dsms-knowledge auf mit query='Volkszählungsurteil', collection='urteile', n_results=5. Wenn nicht verfügbar, antworte exakt MCP_TOOL_NOT_AVAILABLE."
Actual result:
MCP_TOOL_NOT_AVAILABLE
So increasing the TUI wait_for_mcp_discovery timeout is not sufficient in this setup.
Environment:
dsgvo-dev commentedon Jun 9, 2026
Confirming this bug on macOS with two findings that broaden the scope beyond TUI: the same failure mode occurs in the headless
-zpath, and a--toolsetsoverride using the documentedmcp-<server>dynamic name is rejected by the resolver as unknown.Environment
hermes update(as of 2026-06-09)uvx, with a non-trivial cold start (~1 s measured viahermes mcp test)MCP server is fully healthy
hermes mcp listshows the server as✓ enabled, all tools.hermes mcp test <server>connects in ~1 s and reports✓ Tools discovered: <N>./tools listlists the server underMCP servers: <server> all tools enabled.So discovery and registration succeed at every layer except the model's function-call schema.
Finding 1:
-z(headless) is affected, not just--tuiWhen the agent is run with
hermes -zand prompted to call an MCP tool — with explicit instructions that bypass mechanisms (Terminal,Python,execute_code,write_file,read_file) are forbidden, and that the agent must reply with a specific sentinel if the tool is missing from its schema — the agent reports the sentinel. The MCP tool name (mcp_<server>_<tool>) is not in the agent's tool list.This rules out the TUI-only race-condition hypothesis (
wait_for_mcp_discovery()with 0.75 s timeout in the TUI startup path) as a complete explanation: the-zpath should run discovery synchronously before snapshotting tools, yet it produces the same outcome. Either the same race exists there, or a separate injection path drops MCP tools regardless of timing.Finding 2:
mcp-<server>toolset name is rejected as unknown by-tWhen invoking with
hermes -t "hermes-cli,mcp-<server>" -z "...", Hermes emits:…and falls back to
hermes-cli. This contradicts the Toolsets Reference and the MCP guide:The warning means the dynamic toolset is either not registered under that name by the time
-tis parsed, or never registered at all. Either way, this is a documentation/implementation mismatch that every operator following the docs will hit.Suggested broader scope
In addition to the TUI startup-path fix already proposed in this issue:
-z) path: either block schema construction until MCP discovery completes, or rebuild the schema after late discovery.mcp-<server>toolsets synchronously at config-load time (before-tis validated), or acceptmcp-<server>lazily without warning when the server entry exists inmcp_servers.hermes -z -t "hermes-cli,mcp-<server>" "..."with a stdio MCP server whose cold start exceeds 750 ms, asserting that the MCP tools appear in the agent's tool schema.Direct invocation of the MCP server process (outside Hermes) succeeds with the same query that fails inside Hermes, so the bug is strictly on the Hermes side between MCP registration and model tool-schema injection.
dwest-mmc commentedon Jun 12, 2026
Corroborating from the stdio side: hermes-agent v0.16.0, macOS, local stdio server — cold spawn + handshake exceeded 0.75 s during bring-up (first discoveries in the 1–3 s range). Two notes:
wait_for_mcp_discovery()is ajoin(timeout), so raising the bound adds no fixed latency — it returns as soon as discovery completes. We run 12 s with no perceptible startup cost.Xande-p commentedon Jun 19, 2026
I would say the severity of this bug is greater then P2 (medium). I have exactly one MCP server (deapi) and had given up on tui because of this bug. The docs say the TUI is the main client, so maybe this bug report should be bumped.
My workaround is, in tui_gateway/entry.py, remove the background Thread target structure _discover_mcp_background and replace it with a direct call to discover_mcp_tools() at startup. A second slower, but works.
fix(mcp): increase mcp_discovery_timeout default to 5.0s