Hermes Agent Tutorial Part 4: MCP Integration and External Tool Extensions

In Part 1, Part 2, and Part 3 of this series, we explored Hermes Agent’s fundamentals, tool ecosystem, and automated cron workflows. Now we turn to one of the most powerful extensibility mechanisms available: MCP (Model Context Protocol) integration.

MCP is an open protocol that standardizes how AI agents connect to external tools, data sources, and services. Instead of writing custom integrations for every API, database, or filesystem, you simply point Hermes Agent at an MCP server and its tools become available as first-class citizens — callable directly by the agent alongside built-in tools like terminal, read_file, and web_search. In this article, we will cover the MCP concept, how to configure mcp_servers in Hermes Agent, the supported transport types, security considerations, and real-world examples.

What Is MCP and Why It Matters

The Model Context Protocol (MCP), pioneered by Anthropic and now widely adopted, solves a fundamental problem in the AI agent ecosystem: fragmentation. Before MCP, every agent framework invented its own plugin system. Connecting an agent to GitHub, a PostgreSQL database, or a corporate API required bespoke code, custom authentication handling, and ongoing maintenance. MCP replaces this chaos with a single, standardized interface.

An MCP server is a lightweight process that exposes a set of tools through a well-defined JSON-RPC protocol. The server can be a local command-line tool (communicating over stdin/stdout), a remote HTTP service, or even a WebSocket endpoint. The agent discovers the available tools, learns their schemas, and invokes them dynamically during conversations. This means:

  1. Write once, use everywhere — An MCP server built for Claude can work with Hermes Agent, and vice versa. The protocol is vendor-neutral.
  2. No custom code required — You do not write Python scripts to wrap APIs. You configure a server URL or command, and the agent handles the rest.
  3. Dynamic discovery — New tools appear automatically when the MCP server updates. No agent restart is needed for tool schema changes (though server additions do require a restart).
  4. Composability — You can connect multiple MCP servers simultaneously. Your agent might use filesystem tools from one server, GitHub tools from another, and internal API tools from a third — all in the same conversation.

Hermes Agent’s native MCP client implements this protocol directly. It is not a wrapper around another tool; it is a first-class subsystem that connects at startup, discovers tools, and registers them with the agent’s tool registry. This deep integration means MCP tools behave identically to built-in tools: they appear in the system prompt, respect guardrails, support streaming, and can be combined in multi-tool workflows.

Configuring MCP Servers in Hermes Agent

All MCP server configuration lives in ~/.hermes/config.yaml under the mcp_servers key. Hermes Agent reads this section during startup, establishes connections to each configured server, and registers the discovered tools.

Basic Configuration Structure

mcp_servers:
  time:
    command: "uvx"
    args: ["mcp-server-time"]

  filesystem:
    command: "npx"
    args: ["-y", "@modelcontextprotocol/server-filesystem", "/home/user/projects"]

  github:
    command: "npx"
    args: ["-y", "@modelcontextprotocol/server-github"]
    env:
      GITHUB_PERSONAL_ACCESS_TOKEN: "ghp_xx...xxxx"
    timeout: 60

  company_api:
    url: "https://mcp.internal.company.com/mcp"
    headers:
      Authorization: "Bearer sk-xxx...xxxx"
    timeout: 180
    connect_timeout: 30

Each entry under mcp_servers is a server name mapped to its transport configuration. The server name is used as a prefix for tool registration, so choose descriptive, unique names. A configuration must specify either command (for stdio transport) or url (for HTTP transport), but never both.

Configuration Options Reference

OptionTypeDefaultDescription
commandstring—Executable to run for stdio transport
argslist[]Arguments passed to the command
envdict{}Extra environment variables for the subprocess
urlstring—Server URL for HTTP transport
headersdict{}HTTP headers sent with every request
timeoutint120Per-tool-call timeout in seconds
connect_timeoutint60Initial connection and discovery timeout

The timeout and connect_timeout values are particularly important for slow-starting servers or network-bound HTTP endpoints. If a server takes longer than connect_timeout to initialize, Hermes Agent logs a warning and retries with exponential backoff.

Transport Types: Stdio vs HTTP

Hermes Agent supports two transport mechanisms for MCP, each suited to different deployment scenarios.

Stdio Transport

The stdio transport is the most common and simplest to set up. Hermes Agent launches the MCP server as a subprocess and communicates over stdin/stdout using JSON-RPC messages. This is ideal for local tools, npm packages, and Python scripts.

