A Hermes Agent MCP server is either an outside MCP server that you plug into Hermes, or Hermes itself running as an MCP server so other agents can use it, and this guide sets up both.
The command for both is hermes mcp, which the CLI help describes as the way to "Manage MCP server connections and run Hermes as an MCP server."
Hermes Agent is the free, open-source agent from Nous Research, and MCP is the Model Context Protocol, the shared standard that lets agents and tools talk to each other.
Here's the confusion I see all the time.
People search "Hermes MCP server" and half of them want to give Hermes new tools, while the other half want Claude Code or Codex to reach into Hermes.
Those are two different jobs, so I've split this page into two parts.
Part one adds MCP servers to Hermes, and part two runs Hermes as an MCP server for other agents.
Every command below is copied from the official Hermes docs, the official plugin page or the hermes mcp --help output of a v0.22.1 install.
The Hermes Agent MCP Server Setup At A Glance
These are the ten steps on one screen, and each one has its own section below.
| Step | What you do | The command |
|---|---|---|
| 1 | You browse the Nous-approved MCP catalog. | hermes mcp or hermes mcp catalog |
| 2 | You install a catalog server by name. | hermes mcp install deepwiki |
| 3 | You add any other server yourself. | hermes mcp add <name> with --url or --command |
| 4 | You add a preset such as the Codex CLI. | hermes mcp add codex --preset codex |
| 5 | You check what's connected and test it. | hermes mcp list and hermes mcp test <name> |
| 6 | You trim each server down to the tools you need. | hermes mcp configure <name> or tools: include |
| 7 | You sign in to OAuth servers, even on a headless box. | hermes mcp login <server> --flow device |
| 8 | You install the server that exposes Hermes to other agents. | hermes plugins install mcp-serve |
| 9 | You point Claude Code, Codex or Cursor at Hermes. | "command": "hermes", "args": ["mcp-serve"] |
| 10 | You review every server before trusting it. | Read the manifest, filter tools and keep secrets scoped. |
What The Hermes Agent MCP Server Is
MCP servers are small programs that offer tools over a standard protocol.
The Hermes docs say MCP lets Hermes use tools that live outside Hermes itself, such as GitHub, databases, file systems, browser stacks and internal APIs.
When Hermes connects to one, it's the MCP client and the other program is the server.
Hermes can also flip around and be the server, so another agent can list your Hermes conversations, read messages and send replies through the platforms Hermes is connected to.
MCP support ships with the standard Hermes install, so there's nothing extra to install for part one.
🔥 Want my exact Hermes Agent MCP Server Setup setup, step by step? Inside the AI Profit Boardroom you get step-by-step video trainings, my installable Agent OS and four coaching calls a week with 3,400+ members building real automations. → Join the AI Profit Boardroom
Part 1: Add MCP Servers To Hermes Agent
Step 1: Browse the Nous-approved catalog
Hermes ships a curated catalog of MCP servers that Nous staff have reviewed and merged.
The docs say they're disabled by default, so you install only what you want.
hermes mcp # interactive picker (default)
hermes mcp catalog # plain-text list, scriptable
hermes mcp install deepwiki # install a catalog entry by name
The picker shows each entry as available, enabled or installed but disabled, and you press Enter on a row to install, enable, disable or uninstall it.
Step 2: Install from the catalog or from a chat
You can install by name with hermes mcp install, and the help says it also accepts official/<name>.
You can also just ask in a chat, for example "add the Linear MCP", and Hermes shows a setup card.
That card works as a dialog in the desktop app, a callout in the TUI and a panel in the classic 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 an OAuth server, Hermes shows the authorisation link and never opens the browser by itself.
Step 3: Add any MCP server yourself
For servers that aren't in the catalog, hermes mcp add writes the config for you.
This is the usage line from the help output.
usage: hermes mcp add [-h] [--url URL] [--command MCP_COMMAND] [--args ...]
[--auth {oauth,header}] [--preset PRESET]
[--connect-timeout CONNECT_TIMEOUT] [--env [ENV ...]]
name
Use --url for a remote HTTP or SSE server, or --command plus --args for a local stdio server.
The help notes that --args must be the last option on the line.
If you'd rather edit YAML, the docs' quick start adds a server under mcp_servers in ~/.hermes/config.yaml.
mcp_servers:
filesystem:
command: "npx"
args: ["-y", "@modelcontextprotocol/server-filesystem", "/home/user/projects"]
A remote server uses url and headers instead.
mcp_servers:
remote_api:
url: "https://mcp.example.com/mcp"
headers:
Authorization: "Bearer ***"
Most hosted servers such as Linear, Sentry, Atlassian and Stripe need OAuth, and the docs say you set auth: oauth and Hermes handles the rest.
If you're coming from Claude Code, the docs say hermes import-agent claude-code migrates your mcpServers block, and my Hermes import agent guide walks through it.
Step 4: Add a preset, such as the Codex CLI
The docs list one built-in preset, which wires up the Codex CLI's own MCP server.
hermes mcp add codex --preset codex
That writes a server that runs codex mcp-server over stdio, and it needs the codex CLI on your PATH.
This is the reverse of what I showed in my Codex video, because here Hermes calls Codex rather than Codex calling Hermes.
Step 5: List and test your servers
hermes mcp list
hermes mcp test <name>
Hermes names each MCP tool mcp_<server_name>_<tool_name>, so a GitHub tool called create-issue becomes mcp_github_create_issue.
Each server also gets its own toolset called mcp-<server>, which you can toggle in hermes tools.
After you change the config, type /reload-mcp in a chat to reload the servers.
A running gateway watches config.yaml on its own and picks up added or removed servers within about a minute.
Step 6: Keep only the tools you need
hermes mcp configure <name> toggles which tools a server contributes.
You can also do it in YAML with an allowlist or a blocklist, and the docs give these two examples.
mcp_servers:
github:
command: "npx"
args: ["-y", "@modelcontextprotocol/server-github"]
env:
GITHUB_PERSONAL_ACCESS_TOKEN: "***"
tools:
include: [create_issue, list_issues]
mcp_servers:
stripe:
url: "https://mcp.stripe.com"
tools:
exclude: [delete_customer]
enabled: false skips a server completely without deleting it.
Step 7: Sign in to OAuth servers, even on a server box
v0.22.0 added device-code login for terminals with no browser.
hermes mcp login <server> --flow device
hermes mcp reauth --all re-authenticates every OAuth server in your config, one at a time.
hermes mcp remove <name> takes a server out when you're finished with it.
🔥 Want my full Hermes and MCP playbook? Inside the AI Profit Boardroom, I've got a full Hermes Agent course plus the Agent OS, with walkthroughs on MCP, profiles and plugins. You'll be learning alongside 3,400+ members with four coaching calls every week. → Get access here
Part 2: Run Hermes As An MCP Server For Other Agents
Step 8: Install the server for your version
This part changed recently, so check your version with hermes --version first.
On a v0.22.1 install the server is still built in, and the help lists hermes mcp serve as "Run Hermes as an MCP server (expose conversations to other agents)".
hermes mcp serve
hermes mcp serve --verbose
The current docs now ship it as the official mcp-serve plugin, listed in the catalog on 21 October 2026 and named in the v0.22.4 release notes.
hermes plugins install mcp-serve
The plugin page says it needs Hermes 0.22.0 or later, and that hermes mcp serve now prints the new spelling and the install line on builds without the old command.
Step 9: Point Claude Code, Codex or Cursor at Hermes
You don't run the server yourself, because the MCP client starts and stops it over stdio.
This is the client config from the plugin page.
{
"mcpServers": {
"hermes": {
"command": "hermes",
"args": ["mcp-serve"]
}
}
}
If your client still uses the older built-in command, the docs say the args were ["mcp", "serve"], and you change them to ["mcp-serve"] after you install the plugin.
To serve another profile, the plugin page uses ["-p", "<profile>", "mcp-serve"], and the plugin must be installed in that profile too.
In my Codex and Hermes MCP walkthrough, I had Codex write the config from the docs, restart, and then list my previous Hermes conversations through the server.
That post covers the Codex side in depth, so I won't repeat it here.
What the Hermes MCP server gives other agents
| Tool | What it does |
|---|---|
conversations_list |
It lists active messaging conversations, with platform and last activity. |
conversation_get |
It returns one conversation's details. |
messages_read |
It reads recent messages in a conversation. |
attachments_fetch |
It pulls images and media from one message. |
events_poll |
It returns new messages since a cursor. |
events_wait |
It long-polls until the next event arrives. |
messages_send |
It sends a message through Hermes's own send path. |
channels_list |
It lists the targets you can send to. |
permissions_list_open |
It lists approval requests seen during the session. |
permissions_respond |
It allows or denies a pending approval request. |
Reading needs no running gateway, but the docs say sending does, because the platform connections live there.
The server is stdio only, so logs go to stderr and stdout carries the MCP traffic.
The --tools option
With the plugin, hermes mcp-serve --tools also exposes Hermes's own web, browser, vision, image generation, skills and text-to-speech tools.
It's off by default, and the plugin page says terminal, file, code execution, process, kanban and delegation tools are never exposed.
The reason is simple, because they would hand the client a shell on your machine outside Hermes's approval prompts.
Step 10: Review Every MCP Server Before You Connect It
An MCP server runs code and sees data, so I treat each one like a new contractor.
These are the checks the docs give you.
- The catalog docs say installing an entry runs whatever its manifest specifies, so read the
source:,install.bootstrap:andtransport.command:fields first. - Catalog manifests live in the
optional-mcpsfolder of the Hermes repo on GitHub, and the docs say there is no community submission tier. - For stdio servers, Hermes passes only the
envyou configure plus a safe baseline, which reduces accidental secret leaks. - Hermes strips invisible Unicode tag characters from tool results and descriptions, which the docs call a classic prompt-injection channel.
- The current docs let you mark a server
trust: untrusted, so every write-capable call asks first, and set aspend_limitper chat for tools that cost credits. - For the Hermes MCP server, the plugin page says the client can read the profile's conversation history and send messages as your connected accounts.
My rule is to connect one server at a time, filter it to the tools you need, and only then add the next.
If you also run commands inside a container, read my Hermes Agent sandbox guide, because sandboxing and tool filtering work best together.
If you'd like help working out where MCP agents fit your SEO business, you can book a free SEO strategy session with my team.
Common Hermes MCP Problems And Fixes
- If a new server's tools don't appear, run
hermes mcp test <name>, then/reload-mcp. - If an OAuth server parks after a token expires, the docs say to run
hermes mcp login <server>once. - If a headless box can't open a browser, use
--flow device. - If your client still calls
["mcp", "serve"]on a newer build, change it to["mcp-serve"]after installing the plugin. - If
messages_sendfails from Claude Code, make sure the Hermes gateway is running.
🔥 Want help wiring Hermes into your agent stack? The AI Profit Boardroom has Hermes Agent training, the Agent OS and four weekly coaching calls where you can ask me which MCP servers to connect first. → Join the AI Profit Boardroom
Related Reading
- Connect Codex to Hermes with the MCP server
- Set up a Hermes Agent sandbox
- The Hermes Agent v0.22 setup walkthrough
Also On Our Network
- 🌐 How a business uses the Hermes Agent MCP server
- 🌐 The Hermes MCP features, scored with a verdict
- 🌐 The Hermes Agent MCP server quick start for your Agent OS
- 🌐 The models behind your MCP agents, measured on GoldieBench
FAQ: Hermes Agent MCP Server
What is the Hermes Agent MCP server?
It means either an MCP server you connect to Hermes, or Hermes running as an MCP server for other agents.
The hermes mcp command manages both.
How do I add an MCP server to Hermes Agent?
Run hermes mcp for the catalog picker, hermes mcp install <name> for a catalog entry, or hermes mcp add <name> 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 use the built-in hermes mcp serve.
What tools does the Hermes MCP server expose?
It exposes ten conversation and approval tools, and --tools adds web, browser, vision, image, skills and speech tools.
Terminal, file and code execution tools are never exposed.
Is the Hermes Agent MCP server free?
Yes, Hermes and the mcp-serve plugin are MIT licensed, but tool calls cost whatever your provider charges.
If you're building an agency around agents and want a second opinion, you can book a free strategy session with my team.
📺 Video notes + links to the tools 👉
🎥 Learn how I make these videos 👉
🆓 Get a FREE AI Course + Community + 1,000 AI Agents 👉
About Julian
I'm Julian Goldie, an SEO entrepreneur, author and founder of the AI Profit Boardroom, which has 3,400+ members.
I help business owners scale with AI agents, automation and SEO.
- I've built a 7-figure SEO and link-building agency, Goldie Agency, with 70+ people in Bangkok.
- I've grown a YouTube channel to 400,000+ subscribers.
- I wrote the book "Link Building Mastery", which covers nine link building strategies.
- I run GoldieBench, where I score AI models on real one-shot builds.
→ Get my best AI training inside the AI Profit Boardroom
Add servers one at a time, install mcp-serve for the other direction, review everything you connect, and you'll have a Hermes Agent MCP server setup that works both ways.
