[Bug]: Failed to connect to MCP server (tools.mcp_tool)

[chdlc]

Bug Description

Hermes can't connect to MCP servers that use the "npx" command. Two different error scenarios below reported in the log. Ran hermes doctor --fix after updating to latest version, tried using timeout and connect_timeout, but still happening.

Scenario 1: npx command

MCPs:

  filesystem:
    command: "npx"
    args: ["-y", "@modelcontextprotocol/server-filesystem", "/mnt/c/Users/chris"]
  sequentialthinking:
    command: "/home/chris/.local/bin/npx"
    args: ["-y", "@modelcontextprotocol/server-sequential-thinking"]

Logs

2026-03-07 18:59:54,289 WARNING tools.mcp_tool: Failed to connect to MCP server 'filesystem': [Errno 2] No such file or directory: 'npx'
2026-03-07 18:59:54,290 WARNING tools.mcp_tool: Failed to connect to MCP server 'sequentialthinking': [Errno 2] No such file or directory: 'npx'

Scenario 2: full path to npx

MCPs

  filesystem:
    command: "/home/chris/.local/bin/npx"
    args: ["-y", "@modelcontextprotocol/server-filesystem", "/mnt/c/Users/chris"]
  sequentialthinking:
    command: "/home/chris/.local/bin/npx"
    args: ["-y", "@modelcontextprotocol/server-sequential-thinking"]

Logs

2026-03-11 09:07:43,434 WARNING tools.mcp_tool: Failed to connect to MCP server 'filesystem': unhandled errors in a TaskGroup (1 sub-exception)
2026-03-11 09:07:43,434 WARNING tools.mcp_tool: Failed to connect to MCP server 'sequentialthinking': unhandled errors in a TaskGroup (1 sub-exception)

Steps to Reproduce

1. Start chat with Hermes
2. It detects MCPs in config
3. Fails to connect to MCPs, doesn't detect tools

Expected Behavior

Hermes can make use of the following MCPs properly, so the expectation is that npx servers can be detected and registered too.

  exa:
    url: https://mcp.exa.ai/mcp?tools=web_search_exa,get_code_context_exa
    headers: {}
    timeout: 180
    connect_timeout: 60
  scrapling:
    command: /home/chris/.venvs/scrapling/bin/scrapling
    args:
    - mcp
    env: {}
    timeout: 180
    connect_timeout: 60

Actual Behavior

Hermes fails to connect to MCPs and doesn't register their tools.

Affected Component

Tools (terminal, file ops, web, code execution, etc.)

Messaging Platform (if gateway-related)

No response

Operating System

Ubuntu 24.04 WSL2

Python Version

3.11.15

Hermes Version

1.0.0

Relevant Logs / Traceback

Root Cause Analysis (optional)

No response

Proposed Fix (optional)

No response

Are you willing to submit a PR for this?

• I'd like to fix this myself and submit a PR

[chdlc]

I pulled the latest commits with hermes update and it updated my MCP config as follows, and looks like MCPs are working.

  filesystem:
    command: "/home/chris/.hermes/node/bin/npx"
    args: ["-y", "@modelcontextprotocol/server-filesystem", "/tmp"]
    env:
      PATH: "/home/chris/.hermes/node/bin:/usr/local/bin:/usr/bin:/bin:/sbin:/usr/sbin"
  sequentialthinking:
    command: "/home/chris/.hermes/node/bin/npx"
    args: ["-y", "@modelcontextprotocol/server-sequential-thinking"]
    env:
      PATH: "/home/chris/.hermes/node/bin:/usr/local/bin:/usr/bin:/bin:/sbin:/usr/sbin"

[kshitijk4poor]

Submitted fix in #977. This updates MCP stdio command resolution for npx/npm/node and improves nested TaskGroup error reporting so missing executables are surfaced with actionable diagnostics.