.svg)
.svg)
.svg)
.svg)
.svg)
.svg)
.svg)
MCP (Model Context Protocol) is the standard Anthropic shipped in late 2024 for connecting agents to tools and data sources. The whole point: instead of every agent author writing their own filesystem connector, Git connector, database connector, you write the connector once as an MCP server and any MCP-compliant agent can use it. Hermes Agent speaks MCP. Most useful agent feature people don't enable.
This article covers what MCP is in plain terms, how Hermes consumes MCP servers and three concrete server setups that pay back the configuration time immediately.
But first... what does MCP mean?
Well, an MCP server is a small process that exposes a set of tools to an MCP client (the agent). The client lists available tools at startup, calls them when needed, gets responses back. Communication happens over stdio (the simple case) or HTTP (the network case). You don't need to know the protocol details unless you're writing your own server. As a user, you mostly point Hermes at a binary or a docker image and it works.
How Hermes consumes MCP servers
MCP servers in Hermes are configured in your ~/.hermes/config.yaml under an mcp_servers block. Each server has a name (your choice), a command to launch it (binary or npm script), arguments and optional environment variables.
On startup Hermes spawns each configured server as a subprocess, queries the available tools and registers them with the agent. The tools then appear alongside built-in tools in hermes tools list. The model can invoke them like any other tool. The agent doesn't know or care that the underlying implementation is an MCP server. To the LLM it's just another callable function.
Reference docs at Hermes MCP integration.
Server 1: filesystem MCP
The most useful first MCP server. Gives the agent structured read and write access to a directory you control. Better than just enabling the shell tool because the filesystem MCP exposes typed operations (read_file, write_file, list_directory) instead of raw bash. Better security characteristics too.
Install
The official Anthropic-maintained filesystem server is on npm:
npm install -g @modelcontextprotocol/server-filesystemConfigure in Hermes
Edit ~/.hermes/config.yaml and add the server:
mcp_servers:
filesystem:
command: npx
args:
- "@modelcontextprotocol/server-filesystem"
- "/home/youruser/projects"
enabled: trueThe directory argument is the root the server is allowed to touch. Outside that root: blocked. Pick a scoped directory, not /.
Verify
hermes restart
hermes tools list | grep -i mcpYou should see filesystem_read_file, filesystem_write_file, filesystem_list_directory and similar tools. If the list is empty, the server didn't start; check ~/.hermes/logs/mcp-filesystem.log.
Server 2: Git MCP
Gives the agent git operations as typed tools: list commits, read diffs, stage changes, commit, push. Same idea as the filesystem server but for repository operations.
Install
pip install mcp-server-gitConfigure
mcp_servers:
git:
command: python
args:
- "-m"
- "mcp_server_git"
- "--repository"
- "/home/youruser/projects/myrepo"
enabled: trueScope to one repo per server. If you work in multiple repos, define multiple git servers in the config (git_work, git_personal, etc.).
Why this beats running git through the shell tool?
Two reasons. The MCP git server exposes typed operations, so the model can reason about "stage this file" without constructing a shell command that has to parse correctly. And it gives you a cleaner audit trail; the audit log shows "git_stage_file: src/foo.ts" instead of "shell: git add src/foo.ts" buried among other shell calls.
Server 3: Postgres MCP
Lets the agent query a Postgres database as a typed tool. Useful for: building dashboards on the fly, debugging production issues by querying logs, generating reports from operational databases. Less useful for: anything where you don't want the agent reading sensitive rows.
Install
npm install -g @modelcontextprotocol/server-postgresConfigure with a read-only connection
mcp_servers:
postgres-prod:
command: npx
args:
- "@modelcontextprotocol/server-postgres"
- "postgresql://readonly_user:[email protected]:5432/analytics"
enabled: trueImportant: use a read-only Postgres user. Don't connect with a user that has write or admin permissions. The MCP server itself doesn't enforce read-only. The database does.
Allowlisting tables
If your Postgres has tables the agent shouldn't see (user PII, payment info), use Postgres row-level security or grant SELECT only on specific tables to the read-only user. Don't rely on telling the model "don't query the users table"; that works until it doesn't.
The general pattern
Whatever MCP server you add, the config block looks roughly the same:
mcp_servers:
<your-name-for-it>:
command: <how-to-launch-the-server>
args:
- <arg1>
- <arg2>
env:
KEY: value
enabled: trueThe env block is for secrets the server needs (API keys for SaaS MCP servers, database passwords, etc.). Don't hardcode secrets in args; the args show up in process listings and logs. Use env instead.
Debugging an MCP server that won't start
Three common failures.
Command not found
The server binary isn't on the PATH Hermes uses. Either give the absolute path in command or add the directory to Hermes's environment.
mcp_servers:
filesystem:
command: /usr/local/bin/npx
args:
- "@modelcontextprotocol/server-filesystem"
- "/data"Server crashes immediately on launch
Check the per-server log:
cat ~/.hermes/logs/mcp-<servername>.logTypical causes: missing dependencies (pip install failed silently), wrong argument format, no access to the configured directory or database.
Server starts but tools don't appear in Hermes?
The server may not be implementing the MCP listing protocol correctly. Restart Hermes and check the main log:
grep -i mcp ~/.hermes/logs/agent.logYou're looking for "registered N tools from mcp-servername" lines. If the count is 0 or there's no line at all, the server isn't responding to the list_tools request.
Important: Security considerations
An MCP server runs as a subprocess of the Hermes gateway. Whatever permissions Hermes has, the MCP server has. If your gateway runs as a regular user with limited filesystem access, the MCP server inherits those limits. If your gateway runs as root (don't do this), the MCP server is root too.
Three rules I follow:
- Filesystem MCP scoped to a specific directory, never the home dir
- Database MCP connected as a read-only user, never an admin
- Network MCP servers (HTTP-based) only over loopback or tailnet, never public
Beyond that, the same sandbox principles in our Hermes Docker sandbox and SSRF protection tutorial apply to MCP setups too.
Disabling without removing
If you want to temporarily disable an MCP server without deleting its config:
mcp_servers:
postgres-prod:
command: npx
args: [...]
enabled: falseRestart Hermes. The server doesn't start, its tools don't register, the model can't call them. Flip back to true when you want them back.
The wider MCP server library
The official server list (modelcontextprotocol/servers) has maybe 30 community-maintained servers covering Slack, GitHub, Google Drive, Stripe, Brave Search and lots more. Adding any of them follows the same pattern. Read the server's README for its required args and env vars.
Where MCP starts to bite is debugging multi-server interactions. When the agent decides "I'll search Slack, then write to Git, then query Postgres" and one of those servers errors, the failure modes get harder to trace. Audit log on is mandatory once you have more than two or three MCP servers wired up. Covered in our sandbox and security tutorial.
When to skip MCP entirely
If your agent only needs shell, filesystem and the built-in browse tool, you don't need MCP. The built-in tools are fine. MCP earns its complexity when you want structured access to specific systems (databases, SaaS APIs, internal services) without writing a custom skill for each.
Hosting MCP servers alongside Hermes on a VPS
MCP servers run as subprocesses of the gateway, so they live on whatever box hosts Hermes. The LumaDock Hermes Agent template handles this fine on the standard tiers (the servers themselves are lightweight; a few hundred MB extra for the typical filesystem + git + postgres setup). Unmetered bandwidth and no setup fees, which matters because some MCP servers (web search, GitHub) make a lot of outbound API calls. Full setup in our Hermes Agent complete guide.
