Hermes Agent MCP: connect MCP servers to your agent

What MCP gives a Hermes agent

An MCP server is a program or web endpoint that publishes a list of tools. When Hermes starts, it connects to each server you configured, reads the list and registers those tools next to the built-in ones. From then on the model picks them the same way it picks any other tool. In practice that means:

• access to existing tool ecosystems without writing a native Hermes tool;
• local servers that run as a subprocess (stdio) and remote servers reached over HTTP, in one config;
• optional wrappers for a server’s resources and prompts, added only when the server really supports them;
• a per-server filter, so the agent sees only the tools you choose.

To keep names from clashing, Hermes prefixes every MCP tool with mcp__<server>__. A read_file tool from a server called filesystem becomes mcp__filesystem__read_file, and a name with a hyphen or dot such as create-issue has it replaced by an underscore. You rarely type these names; you ask for the outcome and the agent chooses the tool. Each server that contributes at least one tool also gets a toolset called mcp-<server>.

MCP support ships with the standard install. Most local servers are started with npx, so Node.js needs to be on the machine; the installer sets it up if it is missing. If you have not installed Hermes yet, start with how to install Hermes Agent.

One caution before the details. An MCP server is code you run, or a service you hand credentials to, and the agent can act through it. Add only servers you trust, give them the narrowest access that works, and use the tool filter in the section below for anything that can change or delete data.

Adding servers in config.yaml: stdio, HTTP and secrets

Hermes reads MCP servers from the mcp_servers block of ~/.hermes/config.yaml. Each entry has a name of your choosing. A server is one of two kinds, decided by which key you give it.

A stdio server is a local command. Use command and args, plus env for variables the process needs:

mcp_servers:
  filesystem:
    command: "npx"
    args: ["-y", "@modelcontextprotocol/server-filesystem", "/home/user/projects"]

An HTTP server is a remote endpoint. Use url, and headers if it wants a token:

mcp_servers:
  company_api:
    url: "https://mcp.example.com/mcp"
    headers:
      Authorization: "Bearer ${COMPANY_API_TOKEN}"

HTTP servers use the streamable HTTP transport by default. If an endpoint speaks only SSE, add transport: sse. Remote connections honour the usual proxy variables such as HTTPS_PROXY and NO_PROXY.

Keep secrets out of the YAML. Any string in a server entry (env, headers, args, url) can refer to an environment variable with ${NAME}, and the variables Hermes sees include everything in ~/.hermes/.env. So put the real token in that file and only the reference in config.yaml:

# ~/.hermes/.env
GITHUB_TOKEN=your-token-here

# ~/.hermes/config.yaml
mcp_servers:
  github:
    command: "npx"
    args: ["-y", "@modelcontextprotocol/server-github"]
    env:
      GITHUB_PERSONAL_ACCESS_TOKEN: "${GITHUB_TOKEN}"

Stdio servers receive a filtered environment rather than your whole shell environment. It includes a safe baseline, variables supplied by configured external secret sources, selected Hermes runtime variables, and the server entry’s env values. List other variables the server needs under env.

After you edit the file, run /reload-mcp inside a session to reconnect the servers and refresh the tool list, or start a new session. A running messaging gateway also watches the file and, within about a minute, connects entries you added and drops entries you removed or set to enabled: false. Setting enabled: false is the way to switch a server off without deleting its config.

The hermes mcp commands: add, list, test, remove

You can skip hand-editing and let Hermes write the entry. The subcommands of hermes mcp:

• hermes mcp add <name> adds a server, with --url for a remote endpoint or --command for a local one.
• hermes mcp list (alias ls) shows each server with its transport, how many tools are selected and whether it is enabled.
• hermes mcp test <name> connects and prints the tools the server reports.
• hermes mcp configure <name> reopens the tool checklist for a server.
• hermes mcp remove <name> (alias rm) deletes the entry and its saved OAuth tokens.
• Use hermes mcp login <name> or hermes mcp reauth <name> to repeat OAuth sign-in for one server, or hermes mcp reauth --all for every configured OAuth server (more below).
• hermes mcp catalog and hermes mcp install <name> work with the built-in catalog; hermes mcp serve is covered near the end.

Two typical additions:

hermes mcp add ink --url "https://mcp.ml.ink/mcp"
hermes mcp add github --env GITHUB_PERSONAL_ACCESS_TOKEN=your-token-here --command npx --args -y @modelcontextprotocol/server-github

Mind the order: --args takes everything after it, so it must be the last option. The --env option (KEY=VALUE) works for stdio servers only, and --connect-timeout sets the connection time limit. Note that a value passed with --env is written into config.yaml; for a real token, use the ${NAME} reference described above instead.

