agentos.guide › blog

Hermes Agent MCP Server: The Quick Start For Both Directions, And How It Fits Your Agent OS

By Julian Goldie · 22 October 2026 · agentos.guide

The Hermes Agent MCP server covers two jobs: Hermes using outside MCP servers as tools, and Hermes running as an MCP server so Claude Code, Codex or Cursor can use it.

Hermes Agent is the free, open-source agent from Nous Research, and the hermes mcp command manages both directions.

The server side now ships as the official mcp-serve plugin, so the setup you copy depends on your version.

This page is the quick start for both directions, plus how MCP fits each profile in an Agent OS.

The Hermes Agent MCP server quick start

This is the shortest path to MCP working in both directions inside your Agent OS.

The rest of this page explains each step, then shows how I'd map MCP to Agent OS profiles.

What the Hermes Agent MCP server is

MCP, the Model Context Protocol, is a shared standard that lets an agent use tools that live in another program.

Hermes uses it in two directions, and the CLI help describes hermes mcp as the way to "Manage MCP server connections and run Hermes as an MCP server."

In the first direction, Hermes is the client and gains tools such as GitHub, databases, file systems, browser stacks and internal APIs.

In the second direction, Hermes is the server, and agents such as Claude Code, Claude Desktop, Cursor and Codex can read and send your Hermes messages.

MCP support ships with the standard Hermes install, and Hermes is free and open source from Nous Research.

Every hermes mcp command

This is the full command list from hermes mcp --help on a v0.22.1 install.

🔥 Want the exact Hermes Agent setup I run inside my Agent OS?

Inside the AI Profit Boardroom you get the installable Agent OS, step-by-step video tutorials, four coaching calls a week and 3,400+ members building real automations.

→ Get access here

Direction 1: add MCP servers to Hermes

The fastest route is the catalog, which the docs say holds servers that Nous staff have reviewed and merged.

hermes mcp                   # interactive picker (default)
hermes mcp catalog           # plain-text list, scriptable
hermes mcp install deepwiki  # install a catalog entry by name

Catalog entries are disabled by default, so you install only what you want.

You can also ask Hermes in a chat, for example "add the Linear MCP", and a setup card appears in the desktop app, the TUI or the CLI.

In the desktop app, v0.22.0 replaced the old MCP tab with a Connectors page that lists hosted apps and your MCP servers together.

For a server outside the catalog, hermes mcp add <name> takes --url for a remote server or --command and --args for a local one.

The docs' one built-in preset wires up the Codex CLI's own MCP server with hermes mcp add codex --preset codex, and it needs the codex CLI on your PATH.

If you prefer YAML, servers live under mcp_servers in ~/.hermes/config.yaml.

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

Hermes names each tool mcp_<server_name>_<tool_name>, and each server gets its own toolset called mcp-<server>.

After a config change, type /reload-mcp in a chat, and a running gateway also picks up changes within about a minute.

If you're moving from Claude Code, the docs say hermes import-agent claude-code migrates its MCP servers, which my Hermes import agent guide covers.

Signing in and keeping each server small

Most hosted servers need OAuth, and the docs say auth: oauth makes Hermes handle discovery, PKCE, token exchange and refresh.

For a headless server, v0.22.0 added hermes mcp login <server> --flow device.

hermes mcp reauth --all re-authenticates every OAuth server one at a time.

To keep a server small, use hermes mcp configure <name> or a tools: include list in YAML.

The docs' Stripe example uses tools: exclude: [delete_customer] to drop a destructive tool.

The v0.22.3 release notes also list MCP progress notifications streamed as live tool progress.

Direction 2: run Hermes as an MCP server

Check your version first with hermes --version, because this part changed recently.

Builds such as v0.22.1 ship the server built in as hermes mcp serve, with --verbose for debug logging.

The current docs ship it as the official mcp-serve plugin, listed in the catalog on 21 October 2026, and the plugin page says it needs Hermes 0.22.0 or later.

hermes plugins install mcp-serve

You don't start the server yourself, because your MCP client launches it over stdio.

{
  "mcpServers": {
    "hermes": {
      "command": "hermes",
      "args": ["mcp-serve"]
    }
  }
}

If a client still uses the older args ["mcp", "serve"], the plugin page says you change them to ["mcp-serve"].

To serve another profile, the plugin page uses ["-p", "<profile>", "mcp-serve"], and the plugin must be installed in that profile too.

