Built-in MCP (Model Context Protocol) client that connects to external MCP servers, discovers their tools, and registers them as native Hermes Agent tools. Supports stdio and HTTP transports with automatic reconnection, security filtering, and zero-config tool injection.
Built-in MCP (Model Context Protocol) client that connects to external MCP servers, discovers their tools, and registers them as native Hermes Agent tools. Supports stdio and HTTP transports with automatic reconnection, security filtering, and zero-config tool injection.
Hermes Agent has a built-in MCP client that connects to MCP servers at startup, discovers their tools, and makes them available as first-class tools the agent can call directly. No bridge CLI needed -- tools from MCP servers appear alongside built-in tools like terminal, read_file, etc.
When to Use
Use this whenever you want to:
Connect to MCP servers and use their tools from within Hermes Agent
Add external capabilities (filesystem access, GitHub, databases, APIs) via MCP
Run local stdio-based MCP servers (npx, uvx, or any command)
Connect to remote HTTP/StreamableHTTP MCP servers
Have MCP tools auto-discovered and available in every conversation
For ad-hoc, one-off MCP tool calls from the terminal without configuring anything, see the mcporter skill instead.
Prerequisites
mcp Python package -- optional dependency; install with pip install mcp. If not installed, MCP support is silently disabled.
Node.js -- required for npx-based MCP servers (most community servers)
uv -- required for uvx-based MCP servers (Python-based servers)
Install the MCP SDK:
pip install mcp
# or, if using uv:
uv pip install mcp
Quick Start
Add MCP servers to ~/.hermes/config.yaml under the mcp_servers key:
You can then use the tools naturally -- just ask the agent to get the current time.
Configuration Reference
Each entry under mcp_servers is a server name mapped to its config. There are two transport types: stdio (command-based) and HTTP (url-based).
Stdio Transport (command + args)
mcp_servers:server_name:command:"npx"# (required) executable to runargs: ["-y", "pkg-name"] # (optional) command arguments, default: []env:# (optional) environment variables for the subprocessSOME_API_KEY:"value"timeout:120# (optional) per-tool-call timeout in seconds, default: 120connect_timeout:60# (optional) initial connection timeout in seconds, default: 60
HTTP Transport (url)
mcp_servers:server_name:url:"https://my-server.example.com/mcp"# (required) server URLheaders:# (optional) HTTP headersAuthorization:"Bearer sk-..."timeout:180# (optional) per-tool-call timeout in seconds, default: 120connect_timeout:60# (optional) initial connection timeout in seconds, default: 60
All Config Options
Option
Type
Default
Description
command
string
--
Executable to run (stdio transport, required)
args
list
[]
Arguments passed to the command
env
dict
{}
Extra environment variables for the subprocess
url
string
--
Server URL (HTTP transport, required)
headers
dict
{}
HTTP headers sent with every request
timeout
int
120
Per-tool-call timeout in seconds
connect_timeout
int
60
Timeout for initial connection and discovery
Note: A server config must have either command (stdio) or url (HTTP), not both.
How It Works
Startup Discovery
When Hermes Agent starts, discover_mcp_tools() is called during tool initialization:
Reads mcp_servers from ~/.hermes/config.yaml
For each server, spawns a connection in a dedicated background event loop
Initializes the MCP session and calls list_tools() to discover available tools
Registers each tool in the Hermes tool registry
Tool Naming Convention
MCP tools are registered with the naming pattern:
mcp_{server_name}_{tool_name}
Hyphens and dots in names are replaced with underscores for LLM API compatibility.
Examples:
Server filesystem, tool read_file → mcp_filesystem_read_file
Server github, tool list-issues → mcp_github_list_issues
Server my-api, tool fetch.data → mcp_my_api_fetch_data
Auto-Injection
After discovery, MCP tools are automatically injected into all hermes-* platform toolsets (CLI, Discord, Telegram, etc.). This means MCP tools are available in every conversation without any additional configuration.
Connection Lifecycle
Each server runs as a long-lived asyncio Task in a background daemon thread
Connections persist for the lifetime of the agent process
If a connection drops, automatic reconnection with exponential backoff kicks in (up to 5 retries, max 60s backoff)
On agent shutdown, all connections are gracefully closed
Idempotency
discover_mcp_tools() is idempotent -- calling it multiple times only connects to servers that aren't already connected. Failed servers are retried on subsequent calls.
Transport Types
Stdio Transport
The most common transport. Hermes launches the MCP server as a subprocess and communicates over stdin/stdout.
All other environment variables (API keys, tokens, secrets) are excluded unless you explicitly add them via the env config key. This prevents accidental credential leakage to untrusted MCP servers.
mcp_servers:github:command:"npx"args: ["-y", "@modelcontextprotocol/server-github"]
env:# Only this token is passed to the subprocessGITHUB_PERSONAL_ACCESS_TOKEN:"ghp_..."
Credential Stripping in Error Messages
If an MCP tool call fails, any credential-like patterns in the error message are automatically redacted before being shown to the LLM. This covers:
"MCP SDK not available -- skipping MCP tool discovery"
The mcp Python package is not installed. Install it:
pip install mcp
"No MCP servers configured"
No mcp_servers key in ~/.hermes/config.yaml, or it's empty. Add at least one server.
"Failed to connect to MCP server 'X'"
Common causes:
Command not found: The command binary isn't on PATH. Ensure npx, uvx, or the relevant command is installed.
Package not found: For npx servers, the npm package may not exist or may need -y in args to auto-install.
Timeout: The server took too long to start. Increase connect_timeout.
Port conflict: For HTTP servers, the URL may be unreachable.
"MCP server 'X' requires HTTP transport but mcp.client.streamable_http is not available"
Your mcp package version doesn't include HTTP client support. Upgrade:
pip install --upgrade mcp
Tools not appearing
Check that the server is listed under mcp_servers (not mcp or servers)
Ensure the YAML indentation is correct
Look at Hermes Agent startup logs for connection messages
Tool names are prefixed with mcp_{server}_{tool} -- look for that pattern
Connection keeps dropping
The client retries up to 5 times with exponential backoff (1s, 2s, 4s, 8s, 16s, capped at 60s). If the server is fundamentally unreachable, it gives up after 5 attempts. Check the server process and network connectivity.
