hermes - 💡(How to fix) Fix MCP server misconfiguration is invisible — missing SDK / connection failures logged at DEBUG, never reach gateway.log

Bug Description

Configuring MCP servers in ~/.hermes/config.yaml under mcp_servers is a silent-no-op when the mcp Python package is not installed, or when a server fails to connect. The only indication exists at DEBUG log level, which is never written to any log file by default.

Reproduced with CodeGraph MCP server being configured for weeks with zero tools appearing — no error, no warning, just nothing.

Steps to Reproduce

1. Add an MCP server to ~/.hermes/config.yaml:

mcp_servers:
  codegraph:
    command: codegraph
    args: [serve, --mcp]
    enabled: true

1. Ensure mcp Python package is NOT installed (pip list | grep mcp → empty)

2. Start the gateway (or any Hermes session)

3. Observe: no MCP tools registered, no error message shown to user, nothing in ~/.hermes/logs/gateway.log or agent.log

Root Cause

tools/mcp_tool.py has three silent-fail paths that all use logger.debug():

1. Line 2915 — logger.debug("MCP SDK not available — skipping MCP tool discovery") — fires when _MCP_AVAILABLE is False
2. Line 2838 — logger.debug("MCP SDK not available — skipping explicit MCP registration") — same check in the explicit registration path
3. Line 2920 — logger.debug("No MCP servers configured") — fires when config section is empty

All three are at debug level. Gateway log defaults to INFO+. Agent.log defaults to INFO+. So these messages are never surfaced to any user-visible log.

Even when the mcp package IS installed, if a server connection fails (bad command, missing binary, timeout), the error at line 2945 only logs a count summary at INFO level — no server name, no reason, no actionable detail.

Impact

• Users configure MCP servers, restart, see no tools, cannot diagnose why
• This affects all MCP server types (stdio and HTTP)
• The CodeGraph MCP server specifically was configured and enabled for weeks without working, and the only way to detect it was manually checking _MCP_AVAILABLE
• First-time MCP users hit this immediately with zero feedback

Suggested Fix

1. Line 2915: Upgrade to logger.warning("MCP SDK not installed — install with: pip install mcp") so it shows in default log output
2. Line 2920: Keep as logger.debug (no servers configured is a valid state)
3. Line 2944-2945: Add per-server failure detail at logger.warning level — include the server name and error
4. Line 2838: Upgrade to logger.warning

Additionally: when the agent starts with mcp_servers configured but no MCP tools register, consider showing a one-time warning in the console or gateway startup banner.

Environment

• Hermes: current main (tested against latest)
• OS: Linux
• mcp package: absent by default (optional dependency)
• Observed: May 2026