mcp_servers:
  filesystem:
    command: "npx"
    args: ["-y", "@modelcontextprotocol/server-filesystem", "/home/user/documents"]
    timeout: 30

In this example, Hermes Agent runs npx -y @modelcontextprotocol/server-filesystem /home/user/documents as a subprocess. The -y flag auto-installs the package if it is not already cached. The server exposes tools like read_file, write_file, and list_directory scoped to the specified path.

Stdio transport is perfect for:

Because the subprocess inherits a filtered environment (see the Security section below), you must explicitly pass sensitive credentials via the env key.

HTTP / StreamableHTTP Transport

For remote or shared MCP servers, Hermes Agent supports HTTP transport. This is useful when:

mcp_servers:
  remote_analytics:
    url: "https://mcp.analytics.company.com/v1/mcp"
    headers:
      Authorization: "Bearer sk-xxx...xxxx"
      X-Team-Id: "engineering"
    timeout: 180
    connect_timeout: 30

HTTP transport requires the mcp Python package to include HTTP client support (mcp.client.streamable_http). If your installed version lacks this module, Hermes Agent logs an informative error and skips that server while continuing to initialize the others. Upgrade the package to resolve this:

pip install --upgrade mcp

Tool Discovery and Naming Convention

When Hermes Agent connects to an MCP server, it automatically calls list_tools() to discover the available tools and their JSON schemas. These schemas include tool names, descriptions, and parameter definitions — everything the LLM needs to invoke the tools correctly.

Naming Pattern

Discovered tools are registered with the following naming convention:

mcp_{server_name}_{tool_name}

Hyphens and dots in the original names are replaced with underscores for LLM API compatibility. For example:

This prefixing prevents collisions between tools from different servers and makes it immediately clear which server provides a given capability.

Auto-Injection

After discovery, MCP tools are automatically injected into all hermes-* platform toolsets. Whether you are chatting in the CLI, Telegram, Discord, Slack, or Feishu, the MCP tools are available without additional configuration. This global availability is one of the key advantages of Hermes Agent’s native MCP client over ad-hoc bridge scripts.

Security Considerations

Connecting your AI agent to external tools is powerful, but it requires careful attention to security. Hermes Agent implements several safeguards to protect your credentials and limit exposure.

Environment Variable Filtering

For stdio transport, Hermes Agent does not pass your full shell environment to MCP subprocesses. Only a safe baseline set of variables is inherited:

All other environment variables — including API keys, tokens, and 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 subprocess
      GITHUB_PERSONAL_ACCESS_TOKEN: "ghp_..."

Credential Redaction

If an MCP tool call fails, Hermes Agent automatically scans the error message for credential-like patterns and redacts them before passing the error to the LLM. This covers GitHub PATs (ghp_...), OpenAI-style keys (sk-...), Bearer tokens, and generic patterns like token=, key=, API_KEY=, password=, and secret=.

This redaction prevents a subtle but serious attack vector: an untrusted MCP server could deliberately return errors containing your credentials, hoping the LLM would echo them back in its response. Hermes Agent neutralizes this risk at the infrastructure level.

Practical Examples

Let us walk through several real-world MCP server configurations that demonstrate the breadth of what is possible.

Example 1: Time Server (uvx)

The simplest possible MCP server provides time-related utilities. This is useful for agents that need to reason about timezones, schedule tasks, or generate timestamped outputs.

mcp_servers:
  time:
    command: "uvx"
    args: ["mcp-server-time"]

After restarting Hermes Agent, you can ask: “What is the current time in Tokyo?” The agent will call mcp_time_get_current_time with the appropriate timezone parameter.

Example 2: Filesystem Server (npx)

Filesystem access is one of the most common use cases. The official Model Context Protocol filesystem server lets the agent read, write, and search files within a specified directory tree.

mcp_servers:
  filesystem:
    command: "npx"
    args: ["-y", "@modelcontextprotocol/server-filesystem", "/home/user/documents"]
    timeout: 30

This exposes tools like mcp_filesystem_read_file, mcp_filesystem_write_file, and mcp_filesystem_list_directory. The agent can now browse your documents, edit configuration files, or analyze codebases — all through natural language requests.

Important: The path argument (/home/user/documents in this example) acts as a sandbox. The server will refuse to access files outside this directory. Choose the path carefully to balance utility and security.

Example 3: GitHub Server with Authentication

For software development workflows, the GitHub MCP server is invaluable. It can list issues, create pull requests, search repositories, and manage discussions.

