A Hermes Agent MCP server setup means one of two things: connecting MCP servers to Hermes so it can use outside tools, which you do with hermes mcp add or the mcp_servers block in config.yaml, or running Hermes itself as an MCP server with hermes mcp serve so other agents like Claude Code can use it. This guide covers both, straight from the current Hermes docs.
📺 Watch: NEW Codex + Hermes Agent MCP is Insane! (FREE!)
🔥 Get the Agent OS as a free bonus: AI Profit Boardroom members get the full Agent OS zip, prompt libraries, daily tutorials and weekly live coaching calls. → Get inside
Most people mean the first one. They want Hermes to talk to GitHub, Linear, a database or some internal API. The second one is newer and narrower, and I'll show you exactly what it exposes so you don't expect more than it does.
I run Hermes every day inside my Agent OS, with a profile per model. MCP is how I plug outside tools into it without writing a custom tool for every one.
What MCP gives Hermes
MCP, the Model Context Protocol, lets Hermes connect to external tool servers so the agent can use tools that live outside Hermes itself. Think GitHub, databases, file systems, browser stacks and internal APIs.
Per the docs, you get:
- Access to external tool ecosystems without writing a native Hermes tool first
- Local stdio servers and remote HTTP MCP servers in the same config
- Automatic tool discovery and registration at startup
- Per-server filtering, so Hermes only sees the MCP tools you actually want
MCP support ships with the standard install. There's no extra step.
If you want to learn Hermes properly, MCP included, the AI Profit Boardroom has Hermes courses, daily updates, my Agent OS zip and 4 coaching calls a week, for $69/mo.
Hermes Agent MCP server setup: the quick reference
Here's every task in one place, using only commands and settings from the docs.
| Task | Command or setting |
|---|---|
| Open the interactive MCP picker | hermes mcp |
| List the Nous-approved catalog | hermes mcp catalog |
| Install a catalog entry | hermes mcp install deepwiki |
| Add a remote OAuth server | hermes mcp add my-oauth-server --url https://mcp.example.com/mcp --auth oauth |
| Add a server from a preset | hermes mcp add codex --preset codex |
| Log in to an OAuth server | hermes mcp login (server name) |
| Log in with no callback | hermes mcp login (server name) --flow device |
| Pick which tools a server exposes | hermes mcp configure (server name) |
| Test a server | hermes mcp test (server name) |
| Remove a server | hermes mcp remove (server name) |
| Reload MCP servers in a session | /reload-mcp |
| Declare servers by hand | mcp_servers in ~/.hermes/config.yaml |
| Run Hermes as an MCP server | hermes mcp serve |
📺 Watch: Higgsfield MCP Makes Hermes Agent Unstoppable
Part one: connecting MCP servers to Hermes
Option 1: the catalog of Nous-approved MCPs
This is the easiest route. Hermes ships a curated catalog of MCP servers that Nous staff have reviewed and merged. They're disabled by default, so you install only what you want.
Run hermes mcp for the interactive picker. It shows each entry with its status, such as available, enabled, or installed but disabled. Hit Enter on a row to install, enable, disable or uninstall. Prefer plain text? Run hermes mcp catalog. Know the name already? Run hermes mcp install followed by the name, like hermes mcp install deepwiki.
Presence in the catalog means Nous approval. There's no community submission tier. Entries get added by merging a pull request.
You can also just ask in chat: "add the Linear MCP". The agent brings up a setup card in the desktop app, the terminal UI or the classic CLI. The card shows the setup fields, masks secrets, gives you an authorization link for OAuth entries, and only saves once the server has accepted the token and the first connection works. If it fails, nothing from the attempt is kept.
That's how I'd do it. Ask your agent. Don't hand-edit config unless you have to.
Option 2: hermes mcp add
For servers outside the catalog, use hermes mcp add. For a remote server with OAuth, the docs example is hermes mcp add my-oauth-server --url https://mcp.example.com/mcp --auth oauth.
For well-known servers there's a --preset flag that fills in the transport details. The docs list one preset, codex, which wires up the Codex CLI's MCP server over stdio. You run hermes mcp add codex --preset codex, and you need the codex CLI on your PATH.
Option 3: mcp_servers in config.yaml
You can also declare servers by hand in ~/.hermes/config.yaml. A local stdio server from the docs looks like this:
mcp_servers:
filesystem:
command: "npx"
args: ["-y", "@modelcontextprotocol/server-filesystem", "/home/user/projects"]
A remote HTTP server uses a url and headers instead of a command. For OAuth, set auth: oauth and Hermes handles discovery, client identification, PKCE, token exchange, refresh and step-up auth. Then start Hermes with hermes chat and ask it to use the new capability.
Hermes prefixes MCP tools so they don't clash with built-in names. The pattern is mcp, then the server name, then the tool name. So a filesystem server's read_file tool becomes mcp_filesystem_read_file.
Coming from Claude Code? The mcpServers block in your Claude config maps to mcp_servers in Hermes, and hermes import-agent claude-code migrates it for you along with skills and instructions. More on that in my Hermes import agent guide.
Want help deciding which MCP servers are worth connecting for your business? Book a free AI strategy session.
OAuth tips from the docs
- Edit config, then log in from a fresh terminal. Inside a running session, MCP auto-reload has a 30 second timeout, which isn't enough for OAuth. Run hermes mcp login from a new terminal and it waits the full 5 minutes.
- No browser on the host? If the server supports it, hermes mcp login with --flow device prints a URL and a short code you enter on any device.
- Some providers need your own OAuth client. The docs call out Google Drive and Atlassian, which reject automatic registration. hermes mcp login now checks a token actually landed and tells you if you need to supply one.
📺 Watch: Hermes Agent + Blender MCP is INSANE!
How Hermes handles MCP credentials
This is the part I like. MCP stdio subprocesses get a filtered environment so your keys don't leak by accident.
Only these pass through from your machine: PATH, HOME, USER, LANG, LC_ALL, TERM, SHELL and TMPDIR, plus any XDG variables. Every other environment variable, including API keys, tokens and secrets, is stripped. The only extra values a server gets are the ones you put in its own env config.
Catalog entries that need an API key prompt you at install time and write it to ~/.hermes/.env.
Error messages from MCP tools are also cleaned before the model sees them. GitHub tokens, OpenAI-style keys, bearer tokens and things like token=, key=, password= and secret= get replaced with [REDACTED].
Old way: paste every key into a config file and hope nothing leaks. New way: each server sees only what you hand it.
Part two: running Hermes as an MCP server
Hermes can also be an MCP server. That lets other MCP-capable agents, like Claude Code, Cursor or Codex, use Hermes's messaging: list conversations, read message history and send messages across your connected platforms.
Start it with hermes mcp serve. It's a stdio MCP server, so your MCP client manages the process, not you. Add hermes with the args mcp and serve to your client's MCP config. For debug logging on stderr, use hermes mcp serve --verbose.
It exposes 10 tools: conversations_list, conversation_get, messages_read, attachments_fetch, events_poll, events_wait, messages_send, channels_list, permissions_list_open and permissions_respond.
Know the limits the docs list:
- It's stdio-only today. For an HTTP MCP server you'd need a separate adapter.
- Sends are text-only. No media or attachments through messages_send.
- The gateway doesn't need to run for reading, but it does need to run for sending.
So it's not "all of Hermes as a tool". It's a messaging bridge. That's still useful: your coding agent can read and send Telegram, Discord or Slack messages through Hermes.
How this differs from my older MCP page
My earlier Hermes MCP server post covered the idea. This one is the up-to-date, docs-based setup guide: the catalog, the setup card, OAuth login, credential filtering and the exact tools hermes mcp serve exposes. If you want MCP for search visibility work, see my GEO MCP breakdown.
Before you trust any model to drive these tools, test it. That's why I built Goldie Bench. And for how MCP fits with profiles and skills in one system, read my Agent OS guide.
FAQ
How do I add an MCP server to Hermes?
Run hermes mcp to open the picker and install from the Nous-approved catalog, use hermes mcp add for other servers, or add an entry under mcp_servers in ~/.hermes/config.yaml. You can also just ask Hermes in chat, like "add the Linear MCP".
Can Hermes run as an MCP server?
Yes. hermes mcp serve starts a stdio MCP server with 10 messaging tools, so agents like Claude Code, Cursor or Codex can list conversations, read history and send messages through Hermes.
Are my API keys safe with MCP servers in Hermes?
Stdio MCP servers get a filtered environment, so API keys and tokens are stripped unless you set them in that server's env config. Errors are also redacted before the model sees them.
Does hermes mcp serve support HTTP?
Not today. It's stdio-only. The MCP client side of Hermes speaks both stdio and HTTP, but the built-in server is stdio.
Want Hermes courses, daily updates and 4 coaching calls a week? Join the AI Profit Boardroom for $69/mo. Or get your MCP setup planned with a free AI strategy session. If you want one more pair of eyes on the setup before you go live, book another free AI strategy session any time.
