How-To Guide
Connect MCP Servers to Hermes Agent Safely
Connect MCP servers to Hermes Agent safely with the catalog, tool filters, OAuth, /reload-mcp, and a least-privilege trust checklist before gateway or cron use.
Quick answer
To connect MCP servers to Hermes Agent safely, prefer the curated hermes mcp catalog when available, read the manifest/source, expose only needed tools with tools.include, keep secrets in .env, test with hermes mcp test NAME, then use /reload-mcp. Do not expose a new MCP server to Telegram, Discord, or cron until the CLI test and trust checklist pass.
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:
- ☑A working Hermes CLI/provider smoke test (
hermes doctorand one smallhermes chat -qcall) - ☑A clear reason to use MCP instead of a native Hermes tool, skill, or direct API
- ☑A source repo/vendor you trust enough to run or call from your machine
- ☑A rollback path: disable the server, revoke OAuth, or rotate the API key
Steps
- 1
Choose MCP only when it fits
Use MCP for model-friendly tool discovery, local developer tools, dashboards, databases, or reviewed connector ecosystems. Use a direct API for narrow production writes, billing, or high-volume deterministic workflows.
- 2
Start from the Hermes MCP catalog when possible
Run
hermes mcp,hermes mcp catalog, orhermes mcp install <name>so you can see reviewed entries, install notes, credentials, and tool-selection prompts instead of hand-copying random server configs. - 3
Inspect the server trust boundary
Before enabling the server, record what it can read, what it can write, which credentials it needs, whether it runs local code, and whether it will ever be reachable from Telegram, Discord, cron, or a team dashboard.
- 4
Filter tools before first real use
Use
tools.includefor allowlists when possible. If you must blacklist, usetools.excludefor destructive operations and disableresourcesorpromptswhen the server does not need them. - 5
Keep secrets out of prompts and committed config
Put provider keys or OAuth tokens in the active Hermes
.env/auth flow, refer to environment variable names in notes, and never paste raw secrets into chat, skills, or public repos. - 6
Test one server from the CLI
Run
hermes mcp test NAME, then ask Hermes for one harmless read-only action from the CLI. Fix connection errors before trying a gateway, dashboard, or scheduled job. - 7
Reload deliberately
After changing config, run
/reload-mcp. If tools still do not appear in a long-running gateway or CLI, relaunch that process because MCP tool caches can stay stale across live sessions. - 8
Only then expose it to always-on surfaces
If the server can mutate data, do not connect it to Telegram, Discord, cron, or team use until approval gates, profile isolation, and rollback have been verified.
Pro Tips
- 💡Before adding MCP, ask whether a plain CLI command would be simpler and safer; the MCP vs CLI guide explains when a reusable server is worth it.
- 💡Prefer
tools.includeovertools.excludefor the first version of a server. - 💡Use one Hermes profile per trust boundary: personal, work, client, production, or experimental.
- 💡Treat stdio MCP servers as local code execution. Read the package/repo and bootstrap commands before installing.
- 💡For remote MCP, prefer OAuth/PKCE or scoped tokens over broad static keys.
- 💡If the server touches billing, production data, or customer records, consider a direct API with typed validation instead of broad MCP access.
Troubleshooting
❌ MCP tools do not appear after adding a server
✅ Run hermes mcp test NAME, then /reload-mcp. If the active Telegram/Discord gateway or CLI still shows stale tools, relaunch the process because the live session may keep an old MCP tool cache.
❌ The server exposes too many dangerous tools
✅ Use tools.include to allow only the small set you need, or tools.exclude to remove destructive tools such as delete, refund, production write, or organization-admin actions.
❌ OAuth or a remote MCP server fails during install
✅ Finish the provider auth flow, verify the endpoint from the CLI, and rerun hermes mcp configure NAME once the server is reachable so you can refine tool selection.
❌ A filesystem MCP server can read too much
✅ Point it at one project directory rather than your home directory, keep .env files out of scope where possible, and use a separate Hermes profile for experiments.
❌ A gateway or cron job used a tool you did not expect
✅ Disable the MCP server, review the session/tool logs, narrow the exposed tools, and re-enable only after testing from the CLI.
FAQ
Is the Hermes MCP catalog automatically safe?
No catalog removes the need for judgment, but Hermes catalog entries are reviewed and expose manifest/source information so you can inspect what will run. Still install only what you need and filter tools.
What is the safest first MCP server to test?
A read-only or project-scoped server, such as a filesystem server pointed at one repo or a docs/resource server, is safer than a billing, admin, or production-write server.
Should MCP servers be available in Telegram or Discord?
Only after CLI testing and tool filtering. Gateways widen the audience and can run while you are not watching, so use profiles, allowed chats/topics, and narrow tool surfaces first.
What is the difference between `include` and `exclude`?
tools.include registers only the named tools and is safest for high-risk servers. tools.exclude registers everything except named tools and is better for low-risk servers where you know only a few tools are dangerous.
Related setup and cost guides
MCP security risks checklist
Understand the threat model before enabling broad tool access.
MCP vs API decision guide
Choose MCP, direct APIs, native tools, or skills by risk and workflow.
Hermes Web UI
Use the dashboard to inspect configuration and MCP catalog details.
Pricing and managed cloud
Compare self-hosted setup work with FlyHermes managed hosting.