✦
Hermes Agent
Open navigation menu

How-To Guide

Connect MCP Servers to Hermes Agent Safely

Connect local, Docker, and OAuth MCP servers to Hermes Agent safely. Fix mcp_servers YAML, container paths, remote auth, stale tools, and gateway reloads.

Quick answer

To connect an MCP server to Hermes Agent, use hermes mcp install NAME for a catalog server or hermes mcp add NAME --url URL --auth oauth for a hosted OAuth server. For a local stdio server, use hermes mcp add NAME --command COMMAND --args .... Confirm manual config is under the top-level mcp_servers: key, run hermes mcp test NAME, choose tools with hermes mcp configure NAME, then use /reload-mcp or restart the gateway. In Docker, every command path and localhost URL must resolve inside the container.

MCP (Model Context Protocol) lets Hermes connect to external tool servers such as GitHub, databases, local files, browser tools, or internal APIs. This guide owns the implementation intent: choose MCP instead of a CLI command, add the right transport, authenticate it, test it, and make the tools appear in the correct profile. Fresh July 2026 support threads exposed two repeatable failures: a Docker install used mcp: servers: instead of the required top-level mcp_servers: key, and a hosted OAuth connector was mistaken for an API-key integration. Use this page as the setup and troubleshooting checklist, the MCP security guide for the threat model, MCP vs API for architecture, and the Hermes Web UI guide for the self-hosted configuration surface.

Deploy Hermes faster with FlyHermes

Managed cloud · API costs included · Skill library · Cancel anytime

Before you start:

  • ☑A working Hermes CLI/provider smoke test (hermes doctor and one small hermes chat -q call)
  • ☑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. 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. 2

    Start from the Hermes MCP catalog when possible

    Run hermes mcp, hermes mcp catalog, or hermes mcp install <name> so you can see reviewed entries, install notes, credentials, and tool-selection prompts instead of hand-copying random server configs. For a custom server, use hermes mcp add NAME --url URL or hermes mcp add NAME --command COMMAND --args ...; put --args last because it consumes the remaining arguments.

  3. 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. 4

    Filter tools before first real use

    Use tools.include for allowlists when possible. If you must blacklist, use tools.exclude for destructive operations and disable resources or prompts when the server does not need them.

  5. 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. 6

    Finish OAuth from a fresh terminal

    For a hosted OAuth server, run hermes mcp add NAME --url https://example.com/mcp --auth oauth, complete the browser flow, and use hermes mcp login NAME to re-authenticate. If Hermes runs on a remote host, use the documented paste-back redirect flow or an SSH port forward. Do not start interactive OAuth by editing config inside a running session because its short auto-reload timeout can expire before authorization finishes.

  7. 7

    Resolve paths and localhost from inside Docker

    A stdio command must exist at the container path, not only on the host. A URL such as 127.0.0.1:3002 means the same container; use a Compose service name for another container or host.docker.internal on supported desktop Docker setups for a service on the host. Keep manual YAML under top-level mcp_servers:, not mcp: servers:.

  8. 8

    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.

  9. 9

    Run negative security tests

    Use the MCP security control matrix to test three failures before production: poisoned tool output must not trigger an instruction, a non-allowlisted write must be unavailable or approval-gated, and a revoked test credential must fail without a partial side effect. Record the profile, exposed tools, server version, and result.

  10. 10

    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.

  11. 11

    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.include over tools.exclude for 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.
  • 💡OAuth credentials are cached per server under the active Hermes home; changing profiles or containers can make a successful login appear missing.
  • 💡A successful tools/list response does not prove OAuth completed. Run one harmless authenticated tool call after hermes mcp login NAME.
  • 💡If the server touches billing, production data, or customer records, consider a direct API with typed validation instead of broad MCP access.
  • 💡A successful read test proves connectivity, not safety. Repeat the poisoned-output, denied-write, and revoked-credential tests after server updates, scope changes, or new gateway access.

Troubleshooting

❌ The server never appears because manual YAML uses `mcp: servers:`

✅ Hermes reads MCP definitions from the top-level mcp_servers: key. Prefer hermes mcp add so Hermes writes the correct shape, or move the server block under mcp_servers: and run hermes mcp test NAME.

❌ A local MCP command exists on the host but fails in Docker

✅ Enter the container and verify the exact command path there. Bind mounts can map the same files to a different path, and a host executable is not automatically available inside the container. Use the container path in command, then test from the same container that runs Hermes.

❌ A local HTTP MCP or backing API works on the host but not in Docker

✅ Test the URL from inside the Hermes container. Use 127.0.0.1 only when the service runs in that same container, a Compose service name when it runs in another container, or host.docker.internal on supported Docker Desktop setups when it runs on the host.

❌ 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

✅ Run hermes mcp login NAME from a fresh terminal and verify that authorization produces a cached token, not merely a public tools/list response. On a remote host, use paste-back or an SSH port forward. Then run hermes mcp test NAME and hermes mcp configure NAME.

❌ 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.

❌ A tool result contains instructions asking the agent to reveal secrets or call another tool

✅ Treat the result as untrusted data, stop the workflow, remove write-capable tools from that profile, and reproduce with a harmless fixture. Keep fetched pages, files, tickets, email, and API output outside the authority boundary.

FAQ

Can Hermes connect to an MCP server that uses OAuth but has no API key?

Yes. Add the remote server with hermes mcp add NAME --url URL --auth oauth, complete browser authorization, and use hermes mcp login NAME to authenticate again. Some providers do not support dynamic client registration and require your own OAuth client ID and secret.

Why does my MCP server work outside Docker but fail in Hermes Docker?

Hermes resolves the command path, environment variables, DNS names, and localhost from inside its container. Verify the executable and backing service from that same container, then use the container path or Compose service name in the MCP config.

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.

How do I know an MCP server is safe enough for a gateway or cron job?

Do not rely on a normal smoke test alone. Verify source and scopes, use a narrow profile and tool allowlist, then test poisoned output, a denied write, and revoked credentials before enabling unattended access.

Why is my MCP server visible in one profile but not another?

MCP servers are configured per Hermes profile. A server added to your default profile is not available in a work or bot profile, so a missing server is usually profile isolation rather than a broken install. Add the server with the target profile (hermes -p NAME mcp add ...) or repeat the setup in every profile that needs it.

Why is my database MCP server read-only?

Many reference database servers register only read-only query tools by default. Write access requires a separate server or an explicit unrestricted access mode. Verify which tools the server registers with hermes mcp test NAME before connecting it, and keep read-only until a write workflow is actually needed.

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.

Related Guides

mcp vs cli ai agentstool usebrowser automationhermes browser automation guideconfigure browser automation