Chapter 3 MCP Integration

MCP (Model Context Protocol) is the standard protocol for AI tool integration. Through MCP, Hermes Agent can connect to hundreds of external tool servers — databases, file systems, API gateways — without writing a single line of code.

What is MCP?

MCP is an open protocol that defines how AI Agents discover and invoke external tools. Think of it like USB-C — one standard interface that works with any device.

┌──────────────┐    MCP Protocol    ┌──────────────┐
│  Hermes Agent │ ◄──────────────► │  MCP Server  │
│  (Client)     │   JSON-RPC       │ (Tool Provider)│
└──────────────┘                   └──────────────┘

Core concepts:

• MCP Server: The server providing tools (e.g., file system, database, API)
• MCP Client: The client that connects to the server and calls tools (Hermes is the Client)
• Transport: Communication method (stdio or HTTP)

---

Two Integration Methods

Hermes provides two ways to integrate MCP:

Method 1: Native MCP (Recommended)

Configure directly in config.yaml — MCP tools are automatically registered as native Hermes tools.

Method 2: mcporter CLI

Temporarily connect to and debug MCP servers through the mcporter skill.

	Native MCP	mcporter
Configuration	config.yaml	Temporary call during conversation
Persistence	✅ Permanent	❌ Current session only
Auto-discovery	✅ Automatic at startup	❌ Manual specification
Best for	Daily use	Debugging, exploration

---

Configuring Native MCP

stdio Transport (Local Commands)

# ~/.hermes/config.yaml
mcp_servers:
  filesystem:
    command: npx
    args: ["-y", "@modelcontextprotocol/server-filesystem", "/path/to/allowed/dir"]
    env:
      NODE_OPTIONS: "--max-old-space-size=4096"

  sqlite:
    command: uvx
    args: ["mcp-server-sqlite", "--db-path", "/path/to/my.db"]

HTTP Transport (Remote Services)

mcp_servers:
  my-api:
    url: https://my-mcp-server.example.com/mcp
    headers:
      Authorization: "Bearer ${MY_API_TOKEN}"

Environment Variable Substitution

Supports ${VAR} syntax for referencing environment variables:

mcp_servers:
  database:
    command: uvx
    args: ["mcp-server-postgres"]
    env:
      DATABASE_URL: "postgresql://${DB_USER}:***@localhost/mydb"

---

Managing MCP Servers

View Configured Servers

hermes mcp list

View Server Tools

hermes mcp tools <server-name>

Debug Connection

hermes mcp inspect <server-name>

Interactive Configuration

hermes mcp setup

---

Common MCP Servers

Server	Installation	Function
filesystem	npx @modelcontextprotocol/server-filesystem	File read/write
sqlite	uvx mcp-server-sqlite	SQLite database
postgres	uvx mcp-server-postgres	PostgreSQL
github	npx @modelcontextprotocol/server-github	GitHub API
brave-search	npx @modelcontextprotocol/server-brave-search	Brave search
puppeteer	npx @modelcontextprotocol/server-puppeteer	Browser automation
slack	npx @modelcontextprotocol/server-slack	Slack API

TIP

The MCP ecosystem is growing rapidly. Check the MCP Server directory for a complete list.

---

Security Mechanisms

Tool Filtering

Hermes automatically filters dangerous operations from MCP tools:

mcp_servers:
  my-server:
    command: npx
    args: ["my-mcp-server"]
    # Optional: allow only specific tools
    allowed_tools:
      - read_file
      - search
    # Optional: block specific tools
    blocked_tools:
      - delete_all

Auto-Reconnect

Native MCP supports automatic reconnection. If the MCP Server process crashes, Hermes will automatically restart it.

Sandbox Isolation

MCP Server processes run in an isolated environment and do not directly affect the Hermes main process.

---

Hands-On: Connecting to a SQLite Database

Step 1: Install MCP Server

# Requires uvx (part of the uv tool)
pip install uv

Step 2: Configure

# ~/.hermes/config.yaml
mcp_servers:
  my-db:
    command: uvx
    args: ["mcp-server-sqlite", "--db-path", "~/data/myapp.db"]

Step 3: Test

You: Connect to the my-db database and list all tables
Hermes: [Discovering MCP tools...] [Calling list_tables...]
        There are 3 tables in the database:
        - users
        - orders
        - products

You: Query the latest 10 orders
Hermes: [Calling execute_sql...]
        | id | user | product | amount | date |
        |----|------|---------|--------|------|
        | 1  | Zhang| iPhone  | 6999   | 04-12|
        | ... |

Step 4: Natural Language Queries

Once MCP tools are registered, you can operate the database using natural language:

You: Find me users whose total orders exceed 10000
Hermes: [Auto-generates SQL and executes...]

---

mcporter Skill

The mcporter skill provides interactive MCP management:

You: Use mcporter to list all configured MCP servers
Hermes: [Calling mcporter CLI...]
        2 servers configured:
        1. filesystem (stdio) - 5 tools
        2. my-db (stdio) - 3 tools

Temporarily connect to a new MCP Server:

You: Use mcporter to temporarily connect to npx @my-org/my-mcp-server
Hermes: [Starting temporary MCP Server...] [Discovering tools...]
        Found 4 tools: ...

Further Reading

• MCP Official Specification
• MCP Server Directory
• Hermes MCP Documentation

---