MCP Integration: Connecting External Tools

What MCP Adds That Toolsets Do Not

The toolset catalog from Lesson 2 covers what ships with Hermes. MCP (Model Context Protocol) is how you connect anything else -- a GitHub integration, a Stripe dashboard, a project management tool -- without Hermes needing native, built-in support for it. If something already has an MCP server built for it, you can usually be using it within minutes.

Installing MCP Support

cd ~/.hermes/hermes-agent
uv pip install -e ".[mcp]"

A credential note before you connect anything: unlike the model provider key from Hermes Agent Fundamentals, there is no single MCP credential -- each external server you connect needs whatever that specific service requires, obtained from that service directly. Connecting GitHub means generating a personal access token in GitHub's own settings; connecting Stripe means generating an API key in Stripe's own dashboard. The examples below show where each token goes in config.yaml, but getting the token itself always happens on the third-party service's own site, never inside Hermes. Some MCP servers (like a local filesystem server) need no external credential at all.

Configuring Servers

MCP servers are configured under mcp_servers in config.yaml. There are three connection types, depending on what the server you are connecting to actually supports.

Stdio (a local process Hermes launches):

mcp_servers:
  filesystem:
    command: "npx"
    args: ["-y", "@modelcontextprotocol/server-filesystem", "/tmp"]
    env:
      VARIABLE: "value"

HTTP (a remote server you connect to):

mcp_servers:
  remote_api:
    url: "https://mcp.example.com/mcp"
    headers:
      Authorization: "Bearer ***"

OAuth-authenticated HTTP:

mcp_servers:
  linear:
    url: "https://mcp.linear.app/mcp"
    auth: oauth

The Full Set of Options

Restricting What a Server Can Do

A real-world example: connecting GitHub but limiting it to read-and-create operations, never edit or delete:

mcp_servers:
  github:
    command: "npx"
    args: ["-y", "@modelcontextprotocol/server-github"]
    env:
      GITHUB_PERSONAL_ACCESS_TOKEN: "***"
    tools:
      include: [list_issues, create_issue, update_issue]
      prompts: false

Or the inverse -- allow everything except one dangerous operation:

mcp_servers:
  stripe:
    url: "https://mcp.stripe.com"
    headers:
      Authorization: "Bearer ***"
    tools:
      exclude: [delete_customer]

This matters more than it might seem at first. An MCP server built by someone else may expose far more capability than you actually want your agent to have access to -- tools.include/tools.exclude is how you narrow that down to exactly what you intend to use.

Managing Servers

hermes mcp                          # Interactive picker for catalog entries
hermes mcp catalog                  # Scriptable text list of available MCPs
hermes mcp install <name>           # Install a specific catalog entry
hermes mcp configure <name>         # Refine tool selection after installation
hermes mcp add <name> --preset <preset>  # Add with preset defaults
/reload-mcp                         # Reload MCP servers mid-session

How Tools Get Named

Every tool from an MCP server is registered with a namespace prefix so there is never a naming collision between servers: mcp_<server_name>_<tool_name>. A "github" server exposing a "create-issue" tool becomes mcp_github_create_issue in practice.

Running Hermes as an MCP Server Itself

The relationship can run in the other direction too:

hermes mcp serve

This exposes Hermes itself as an MCP server that other MCP-compatible tools can connect to -- useful if you want some other application to be able to call into Hermes the same way Hermes calls into external servers.

Servers Can Update Themselves Live

MCP servers can notify Hermes of capability changes via notifications/tools/list_changed, and Hermes automatically refreshes its tool list in response -- you do not need to manually reload every time a server you are connected to adds a new tool on its end.

The next lesson covers two more ways to reach Hermes programmatically: running it as an OpenAI-compatible API server, and connecting it directly inside your IDE.