Sókrates Wiki

Model Context Protocol (MCP) in Hermes

3 min read

Model Context Protocol (MCP) in Hermes

Summary

The Model Context Protocol (MCP) is a standardized integration layer that allows the Hermes Agent to connect to external tool ecosystems, databases, and APIs without requiring native tool development for each service. Hermes supports both local stdio-based servers and remote HTTP-based MCP servers, featuring a robust filtering system for security and tool management.

Details

The Model Context Protocol (MCP) is a core capability of the Hermes Agent, enabling it to extend its functionality by consuming tools, resources, and prompts exposed by external servers. This integration allows Hermes to interact with diverse environments such as GitHub, local filesystems, Stripe, and internal documentation servers through a unified interface.

Server Types and Connectivity

Hermes supports two primary methods for connecting to MCP servers:

  1. Stdio Servers: These run as local subprocesses managed by the Hermes Agent. They communicate over standard input/output. Configuration typically involves specifying an executable (e.g., npx for Node.js servers or uvx for Python servers) and arguments.

    • Example: A filesystem server might be configured with command: "npx" and args: ["-y", "@modelcontextprotocol/server-filesystem", "/path/to/project"].
    • Security: Hermes does not pass the full shell environment to stdio servers; it only provides a safe baseline plus explicitly defined variables in the env mapping to prevent secret leakage.

  2. HTTP Servers: These are remote endpoints that Hermes connects to via standard web protocols.

    • Example: An internal API might be accessed via a url and custom headers for authentication (e.g., Authorization: "Bearer ***").

Configuration and Management

MCP settings are defined in the Hermes configuration file, typically located at ~/.hermes/config.yaml under the mcp_servers key.

Key configuration parameters include:

  • enabled: A boolean flag to skip server connection attempts entirely.
  • timeout / connect_timeout: Durations for tool execution and initial handshakes.
  • tools: A nested mapping for fine-grained control over exposed functionality.

Changes to the configuration can be applied at runtime using the /reload-mcp command within a Hermes session, which triggers a re-discovery and registration of available tools.

Tool Filtering and Security

To maintain a clean tool namespace and enforce security boundaries, Hermes provides per-server filtering:

  • Allowlisting (include): Explicitly defines which tools from the MCP server should be registered. This is the recommended approach for sensitive systems like Stripe or internal databases.
  • Blocklisting (exclude): Registers all tools except those specifically named. This is useful for removing destructive actions (e.g., delete_customer) from an otherwise safe toolset.
  • Utility Wrappers: Hermes automatically generates utility tools for servers that support MCP “Resources” (e.g., list_resources, read_resource) and “Prompts” (e.g., list_prompts, get_prompt). These can be toggled off globally or per-server using tools.resources: false or tools.prompts: false.

Common Implementation Patterns

  • Local Project Assistant: Combining a filesystem MCP server (scoped to a specific directory) with a git MCP server to allow Hermes to reason over a codebase.
  • GitHub Triage: Using the @modelcontextprotocol/server-github with a restricted toolset (list_issues, create_issue) to manage repository state without granting full administrative access.
  • Knowledge Access: Connecting to documentation servers that expose internal guides as MCP Resources, allowing the agent to “read” onboarding materials or incident response playbooks.

Graph View

Backlinks