add is discovery-first. For a remote server it asks whether authentication is needed; if you say yes it prompts for a token, stores it in ~/.hermes/.env as MCP_<NAME>_API_KEY and writes a bearer header that points at that variable. With --auth oauth it sets up OAuth instead. It then connects, lists the tools and lets you tick the ones to keep. If the connection fails, it offers to save the entry disabled so you can fix it and run hermes mcp test later. It ends with a reminder to start a new session to use the tools.

hermes mcp test also works as a health check in scripts, because its exit code is 0 when it connected, 1 when the connection failed and 3 when no server has that name.

The catalog. Hermes ships a short list of reviewed servers, all off until you install them. hermes mcp catalog prints it, hermes mcp install deepwiki installs one by name, and plain hermes mcp opens an interactive picker. Entries that need a key prompt for it and save it to ~/.hermes/.env. Read the entry’s manifest before you install it, since an install can run setup commands. GitHub is deliberately not in the catalog; the Hermes documentation points to its bundled GitHub skills and the gh command line tool instead (see Hermes Agent skills).

Filtering tools, with filesystem, GitHub and database examples

Some servers expose dozens of tools, and a few of them delete or overwrite things. Each server entry has a tools block that decides what the agent sees:

• include is an allowlist: only these tools are registered.
• exclude is a blocklist: everything except these.
• If both are present, include wins.
• Entries can be glob patterns, such as *_dns_*; entries without wildcards match the exact name only.
• resources: false and prompts: false switch off the resource and prompt wrappers.

An include list of exact tool names keeps newly added server tools hidden. Glob patterns also admit new tools that match. Choosing to select tools during hermes mcp add writes an include list. hermes mcp configure can update an existing exclude list or remove filtering when all tools are selected, so inspect the saved configuration if you need a fixed allowlist.

Filesystem. The example in the Hermes documentation limits the server to one folder. The server can only reach the directory you pass as the last argument:

mcp_servers:
  project_fs:
    command: "npx"
    args: ["-y", "@modelcontextprotocol/server-filesystem", "/home/user/my-project"]

GitHub. The documentation’s issue-management setup exposes three tools and nothing else:

mcp_servers:
  github:
    command: "npx"
    args: ["-y", "@modelcontextprotocol/server-github"]
    env:
      GITHUB_PERSONAL_ACCESS_TOKEN: "${GITHUB_TOKEN}"
    tools:
      include: [list_issues, create_issue, update_issue]
      prompts: false
      resources: false

The package names above are the ones the Hermes documentation uses; check each package’s own page for its current state and tool names before relying on it, and give the token only the repository permissions the job needs.

A database. The Hermes catalog includes Neon, a hosted Postgres service, as a remote server that signs in with OAuth. Its manifest points at https://mcp.neon.tech/mcp and leaves out a set of documentation and logging tools by default. Install it with:

hermes mcp install neon

For a database of your own, use the server your database vendor documents, as a stdio or HTTP entry in the same shape. Whatever you pick, connect it with a read-only database user where you can, and use exclude or include to keep write tools away from the model unless you need them. The filter limits what the agent can call; it does not replace the database’s own permissions.

OAuth for remote servers, and timeouts

Many hosted MCP servers use OAuth 2.1 rather than a fixed token. Set auth: oauth on the entry and Hermes handles the sign-in, token exchange and refresh:

mcp_servers:
  linear:
    url: "https://mcp.linear.app/mcp"
    auth: oauth

On first connect Hermes prints an authorise link, opens your browser when it can, and waits for the redirect on a local port. Tokens are stored under ~/.hermes/mcp-tokens/, one file per server, readable only by your user. Run hermes mcp login <server> from a terminal for interactive OAuth authorisation. Normal discovery uses connect_timeout, which defaults to 60 seconds; explicit login allows the greater of connect_timeout and oauth.timeout plus 15 seconds.

When the browser is on another machine (Hermes on a server, you on a laptop), the redirect cannot reach Hermes. The options in the docs: paste the final redirect URL back into the prompt; use the device-code flow with hermes mcp login <server> --flow device, which needs no browser on the host if the server supports it; or forward the port over SSH. If a vendor does not allow automatic client registration, register your own OAuth app and give Hermes its client_id and client_secret under an oauth: block.

Timeouts. Four numbers are worth knowing, all set on the server entry:

• timeout: how long one tool call may run, in seconds. The default is 300.
• connect_timeout: how long the first connection may take. The default is 60.
• oauth.timeout: how long to wait for you to approve a sign-in. The default is 300 seconds.
• idle_timeout_seconds: stops a stdio server after that many seconds without a tool call; it starts again on the next call. It suits memory-hungry servers; the Hermes docs use it for a browser one.

