hermes - 💡(How to fix) Fix [Bug]: TUI/CLI startup banner shows MCP servers as "failed" while async connection is still in progress [1 pull requests]

Bug Description

When starting hermes chat or hermes --tui, HTTP MCP servers (clickup, github, linear — anything using OAuth or Bearer auth over HTTP) show as (http) — failed in the startup banner. The servers actually connect fine within 3–5 seconds, but the banner renders before async MCP initialization completes.

This is a render-timing problem: the banner snapshots MCP connection states while they're still in the "connecting" phase. The servers finish connecting shortly after, but the user's first impression is that their setup is broken.

From agent.log:

WARNING tools.mcp_tool: MCP server 'phpstorm' initial connection failed (attempt 2/3)...
WARNING tools.mcp_tool: MCP server 'phpstorm' failed initial connection after 3 attempts, giving up
INFO  tools.mcp_tool: MCP: registered 260 tool(s) from 6 server(s) (1 failed)

Only phpstorm truly failed (needs PhpStorm IDE running). The other 5 (clickup, github, linear, dart-mcp-server, butterfly, gitlab) connected fine. But the banner showed ALL including clickup as "failed".

Steps to Reproduce

1. Configure any HTTP MCP server with OAuth or Bearer auth (e.g. clickup, github via githubcopilot, linear)
2. Run hermes chat or hermes --tui
3. Observe the startup banner — HTTP MCP servers show as (http) — failed

Wait for the session to fully initialize (3–5s), then check:

hermes mcp list

All servers show as ✓ enabled with tools discovered.

Expected Behavior

The banner should either:

• Show a distinct state like (http) — connecting... or (http) — pending instead of failed for servers that haven't finished async init yet
• Or defer rendering the MCP status section until all servers have resolved (connect or fail)
• Or update the banner dynamically as connections complete

failed should be reserved for cases where startup was attempted and threw/spawn failed.

Actual Behavior

Banner displays clickup (http) — failed for servers that connect successfully moments later. This sends users on a debugging rabbit hole investigating credentials, tokens, and network when there's nothing wrong.

Evidence

$ hermes mcp test clickup
Testing 'clickup'...
  Transport: HTTP → https://mcp.clickup.com/mcp
  Auth: OAuth 2.1 PKCE
  ✓ Connected (3452ms)
  ✓ Tools discovered: 51

$ hermes mcp list
  Name     Transport                    Tools    Status
  clickup  https://mcp.clickup.com/mcp  all      ✓ enabled
  github   https://api.githubcopilot... all      ✓ enabled
  linear   https://mcp.linear.app/mcp   all      ✓ enabled

All servers are healthy. The "failed" banner is a false negative.

Related Issues

• #21663: cli.py invoked directly bypasses discover_mcp_tools() (similar banner symptom, different root cause — that issue is about the discovery call never happening)
• #12130: TUI v2 feature-parity audit (mentions MCP boot status as Tier 1 gap)
• #22724: MCP connectivity check resolves config key as DNS hostname (different issue)

Our case is distinct: the hermes wrapper IS calling discover_mcp_tools() correctly (the servers eventually connect and tools are registered), but the startup banner renders before async HTTP connections resolve.

Suggested Fix

In the MCP status rendering path (likely in cli.py or the startup banner code), distinguish between:

1. failed — spawn was attempted and threw/connection was rejected
2. connecting / pending — async init is still in progress (default initial state)
3. connected — handshake complete, tools discovered

For HTTP MCP servers especially, the async connection can take 3–5 seconds due to TLS + OAuth overhead. The banner should not mark these as failed before they've had a chance to complete.

Alternatively, if the calling code can get a future/promise from the connection attempt, the banner could defer rendering the MCP section until all servers have resolved or a timeout elapses.

Operating System

Linux (Kali 6.18.5)

Hermes Version

v0.15.1 (2026.5.29)

Python Version

3.11.15

Additional Context

Full logs confirming:

2026-06-05 19:55:06,933 INFO tools.mcp_tool: MCP: registered 260 tool(s) from 6 server(s) (1 failed)

Only phpstorm failed. clickup, github, linear, dart-mcp-server, butterfly, gitlab — all 6 connected successfully. But the startup banner shown to the user listed all HTTP servers as "failed".