Reading needs no running gateway, but sending does, because the platform connections live in the gateway.

With hermes mcp-serve --tools, the client also gets Hermes's web, browser, vision, image generation, skills and text-to-speech tools.

The plugin page says terminal, file, code execution, process, kanban and delegation tools are never exposed, because they would hand the client a shell outside Hermes's approval prompts.

In my Codex and Hermes video, Codex initialised the Hermes MCP server, listed the tools and returned my previous Hermes conversations.

🔥 Want the exact Hermes Agent setup I run inside my Agent OS?

Inside the AI Profit Boardroom you get the installable Agent OS, step-by-step video tutorials, four coaching calls a week and 3,400+ members building real automations.

→ Get access here

How the Hermes MCP server fits an Agent OS workflow

My Agent OS runs Hermes alongside other agents, and MCP is how I'd let them call each other instead of copying text between windows.

The way I'd roll it out is one direction at a time.

Add one reviewed server to one Hermes profile first, then install mcp-serve and connect one coding agent to it.

If something misbehaves, you'll know exactly which link caused it.

For the dashboard side of running several Hermes profiles, my Hermes Command Desk guide shows how I keep them in one place.

Review every MCP server before you connect it

The docs say installing a catalog entry runs whatever its manifest specifies, so read its source:, install.bootstrap: and transport.command: fields first.

Manifests live in the optional-mcps folder of the Hermes repo, and the docs say there is no community submission tier.

For stdio servers, Hermes passes only the env you configure plus a safe baseline, which reduces accidental secret leaks.

Hermes strips invisible Unicode tag characters from tool results, which the docs describe as a classic prompt-injection channel.

A server marked trust: untrusted asks before every write-capable call, and a spend_limit caps costed calls per chat.

For the Hermes server, the plugin page warns that the client can read the profile's conversation history and send messages as your connected accounts.

If your agents also run commands, pair this with a container, as I explain in my Hermes Agent sandbox guide.

If you'd like help planning where MCP agents fit your SEO business, you can book a free SEO strategy session with my team.

The limits to know

• The Hermes MCP server is stdio only, and the docs suggest a separate adapter if you need HTTP.
• The server command moved from hermes mcp serve to the mcp-serve plugin, so older configs need updating.
• Sending needs the Hermes gateway running.
• The event queue lives in memory and starts when the server starts.
• Tool calls cost whatever your configured provider charges.

FAQ

What is the Hermes Agent MCP server?

It covers two directions. Hermes can connect to outside MCP servers to gain tools, and Hermes can run as an MCP server so Claude Code, Claude Desktop, Cursor or Codex can read and send your Hermes messages. hermes mcp manages both.

How do I add an MCP server to Hermes?

Run hermes mcp for the catalog picker, hermes mcp install deepwiki to install a catalog entry, or hermes mcp add with --url or --command for anything else.

How do I run Hermes as an MCP server?

On current builds, run hermes plugins install mcp-serve and point your client at hermes with the args ["mcp-serve"]. Older builds such as v0.22.1 use the built-in hermes mcp serve.

Can another agent run commands through the Hermes MCP server?

No. The plugin page says terminal, file, code execution, process, kanban and delegation tools are never exposed, even with --tools.

Does the Hermes MCP server need the gateway running?

Reading conversations does not, but sending messages does, because the platform connections live in the gateway.

Is the Hermes Agent MCP server free?

Yes. Hermes and the mcp-serve plugin are MIT licensed, and tool calls cost whatever your configured provider charges.

Final word on the Hermes Agent MCP server

Add one reviewed server, install mcp-serve for the other direction, and connect one agent at a time.

If you run an agency and want help planning agent work for clients, you can book a free strategy session with my team.

If you want the whole Agent OS with the Hermes tab, the profiles and the training already set up, it lives inside the AI Profit Boardroom, with 3,400+ members and four coaching calls a week.

That is the fastest way to get real work out of the Hermes Agent MCP server.

Related guides on agentos.guide

→ Hermes Agent v0.22: The Quick Start

→ The Hermes Command Desk

→ The Best Hermes Agent Tools

→ Hermes On A Claude Subscription

📺 Video notes + links to the tools 👉

🎥 Learn how I make these videos 👉

🆓 Get a FREE AI Course + Community + 1,000 AI Agents 👉

← all guides on agentos.guide