HERMES AGENT MANUAL

Model Context Protocol (MCP) Integration

Connect, configure, and sandbox external tool servers with Hermes Agent using stdio and SSE transports.

What MCP Does in Hermes

The Model Context Protocol (MCP) provides a standardized JSON-RPC interface for connecting external tools, databases, APIs, and file systems directly to Hermes Agent. Instead of modifying core agent code, you expose capabilities as independent MCP servers that Hermes discovers, interrogates, and executes dynamically.

In Hermes Agent (v0.21+), MCP support is built into the core runtime. Servers can run as local subprocesses communicating over stdio, or as remote HTTP endpoints using Server-Sent Events (SSE).

Managing MCP via the CLI

The hermes mcp command group provides full lifecycle management for MCP servers without manual YAML editing:

terminal

# List all configured MCP servers and their current status
$ hermes mcp list

# Test connection and verify tool schemas for a specific server
$ hermes mcp test stripe

# Add a new stdio-based MCP server
$ hermes mcp add cloudflare npx -y @cloudflare/mcp-server-cloudflare

# Browse approved community MCP servers
$ hermes mcp catalog

# Install a pre-configured catalog server
$ hermes mcp install sqlite

[PRO TIP]

Running hermes mcp with no arguments opens the interactive catalog picker, allowing you to browse, install, and configure Nous-approved tool servers with keyboard navigation.

Declarative Configuration (config.yaml)

MCP servers can also be configured declaratively in ~/.hermes/config.yaml under the mcp_servers key. This is the recommended approach for team environments and automated deployments:

~/.hermes/config.yaml

mcp_servers:
  stripe:
    command: "uvx"
    args: ["mcp-server-stripe"]
    enabled: true
    env:
      STRIPE_SECRET_KEY: "${STRIPE_API_KEY}"
  cloudflare:
    command: "npx"
    args: ["-y", "@cloudflare/mcp-server-cloudflare"]
    enabled: true
    env:
      CLOUDFLARE_API_TOKEN: "${CF_TOKEN}"
  nexus:
    command: "nexusos"
    args: ["mcp"]
    enabled: true
    tools:
      include:
        - "search_notes"
        - "read_concept"
        - "query_knowledge"

Restricting Tool Surface Area

Exposing dozens of tools to a model clutters context and increases the probability of hallucinated tool calls. Hermes allows fine-grained tool filtering on each server using include or exclude rules:

~/.hermes/config.yaml

mcp_servers:
  github:
    command: "npx"
    args: ["-y", "@modelcontextprotocol/server-github"]
    enabled: true
    tools:
      # Only allow read operations; prevent destructive repository mutations
      include:
        - "get_file_contents"
        - "search_repositories"
        - "list_issues"

You can also toggle individual tools interactively at any time using hermes mcp configure <server-name>.

Field Receipts & Common Failure Modes

1. Stdio Pipe Closes Prematurely (Subprocess Crash)

Symptom: hermes mcp test <name> reports Connection closed unexpectedly.

Root Cause: MCP requires pure JSON-RPC over stdout. If the underlying server package (or a wrapper script) emits informational logs, version banners, or debug statements to stdout instead of stderr, the JSON parser fails and terminates the transport pipe.

Remediation: Ensure server logging writes to stderr, or pass quiet flags (e.g. uvx --quiet ... or npx --silent ...).

2. PATH Resolution Under Systemd or Cron Daemons

Symptom: Server runs manually in terminal, but fails with FileNotFoundError: [Errno 2] No such file or directory: 'npx' when Hermes runs as a background service.

Remediation: Background daemons often execute with a minimal PATH (e.g. /usr/bin:/bin). Specify absolute binary paths in config.yaml (e.g. /home/user/.nvm/versions/node/v20/bin/npx or /home/user/.local/bin/uvx).

3. Credential Exposure Across Sandbox Boundaries

[SECURITY BOUNDARY]

Never hardcode raw production API secrets in MCP tool schemas or prompt definitions. Environment variables defined in mcp_servers.<name>.env are injected into the subprocess runtime only and are not visible in model conversation context unless the server explicitly echoes them. For sensitive credentials, route requests through Hermes Vault or local secret brokers.

Running Hermes as an MCP Server

Hermes can also operate as a tool server for other applications. Running hermes mcp serve exposes Hermes conversations and execution kernels over MCP, allowing client IDEs (Cursor, Windsurf, Claude Desktop) to invoke Hermes as an external tool runner:

terminal

# Start Hermes in MCP server mode over stdio
$ hermes mcp serve

# Inspect registered capabilities
$ hermes mcp serve --help

Need Hands-On Setup Assistance?

Connecting enterprise databases, private APIs, or multi-agent orchestration layers requires careful credential sandboxing and error recovery. In a 90-minute Hermes Launch Lab pairing session, we configure and verify your custom MCP servers directly on your workstation with verified receipts.