Connect MCP Servers to Hermes Agent Safely
Connect MCP servers to Hermes Agent with a trust checklist: host assumptions, permissions, env vars, network access, example tool calls, approval gates, and rollback.
Quick answer
To connect an MCP server to Hermes Agent, start with a dedicated profile, document exactly what the server can read or write, add one server at a time with `hermes mcp add`, verify it with `hermes mcp test NAME`, then test from the real surface that will use it. If the server needs broad credentials, filesystem access, or unattended gateway/cron execution, read the MCP security checklist before enabling it.
MCP (Model Context Protocol) lets Hermes connect to external tool servers such as GitHub, databases, local files, browser tools, or internal APIs. The safe setup question is not only “does this server exist?” Fresh MCP community discussion in June 2026 asks what proof makes a reusable MCP config trustworthy enough to install: host/client assumptions, permissions, env vars, network access, example calls, audit notes, and rollback. Use this page as the implementation checklist, then use the MCP security article for the deeper risk model.
Managed cloud · API costs included · Skill library · Cancel anytime
Before you start:
- ☑Hermes Agent installed and passing `hermes doctor`
- ☑npx, uvx, or the runtime required by the MCP server
- ☑A dedicated Hermes profile when the server needs credentials or write access
- ☑API keys or tokens scoped to the workflow, not broad personal/global secrets
Steps
- 1
Choose a trusted MCP server
Prefer maintained servers with clear host assumptions, requested permissions, env vars, network access, example tool calls, expected outputs, and a rollback path. Discovery is not enough; trust evidence matters.
- 2
Create a narrow Hermes profile
Use `hermes profile create <name>` when the MCP workflow has different secrets, tools, memory, or gateway exposure than your default profile.
- 3
Add the server
Use `hermes mcp add NAME --command ...` or add a named entry under `mcp_servers:` in config.yaml with command, args, env, timeout, and allowed_tools.
- 4
Configure environment variables explicitly
Pass only the required API keys or tokens under the server's env block. Do not let a public bot or cron profile inherit broad global credentials.
- 5
Verify before using it
Run `hermes mcp list` and `hermes mcp test NAME`, then ask for one read-only tool call with an expected output. Restart or `/reload-mcp` if a live session still has stale tool state.
- 6
Test the real surface
If the MCP server will be reachable through Telegram, Discord, webhooks, cron, or the dashboard's browser Chat tab, test that exact path after the local CLI test passes.
- 7
Document rollback
Record how to remove the server, which secrets to revoke, and which profile/gateway must restart. If no one can explain why the server is connected, remove it.
Pro Tips
- 💡Environment variables under env: are the only vars passed to the MCP subprocess — use that as a security boundary
- 💡Use npx -y @modelcontextprotocol/server-name for official MCP servers, but still inspect permissions and maintenance status
- 💡Filter exposed tools with allowed_tools before connecting the server to cron, Telegram, Discord, or public webhooks
- 💡Keep one read-only smoke test for each MCP server so future operators can tell healthy behavior from broken auth or prompt injection
- 💡If MCP setup becomes a gateway uptime, profile, Docker, or dashboard maintenance problem, compare FlyHermes before broadening self-hosted infrastructure
Troubleshooting
❌ MCP server fails to connect
✅ Check that the command and args are correct, then run the command manually. Verify npx/uvx is on PATH in the same environment that runs Hermes.
❌ Tools from MCP server are not appearing
✅ Restart Hermes or use `/reload-mcp` in the active session. If the session still sees stale failures, restart the gateway/CLI process because live sessions can cache MCP tool state.
❌ API key is not being passed to the MCP server
✅ Ensure the env var is listed under the server's env key in config.yaml and exists in the active profile's .env. Docker/VPS services often run with a different environment than your shell.
❌ MCP tool calls time out
✅ Increase timeout and connect_timeout for long-running tools, then test one read-only call before exposing the server to cron or gateways.
❌ The MCP server works locally but feels unsafe for a team bot
✅ Move it into a separate Hermes profile, remove write-capable tools, restrict credentials, and read the MCP security checklist before connecting Telegram, Discord, or cron.