Tutorial Overview

Series index: Hermes Agent Tutorial Series

When You Need This: Read this article if you want to extend Hermes with custom tools, connect external APIs, or integrate specialized capabilities like database access, web scraping, or file system operations.

This tutorial covers Hermes Agent’s MCP Integration — extending capabilities via Model Context Protocol.

What you will learn

• ✅ What MCP is and why it matters
• ✅ Hermes MCP support architecture
• ✅ Adding MCP servers to Hermes
• ✅ Popular MCP integrations
• ✅ Custom MCP development basics

What is MCP?

Model Context Protocol

MCP (Model Context Protocol) is an open standard for connecting AI models to external tools and data sources. It provides:

• Standardized interface — Same API for all tools
• Discovery mechanism — Models find available tools
• Security boundaries — Controlled access to resources

flowchart TD
    A[AI Model] --> B[MCP Client]
    B --> C[MCP Server 1: Database]
    B --> D[MCP Server 2: Files]
    B --> E[MCP Server 3: Web]
    B --> F[MCP Server N: Custom]

    C --> G[Tools: query, insert]
    D --> H[Tools: read, write]
    E --> I[Tools: fetch, search]
    F --> J[Tools: custom]

    style B fill:#e1f5ff
    style G fill:#fff3e0

Why MCP matters

Without MCP, each tool requires custom integration. With MCP:

Hermes MCP Support

Architecture

Hermes embeds an MCP client that discovers and connects to configured servers:

flowchart LR
    A[Hermes Agent] --> B[MCP Client]
    B --> C[Server Registry]
    C --> D[SQLite MCP]
    C --> E[Filesystem MCP]
    C --> F[Brave Search MCP]
    C --> G[Custom MCP]

    D --> H[Tool calls]
    E --> H
    F --> H
    G --> H

    H --> A

    style B fill:#e1f5ff

Configuration location

MCP servers are configured in:

~/.hermes/mcp/
├── config.json          # Server registry
├── servers/             # Installed server binaries
└── logs/                # MCP communication logs

Adding MCP Servers

Configuration format

Add servers to ~/.hermes/mcp/config.json:

{
  "servers": {
    "sqlite": {
      "command": "mcp-server-sqlite",
      "args": ["--db-path", "/data/mydb.sqlite"],
      "env": {}
    },
    "filesystem": {
      "command": "mcp-server-filesystem",
      "args": ["--root", "/workspace"],
      "env": {}
    },
    "brave-search": {
      "command": "mcp-server-brave-search",
      "args": [],
      "env": {
        "BRAVE_API_KEY": "${BRAVE_API_KEY}"
      }
    }
  }
}

CLI configuration

# Add MCP server
hermes mcp add sqlite --command "mcp-server-sqlite" --args "--db-path /data/mydb.sqlite"

# List configured servers
hermes mcp list

# Test server connection
hermes mcp test sqlite

Using MCP tools in Hermes

Once configured, Hermes can invoke MCP tools:

You: Query the database for users created this week

Hermes: Using sqlite MCP...
[Tool: sqlite.query]
SELECT * FROM users WHERE created_at > '2026-04-06';
Result: 15 users found

Hermes: Found 15 users created this week...

Popular MCP Integrations

File System MCP

Access files with security boundaries:

hermes mcp add filesystem --command "mcp-server-filesystem" --args "--root ~/workspace"

Tools provided:

• read_file — Read file contents
• write_file — Create/modify files
• list_directory — List files
• search_files — Find by pattern

SQLite MCP

Query SQLite databases:

hermes mcp add sqlite --command "mcp-server-sqlite" --args "--db-path /data/analytics.sqlite"

Tools provided:

• query — Execute SQL queries
• list_tables — Show table schema
• describe_table — Column details

Brave Search MCP

Web search via Brave API:

hermes mcp add brave-search --command "mcp-server-brave-search" --env BRAVE_API_KEY=YOUR_KEY

Tools provided:

