MCP — plug in external tools

MCP stands for Model Context Protocol. It's a standard for how AI agents talk to external tool servers. If Hermes is a power drill, MCP is the set of interchangeable bits — you can swap different capabilities in and out without changing the drill itself.

Other agents speak MCP too. Claude Desktop, Cursor, Codex — they all use it. Which means a lot of people have already written MCP servers for things like GitHub, filesystems, databases, Stripe, Slack, and many others. Hermes can use any of them.

What this actually gets you

Without MCP, Hermes only has the tools that ship with it. That's already a lot, but it's finite.

With MCP, Hermes can:

• Read and write to specific folders you allow (via the filesystem server)
• Open, review, and merge GitHub pull requests (via the GitHub server)
• Query your database
• Control Stripe, Notion, Slack, and a growing list of SaaS products
• Talk to anything anyone has written an MCP server for

The pattern is: someone writes the MCP server once, and every MCP-compatible agent can use it. Hermes benefits from the entire ecosystem without having to reimplement each integration.

Enable MCP in Hermes

MCP support is an optional extra. If you haven't already, install it:

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

This pulls in the MCP libraries. One-time setup.

Add your first MCP server

We'll add the filesystem server. It gives Hermes safe, scoped access to a specific directory on your machine — useful when you want the agent to touch files in one project without having broad filesystem access.

Open your Hermes config:

nano ~/.hermes/config.yaml

Find or add an mcp_servers: section. Add an entry like this:

mcp_servers:
  filesystem:
    command: "npx"
    args: ["-y", "@modelcontextprotocol/server-filesystem", "/home/you/projects"]

Replace /home/you/projects with an actual path on your machine — maybe your home folder, maybe a specific project directory. The server will only let Hermes see files inside that path.

Save the file.

Start using it

If Hermes isn't running, start a new session:

hermes

If Hermes is already running, reload the MCP config without restarting:

/reload-mcp

Now check your tools:

/tools

You should see new tools with names like mcp_filesystem_read_file, mcp_filesystem_list_directory, and so on. They're prefixed with mcp_ and then the server name so you can see where they came from.

Ask Hermes to use them:

List the files in my projects directory and pick the one you find most interesting.

Hermes will call the MCP filesystem server, get the list, and respond. Same pattern as any other tool.

Checkpoint — New mcp_-prefixed tools appeared in your /tools list, and Hermes successfully used one. That's the full loop.

Add a GitHub server too

Once you've done one MCP server, adding more is just more lines in the same config file.

mcp_servers:
  filesystem:
    command: "npx"
    args: ["-y", "@modelcontextprotocol/server-filesystem", "/home/you/projects"]
  github:
    command: "npx"
    args: ["-y", "@modelcontextprotocol/server-github"]
    env:
      GITHUB_PERSONAL_ACCESS_TOKEN: "ghp_xxxxxxxxxxxx"

You'll need a GitHub personal access token. Create one at github.com/settings/tokens, give it scopes for the actions you want Hermes to take, and paste it into the env section.

Save. Reload with /reload-mcp. Now Hermes has GitHub tools — it can list issues, open PRs, read commits, whatever the MCP server exposes.

Managing MCP servers from the command line

Hermes has subcommands for this if you'd rather not hand-edit YAML:

hermes mcp list       # show configured servers
hermes mcp add        # add a server interactively
hermes mcp test       # check that a server is reachable
hermes mcp remove     # remove a server

Both approaches work. Use whichever feels natural.

A note on trust

MCP servers run as subprocesses on your machine. They have whatever access you give them — the filesystem server can read any file you point it at; the GitHub server can do anything your token is scoped for. Review what a server does before installing it, especially if it's from a source you don't know.

This is the same caution you'd apply to any third-party tool. Nothing Hermes-specific about it — just worth saying once.

Where to find MCP servers

The modelcontextprotocol.io ecosystem has a growing list of servers. GitHub has many more — search for mcp-server or check the official @modelcontextprotocol npm scope. The community is active enough that new servers appear every week.

You've reached the end

That was the last step. Let's look at what else Hermes can do.