Model Context Protocol (MCP) Integration

Relevant source files

The following files were used as context for generating this wiki page:

• tools/mcp_tool.py
• tools/mcp_oauth.py
• acp_adapter/server.py
• website/i18n/zh-Hans/docusaurus-plugin-content-docs/current/guides/use-mcp-with-hermes.md
• optional-mcps/cloudflare/manifest.yaml
• optional-skills/mcp/fastmcp/SKILL.md

Model Context Protocol (MCP) Integration allows Hermes Agent to connect to external servers that provide tools, resources, and prompts through a clean RPC layer. This integration enables Hermes to operate local or remote systems, such as file systems, GitHub, or internal APIs, without modifying the core agent logic.

Hermes acts as the client that discovers and registers tools from configured MCP servers during startup or reload. The system supports multiple transport methods, including local standard input/output (stdio) and remote HTTP endpoints. Users maintain granular control over exposed functionality through white-listing and black-listing configurations.

Sources: use-mcp-with-hermes.md, cloudflare/manifest.yaml

System Architecture

The MCP integration acts as an adapter layer between the Hermes core and external services. Hermes discovers the capabilities of each server and exposes them to the Large Language Model (LLM) as standard tools.

The diagram shows how Hermes interfaces with both local processes via stdio and remote servers via HTTP to populate its tool registry.
Sources: use-mcp-with-hermes.md, fastmcp/SKILL.md

Communication Transports

Hermes supports two primary transport protocols for MCP servers:

1. Stdio Transport: Launches a local process (e.g., via npx or uvx) and communicates over standard input and output. This is typically used for local project assistants or filesystem access.
2. HTTP Transport: Connects to a remote URL. This is used for managed services like Cloudflare or internal company APIs. Remote servers often require authentication via OAuth or Bearer tokens.

Sources: use-mcp-with-hermes.md, cloudflare/manifest.yaml

Configuration and Tool Management

Users configure MCP servers in the config.yaml file. The configuration defines how Hermes connects to the server and which specific tools are exposed to the agent.

Server Configuration Options

Parameter	Type	Description
command	String	The executable to run for stdio servers (e.g., npx, python).
args	List	Command-line arguments for the server process.
url	String	The endpoint for HTTP-based MCP servers.
env	Object	Environment variables for the server process (e.g., API keys).
tools.include	List	A whitelist of specific tool names to expose.
tools.exclude	List	A blacklist of tool names or glob patterns to hide.
tools.resources	Boolean	Whether to enable Hermes-added resource wrappers (list_resources).
tools.prompts	Boolean	Whether to enable prompt-related tool wrappers.

Sources: use-mcp-with-hermes.md, cloudflare/manifest.yaml

Tool Filtering Logic

Hermes implements a "minimum effective range" philosophy. Servers like Cloudflare may expose thousands of tools, so Hermes uses curated exclude lists by default to prevent context flooding.

• Include: Only tools in this list appear to the agent. This is the recommended default for sensitive systems.
• Exclude: Tools matching these patterns are hidden. Glob patterns like *_radar_* allow blocking entire product families.

Sources: use-mcp-with-hermes.md, cloudflare/manifest.yaml

Authentication Flows

MCP servers handle authentication through various mechanisms managed by the mcp_oauth modules.

OAuth 2.1 Integration

For remote servers like Cloudflare, Hermes supports Native MCP OAuth 2.1. The client handles:

1. Discovery: Identifying Authorization Server (AS) metadata.
2. Registration: Dynamic Client Registration (DCR) at server endpoints.
3. Exchange: PKCE-based token exchange and automated refresh cycles.

Sources: tools/mcp_oauth.py, cloudflare/manifest.yaml

Sequence: Authentication and Tool Discovery

This sequence illustrates the process from initial connection to tool registration using OAuth.
Sources: tools/mcp_oauth.py, cloudflare/manifest.yaml

Development with FastMCP

The FastMCP framework allows developers to build new MCP servers in Python. It provides decorators to define tools, resources, and prompts.

Key Components of FastMCP

• Tools (@mcp.tool): Verb-based functions that perform actions. They must have typed parameters and docstrings for LLM discovery.
• Resources (@mcp.resource): Stable, read-only content such as database schemas or documentation.
• Prompts (@mcp.prompt): Reusable LLM instruction templates for specific workflows.

Sources: optional-skills/mcp/fastmcp/SKILL.md

Example: API Wrapper Structure

from fastmcp import FastMCP
import httpx

mcp = FastMCP("Weather API")

@mcp.tool()
async def get_forecast(city: str) -> str:
    """Fetch current weather for a city."""
    async with httpx.AsyncClient() as client:
        response = await client.get(f"https://api.weather.com/{city}")
        return response.text

Sources: optional-skills/mcp/fastmcp/SKILL.md:120-135

Operational Commands

Hermes provides slash commands to manage the MCP state during a session:

• /reload-mcp: Re-probes all configured servers and updates the tool registry. This is required after changing include/exclude lists in the configuration.
• /browser connect: While primarily for the core browser, it interacts with MCP bridges (like chrome-devtools-mcp) when Hermes runs in environments like WSL2 to bridge to host browsers.

Sources: use-mcp-with-hermes.md

Summary

MCP Integration provides a scalable extension mechanism for Hermes Agent. By separating the agent logic from tool implementation, Hermes can interface with vast ecosystems like Cloudflare or local filesystems through a standardized protocol. The integration emphasizes security through strict tool filtering and robust authentication management, ensuring that agents only access the specific capabilities required for their tasks.