A browser automation server is a common case. The Hermes documentation shows the Playwright server recycled so its Chromium does not stay in memory all day:

mcp_servers:
  playwright:
    command: "npx"
    args: ["-y", "@playwright/mcp@latest", "--headless"]
    idle_timeout_seconds: 900
    max_lifetime_seconds: 86400

Its tools stay registered while it is stopped, and it starts again on the next call. Hermes also has its own built-in browser tools, so add Playwright only if you want that specific tool set.

Troubleshooting: server not connecting, tools missing

Work through these in order.

• Run the test. hermes mcp test <name> shows whether the connection works and why not. For some HTTP failures it also reports the status, request URL and a response-body excerpt. For a 401 or 403, check the credentials and access permissions; use hermes mcp login <name> only for an OAuth-configured server. A 400 or 405 can indicate a transport mismatch; check whether the endpoint requires transport: sse. An HTML response can indicate a website URL or an intermediary error page.
• Check the command exists. For a stdio server, run node --version and npx --version. If the message says the executable is missing, install it or put its full path in command.
• Read the startup summary. Hermes logs which servers failed to register, with the error for each, in agent.log. To capture HTTP endpoint details, set logging.level: DEBUG in config.yaml, restart Hermes and reproduce the failure, then inspect the records with hermes logs --level DEBUG.
• Tools not appearing. Likely causes are a failed connection, a filter that excluded them, or enabled: false on the server.
• A secret is missing. If a ${NAME} reference remains unresolved, check that NAME has a non-empty value in the active Hermes environment or its .env file. Missing or empty values leave the literal placeholder unchanged. For stdio servers, explicitly list required variables under env unless they already come from the inherited baseline or a configured external secret source.
• Changes not taking effect. Run /reload-mcp or start a new session. A server that failed to connect is retried automatically in a running gateway once you fix the cause.

By default, Hermes connects to at most four servers concurrently; mcp.discovery_concurrency changes this limit, and 0 removes it, so a long list can take a little while at startup. If you run Hermes around the clock in a container, the same configuration applies; see Hermes Agent in Docker for where the data directory lives.

Hermes as an MCP server

Hermes can also be the server. Running hermes mcp serve starts a stdio MCP server that lets another MCP client, such as a coding agent or an editor, work with your Hermes conversations. The client starts and stops the process, so you add it to that client’s own MCP settings:

{
  "mcpServers": {
    "hermes": {
      "command": "hermes",
      "args": ["mcp", "serve"]
    }
  }
}

It exposes ten tools, all about messaging rather than general Hermes abilities:

• conversations_list, conversation_get and messages_read to browse conversations and history;
• attachments_fetch for non-text attachments on a message;
• events_poll and events_wait to watch for new events;
• messages_send and channels_list to send to a connected chat platform and list the places it can send to;
• permissions_list_open and permissions_respond are registered, but this version does not populate pending gateway approvals or forward decisions to the gateway; do not rely on them to approve actions.

Reading stored conversations works without a running gateway. Sending requires the target platform’s credentials and delivery backend; some platforms support standalone sending, while others require a running adapter or bridge. messages_send accepts a message string, whose supported media references can also trigger attachment delivery. The MCP server uses stdio and has no HTTP mode. Add --verbose for debug output.

MCP on ReadyHermes

ReadyHermes has no screen for adding your own MCP servers. If SSH access is enabled under Bot tools you can administer the assistant by hand, but the supported ways to connect it to other software are the ones below. If you need arbitrary MCP servers, running Hermes yourself gives you that control, and the comparison of self-hosting and managed hosting lays out the trade.

What ReadyHermes does offer for connecting your agent to other software:

• Apps. In the workspace, the Apps panel lets your assistant read and act in the apps you use, such as Gmail, Google Calendar and Notion. You sign in to each app yourself and can disconnect it at any time. The public apps directory lists over 1,000 apps; the Apps panel offers the ones that support this kind of sign-in.
• Tools catalog. Under Bot tools, a Tools catalog lists tools you can install on your assistant. For some entries you connect your own service by entering its HTTPS address and a credential. A few of those services speak MCP. They are used through a helper that ReadyHermes installs, not through the mcp_servers list described above, and the assistant has to be running when you connect one.
• Skills. Browse reusable skills for your agent; the guide to Hermes Agent skills explains how they work.

Your own Hermes Agent runs on our servers and stays on, with the AI model included, so the apps you connect keep working while your computer is off. To see what the service includes, read about managed Hermes Agent hosting.