• search — Web search
• search_news — News search

GitHub MCP

GitHub repository operations:

hermes mcp add github --command "mcp-server-github" --env GITHUB_TOKEN=YOUR_TOKEN

Tools provided:

• search_repositories
• get_file_contents
• create_issue
• list_commits

Slack MCP

Slack workspace integration:

hermes mcp add slack --command "mcp-server-slack" --env SLACK_BOT_TOKEN=YOUR_TOKEN

Tools provided:

• send_message
• list_channels
• get_channel_history

MCP server catalog

Browse available servers:

hermes mcp catalog

Output:

Server               Category      Tools
─────────────────────────────────────────────────
filesystem           Files         4
sqlite               Database      3
postgres             Database      5
brave-search         Web           2
github               Development   8
slack                Communication 4
google-drive         Files         6
puppeteer            Browser       5
fetch                HTTP          3

Custom MCP Development

MCP server basics

MCP servers implement:

1. Discovery — List available tools
2. Execution — Handle tool calls
3. Schema — Define input/output types

Minimal MCP server (Python)

from mcp.server import Server
from mcp.types import Tool, ToolResult

server = Server("my-custom-mcp")

@server.list_tools()
async def list_tools():
    return [
        Tool(
            name="hello",
            description="Say hello",
            inputSchema={
                "type": "object",
                "properties": {
                    "name": {"type": "string"}
                },
                "required": ["name"]
            }
        )
    ]

@server.call_tool()
async def call_tool(name: str, arguments: dict):
    if name == "hello":
        return ToolResult(
            content=f"Hello, {arguments['name']}!"
        )

server.run()

Deploy custom MCP

# Install dependencies
pip install mcp

# Run server
python my_mcp_server.py

# Configure Hermes
hermes mcp add my-custom --command "python my_mcp_server.py"

MCP server best practices

1. Clear tool names — Use verb_noun format
2. Explicit schemas — Define all parameters
3. Error handling — Return meaningful errors
4. Security checks — Validate inputs before execution

Security Considerations

Tool permissions

Configure which tools Hermes can use:

mcp:
  permissions:
    filesystem:
      read_file: allow
      write_file: approval_required
    sqlite:
      query: allow
      insert: deny

Approval workflow

For approval_required tools:

sequenceDiagram
    participant U as User
    participant H as Hermes
    participant M as MCP Server

    H->>U: Tool needs approval: write_file
    U->>H: Approve
    H->>M: Execute write_file
    M->>H: Result
    H->>U: Done

    style U fill:#fff3e0

Troubleshooting

MCP server not found

Cause: Server binary not installed.

Fix:

# Install server
pip install mcp-server-sqlite

# Or npm install
npm install @anthropic-ai/mcp-server-filesystem

Tool call failing

Cause: Schema mismatch or permission denied.

Fix:

hermes mcp test SERVER_NAME
hermes mcp logs SERVER_NAME

Environment variable not set

Cause: MCP server needs API key.

Fix:

hermes mcp edit brave-search --env BRAVE_API_KEY=YOUR_KEY

Summary

MCP Integration provides extensibility:

1. Standard protocol — Same interface for all tools
2. Easy configuration — JSON config or CLI commands
3. Popular servers — Filesystem, database, web, GitHub
4. Custom development — Build your own MCP servers
5. Security controls — Permissions and approval

Key takeaways

• ✅ MCP is an open standard for tool integration
• ✅ Hermes embeds MCP client for discovery
• ✅ Popular servers cover common use cases
• ✅ Custom servers extend Hermes further
• ✅ Security controls protect sensitive operations

Series navigation:

• ← Previous: Tutorial 8: Cron Scheduling — Automation
• Back: Series Index

Graduation Milestone G3: After completing this tutorial (the final one), you’ve achieved Master level — full system integration with MCP extensions, custom skills, multi-platform deployment, and serverless backends. Your Hermes Agent is now a complete, extensible AI assistant platform.