mcp_servers:
  github:
    command: "npx"
    args: ["-y", "@modelcontextprotocol/server-github"]
    env:
      GITHUB_PERSONAL_ACCESS_TOKEN: "ghp_xx...xxxx"
    timeout: 60

With this configuration, you can say: “Show me the open issues in the NousResearch/hermes-agent repository labeled ‘bug’” or “Create a pull request from my-feature-branch to main with the title ‘Add dark mode support’”. The agent translates your intent into the appropriate mcp_github_* tool calls.

Example 4: Remote HTTP Server

For organizations with internal APIs, an HTTP-based MCP server provides a clean integration path without requiring every developer to install local dependencies.

mcp_servers:
  company_api:
    url: "https://mcp.mycompany.com/v1/mcp"
    headers:
      Authorization: "Bearer sk-xxx...xxxx"
      X-Team-Id: "engineering"
    timeout: 180
    connect_timeout: 30

This might expose tools for querying customer data, triggering deployments, or retrieving analytics. Because the server is remote, updates to the API surface are immediately available to all connected agents without any client-side changes.

Example 5: Multiple Servers Combined

The true power of MCP emerges when you combine multiple servers. Here is a configuration that simultaneously connects time, filesystem, GitHub, and an internal API:

mcp_servers:
  time:
    command: "uvx"
    args: ["mcp-server-time"]

  filesystem:
    command: "npx"
    args: ["-y", "@modelcontextprotocol/server-filesystem", "/tmp"]

  github:
    command: "npx"
    args: ["-y", "@modelcontextprotocol/server-github"]
    env:
      GITHUB_PERSONAL_ACCESS_TOKEN: "ghp_xx...xxxx"

  company_api:
    url: "https://mcp.internal.company.com/mcp"
    headers:
      Authorization: "Bearer sk-xxx...xxxx"
    timeout: 300

All tools from all servers are registered and available simultaneously. You can ask the agent to: “Read the project roadmap from /tmp/roadmap.md, create a GitHub issue for each milestone, and notify the team via the company API” — and the agent will orchestrate all three MCP servers in a single workflow.

Sampling: Server-Initiated LLM Requests

A powerful advanced feature of MCP is sampling — the ability for an MCP server to request LLM completions through the agent during tool execution. This enables agent-in-the-loop workflows where the server itself needs AI reasoning to complete its task.

For example, a data analysis MCP server might fetch raw data, then ask the LLM to interpret trends and generate a summary. Or a content generation server might request the LLM to draft text based on structured input.

Hermes Agent supports MCP’s sampling/createMessage capability out of the box. Sampling is enabled by default for all MCP servers. You can configure or disable it per server:

mcp_servers:
  my_server:
    command: "npx"
    args: ["-y", "my-mcp-server"]
    sampling:
      enabled: true
      model: "gemini-3-flash"
      max_tokens_cap: 4096
      timeout: 30
      max_rpm: 10
      max_tool_rounds: 5
      log_level: "info"

The max_tool_rounds setting is particularly important: it prevents infinite loops where a sampling request triggers tool calls, which trigger more sampling requests. For untrusted servers, disable sampling entirely:

mcp_servers:
  untrusted_server:
    command: "npx"
    args: ["-y", "some-third-party-server"]
    sampling:
      enabled: false

Per-server audit metrics — including request counts, errors, tokens consumed, and tool use counts — are tracked internally and can be inspected via get_mcp_status().

Connection Lifecycle and Resilience

Hermes Agent’s MCP client is designed for production reliability. Each server connection runs as a long-lived asyncio Task in a dedicated background daemon thread. Connections persist for the lifetime of the agent process.

If a connection drops — due to a network glitch, server restart, or transient error — the client automatically attempts reconnection with exponential backoff. The retry schedule is: 1 second, 2 seconds, 4 seconds, 8 seconds, 16 seconds, capped at 60 seconds. After 5 failed attempts, the client gives up and marks the server as disconnected. Other servers continue operating normally.

On agent shutdown, all MCP connections are gracefully closed, giving servers a chance to clean up resources. This is particularly important for database MCP servers that may hold open connections or transactions.

Note that adding, removing, or significantly reconfiguring MCP servers currently requires restarting Hermes Agent. There is no hot-reload mechanism. However, you can trigger a reload without fully restarting the process by using the /reload-mcp slash command in an active session.

Troubleshooting Common Issues

”MCP SDK not available — skipping MCP tool discovery”

The mcp Python package is not installed. Install it with:

pip install mcp
# or with uv:
uv pip install mcp

“No MCP servers configured”

Your ~/.hermes/config.yaml is missing the mcp_servers key, or it is empty. Add at least one server configuration and restart.

”Failed to connect to MCP server ‘X’”

Common causes and solutions:

”MCP server ‘X’ requires HTTP transport but mcp.client.streamable_http is not available”

Your mcp package version predates HTTP client support. Upgrade:

pip install --upgrade mcp

Tools not appearing in conversations

Connection keeps dropping

Check the server process health and network stability. The client retries up to 5 times with exponential backoff. If the server is fundamentally unreachable (wrong URL, firewall block, process crash), the connection will eventually fail permanently. Fix the underlying issue and restart Hermes Agent.

Best Practices for MCP Integration

1. Start with One Server

When first experimenting with MCP, configure a single simple server like mcp-server-time. Verify that tools appear and work correctly before adding more complex servers. This incremental approach makes troubleshooting much easier.

2. Use Descriptive Server Names

Names like fs, gh, and api are concise but opaque. Prefer filesystem, github, and company_api. Descriptive names make tool listings self-documenting and help the LLM understand which tool to use for a given task.

3. Scope Filesystem Access Tightly

The filesystem MCP server is powerful and potentially dangerous. Always specify the narrowest directory path that satisfies your use case. Never point it at your entire home directory or system root unless you fully understand the risks.

4. Rotate Credentials Regularly

GitHub PATs, API keys, and Bearer tokens should be rotated on a schedule. Because Hermes Agent’s MCP configuration is just YAML, you can manage credentials through your existing secret management infrastructure and update the file atomically.

5. Monitor Sampling Usage

If you enable sampling for MCP servers, keep an eye on token consumption and request rates. Sampling can significantly increase API usage because the LLM may be invoked multiple times per user request. Set max_tokens_cap and max_rpm conservatively.

6. Version Control Your Configuration

Store your config.yaml (with secrets redacted or templated) in version control. This enables code review, rollback, and audit trails for your MCP infrastructure. Treat MCP server configurations as infrastructure-as-code.

7. Test Servers in Isolation

Before adding a new MCP server to your production agent configuration, test it standalone. Most MCP servers can be run directly from the command line, allowing you to verify their behavior independently of Hermes Agent.

Putting It All Together: A Real-World Workflow

Let us conclude with a comprehensive example that demonstrates MCP integration in a realistic development workflow. Suppose you are a team lead who wants to automate weekly sprint reporting. You configure three MCP servers:

mcp_servers:
  github:
    command: "npx"
    args: ["-y", "@modelcontextprotocol/server-github"]
    env:
      GITHUB_PERSONAL_ACCESS_TOKEN: "ghp_xx...xxxx"

  filesystem:
    command: "npx"
    args: ["-y", "@modelcontextprotocol/server-filesystem", "/home/user/reports"]

  company_api:
    url: "https://mcp.internal.company.com/mcp"
    headers:
      Authorization: "Bearer sk-xxx...xxxx"

Now you can ask Hermes Agent:

“Generate this week’s sprint report. Pull all closed issues and merged pull requests from the last 7 days in the backend repo. Write a summary markdown file to /home/user/reports/sprint-week-24.md. Then post a one-paragraph summary to the engineering team via the company API.”

The agent will:

  1. Call mcp_github_list_issues with a date filter to retrieve closed issues
  2. Call mcp_github_list_pull_requests (or equivalent) to find merged PRs
  3. Synthesize the data into a structured report
  4. Call mcp_filesystem_write_file to save the markdown report
  5. Call mcp_company_api_send_message (or equivalent) to notify the team

All of this happens through natural language — no shell scripts, no API wrappers, no manual copy-pasting. The MCP protocol handles the plumbing; the agent handles the reasoning.

Conclusion

MCP integration transforms Hermes Agent from a standalone assistant into a universal interface for your entire toolchain. By configuring mcp_servers in ~/.hermes/config.yaml, you unlock filesystem access, GitHub operations, database queries, internal API calls, and countless other capabilities — all discovered automatically and invoked naturally through conversation.

The key insight is that MCP is not just another plugin system. It is a protocol-level standard that decouples tool providers from agent implementations. As the MCP ecosystem grows, Hermes Agent users benefit automatically. New servers, new capabilities, and new integrations become available without waiting for framework updates or writing custom code.

In the next part of this series, we will explore multi-agent collaboration — how multiple Hermes Agent instances can coordinate, delegate, and solve complex problems that exceed the scope of any single agent.

Stay connected!