MCP (Model Context Protocol) in Hermes Agent: Connecting External Tool Servers

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

mcp_servers:
  company_api:
    url: "https://mcp.internal.example.com"
    headers:
      Authorization: "Bearer ***"

hermes mcp          # interactive picker (default)
hermes mcp catalog  # plain-text list, scriptable
hermes mcp install n8n  # install a catalog entry by name

n8n            available     Manage and inspect n8n workflows from Hermes
linear         enabled       Linear issue/project management (remote OAuth)
github         installed (disabled)  GitHub repo + PR tools

Select tools for 'linear' (SPACE toggle, ENTER confirm)
[x] find_issues         Find issues matching a query
[x] get_issue           Get a single issue
[x] create_issue        Create a new issue
[ ] delete_workspace    Delete a Linear workspace
...

hermes mcp configure linear

# Add Codex CLI as an MCP server in one line
hermes mcp add codex --preset codex

mcp_servers:
  codex:
    command: "codex"
    args: ["mcp-server"]

mcp_servers:
  internal_api:
    url: "https://mcp.internal.example.com/mcp"
    client_cert: "~/.certs/mcp-client.pem"

mcp_servers:
  internal_api:
    url: "https://mcp.internal.example.com/mcp"
    client_cert: ["~/.certs/mcp-client.crt", "~/.certs/mcp-client.key"]

mcp_servers:
  internal_api:
    url: "https://mcp.internal.example.com/mcp"
    client_cert: ["~/.certs/mcp-client.crt", "~/.certs/mcp-client.key", "${MCP_KEY_PASSWORD}"]

How It Works

Architecture and Transport

Hermes Agent supports two kinds of MCP servers: stdio servers and HTTP servers.

Stdio servers run as local subprocesses and talk over stdin/stdout. The documentation recommends using stdio servers when:

• the server is installed locally
• you want low-latency access to local resources
• you are following MCP server docs that show command, args, and env

HTTP servers are remote endpoints Hermes connects to directly. The documentation recommends using HTTP servers when:

• the MCP server is hosted elsewhere
• your organization exposes internal MCP endpoints
• you do not want Hermes spawning a local subprocess for that integration

Tool Registration and Naming

Hermes prefixes MCP tools so they do not collide with built-in names. The pattern is:

mcp_<server_name>_<tool_name>

Examples from the documentation:

Server	MCP tool	Registered name
filesystem	read_file	mcp_filesystem_read_file
github	create-issue	mcp_github_create_issue
my-api	query.data	mcp_my_api_query_data

In practice, you usually do not need to call the prefixed name manually, Hermes sees the tool and chooses it during normal reasoning.

Utility Tools for Resources and Prompts

When supported, Hermes also registers utility tools around MCP resources and prompts:

• list_resources
• read_resource
• list_prompts
• get_prompt

These are registered per server with the same prefix pattern, for example: mcp_github_list_resources, mcp_github_get_prompt.

These utility tools are now capability-aware:

• Hermes only registers resource utilities if the MCP session actually supports resource operations.
• Hermes only registers prompt utilities if the MCP session actually supports prompt operations.

So a server that exposes callable tools but no resources/prompts will not get those extra wrappers.

Discovery Time

Hermes discovers MCP servers at startup and registers their tools into the normal tool registry.

Dynamic Tool Discovery

MCP servers can notify Hermes when their available tools change at runtime by sending a notifications/tools/list_changed notification. When Hermes receives this notification, it automatically re-fetches the server's tool list and updates the registry, no manual /reload-mcp required. This is useful for MCP servers whose capabilities change dynamically (e.g., a server that adds tools when a new database schema is loaded, or removes tools when a service goes offline). The refresh is lock-protected so rapid-fire notifications from the same server don't cause overlapping refreshes. Prompt and resource change notifications (prompts/list_changed, resources/list_changed) are received but not yet acted on.

Reloading

If you change MCP config, use:

/reload-mcp

This reloads MCP servers from config and refreshes the available tool list. For runtime tool changes pushed by the server itself, see Dynamic Tool Discovery above.

Toolsets

Each configured MCP server also creates a runtime toolset when it contributes at least one registered tool:

mcp-<server_name>

That makes MCP servers easier to reason about at the toolset level.

OAuth Flow for HTTP Servers

Most hosted MCP servers (Linear, Sentry, Atlassian, Asana, Figma, Stripe, and others) require OAuth 2.1 instead of a static bearer token. Set auth: oauth and Hermes handles discovery, dynamic client registration, PKCE, token exchange, refresh, and step-up auth via the MCP Python SDK.

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

On first connect, Hermes prints an authorize URL, opens your browser when possible, and waits for the OAuth callback on a local loopback port. Tokens are cached at ~/.hermes/mcp-tokens/<server_name>.json with 0o600 perms; subsequent runs reuse them silently until refresh fails.

Remote / Headless Hosts

When Hermes runs on a different machine than your browser, the loopback callback can't reach your laptop. The documentation provides two ways to complete the flow:

1. Paste-back (no setup): on an interactive terminal Hermes prints "Or paste the redirect URL here…" alongside the authorize URL. Open the URL in your browser, approve, copy the full URL the browser ends up on (the redirect will show a connection error, that's expected), paste it at the prompt. Bare ?code=...&state=... query strings work too.

2. SSH port forward: ssh -N -L <local_port>:127.0.0.1:<remote_port> user@host in a separate terminal, then let the redirect flow normally.

3. Proxied callback (redirect_uri): when a public HTTPS endpoint forwards to the host (e.g., a Tailscale Funnel or reverse proxy pointed at the callback port), set oauth.redirect_uri and the browser redirect reaches Hermes on its own, no tunnel or paste needed:

mcp_servers:
  myserver:
    url: "https://mcp.example.com/mcp"
    auth: oauth
    oauth:
      redirect_port: 8765  # fixed port for the proxy to target
      redirect_uri: "https://oauth.example.ts.net/callback"

For fully headless gateways (messaging bot, no interactive terminal at all), the optional mcp-oauth-remote-gateway skill walks the agent through completing the flow manually and writing tokens where Hermes expects them.

Pitfall: WAF Rejects 127.0.0.1 Redirect URIs

A few providers front their authorization server with a WAF that 403s any authorize request whose query string contains a literal 127.0.0.1 (Reclaim.ai's AWS API Gateway is a known example, every attempt returns {"message":"Forbidden"} before reaching the OAuth app). Set oauth.redirect_host: localhost to use http://localhost:<port>/callback instead; the callback listener still binds 127.0.0.1 either way.

Pitfall: Providers That Don't Support Automatic Registration (Google Drive, Atlassian)

Some servers reject the dynamic client registration step (RFC 7591) that bare auth: oauth relies on, Google's official Drive server (https://drivemcp.googleapis.com/mcp/v1) returns a 400 Bad Request, so no OAuth client is created and no token is acquired. The symptom is subtle: these servers also serve tools/list without auth, so hermes mcp login can list the tools and look like it worked, but every real tool call later times out. hermes mcp login now detects this (it checks that a token actually landed on disk) and tells you to supply your own OAuth client. Create one in the provider's console and add it to config:

mcp_servers:
  googledrive:
    url: "https://drivemcp.googleapis.com/mcp/v1"
    auth: oauth
    oauth:
      client_id: "<your_client_id>"
      client_secret: "<your_client_secret>"

Then run hermes mcp login googledrive, with the pre-registered client, Hermes skips registration and runs the normal browser authorization flow.

Pitfall: Config Auto-Reload Race

When you edit ~/.hermes/config.yaml from inside a running Hermes session, the CLI auto-reloads MCP connections with a 30s timeout. That's not enough for an interactive OAuth flow. Add the entry, then run hermes mcp login <name> from a fresh terminal, it waits the full 5 minutes for you to complete auth.

Security Model

Stdio Env Filtering

For stdio servers, Hermes does not blindly pass your full shell environment. Only explicitly configured env plus a safe baseline are passed through. This reduces accidental secret leakage.

Config-Level Exposure Control

The filtering support is also a security control:

• disable dangerous tools you do not want the model to see
• expose only a minimal whitelist for a sensitive server
• disable resource/prompt wrappers when you do not want that surface exposed

Trust Model for Catalog Entries

Installing a catalog entry runs whatever the manifest specifies, git clone, the entry's bootstrap commands (pip install, npm install, etc.), and ultimately the MCP server's own code. Manifests are gated by PR review into the hermes-agent repo, so Nous has reviewed each entry before it shipped, but you should still read the manifest before installing, especially the source: field's repository, the install.bootstrap: commands, and any transport.command: invocation.

Manifests live at optional-mcps/<name>/manifest.yaml on GitHub. The picker also prints the manifest's source: URL at install time so you can quickly verify the upstream repo. The web dashboard's MCP page surfaces the same detail per catalog entry, transport, auth type, the endpoint URL (HTTP) or command + args (stdio), the git install source/ref and bootstrap commands, and setup notes, with the source: rendered as a clickable link, so you can inspect exactly what an entry connects to or runs before clicking Install.

Requirements and Limitations

Prerequisites

• Hermes Agent installed (MCP support ships with the standard install).
• For stdio servers that run via npx: Node.js and npx must be available on PATH.
• For verifying MCP dependencies: Python and uv available (cd ~/.hermes/hermes-agent && uv pip install -e ".[mcp]").

Supported Platforms

The documentation does not specify supported operating systems or architectures. The commands and paths shown (e.g., ~/.hermes/config.yaml, npx, uv) suggest Linux and macOS are primary targets. Windows is not mentioned.

Known Limitations

• Prompt and resource change notifications: prompts/list_changed and resources/list_changed notifications are received but not yet acted on. Only notifications/tools/list_changed triggers a refresh.
• Auto-reload race: The CLI auto-reloads MCP connections with a 30s timeout when you edit the config file from inside a running session. This is not enough for an interactive OAuth flow. Use a fresh terminal for hermes mcp login.
• OAuth dynamic registration failures: Some providers (Google Drive, Atlassian) reject the dynamic client registration step. You must supply your own client_id and client_secret.
• WAF blocking 127.0.0.1: Some authorization servers block redirect URIs containing 127.0.0.1. Use oauth.redirect_host: localhost as a workaround.
• Parallel tool calls are opt-in: By default, MCP tools run sequentially. You must set supports_parallel_tool_calls: true to enable concurrent execution. The documentation includes a caution: "Only enable parallel calls for servers whose tools are safe to run concurrently."
• Utility tools are capability-aware: Hermes only registers resource/prompt utility wrappers if the server session actually supports those capabilities. This is intentional.
• Empty toolset: If your config filters out all callable tools and disables or omits all supported utilities, Hermes does not create an empty runtime MCP toolset for that server.
• Catalog entries are not auto-updated: You must re-run hermes mcp install <name> to refresh after a Hermes update if a manifest version changed.

Troubleshooting

MCP Server Not Connecting

The documentation provides these checks:

# Verify MCP deps are installed (already included in standard install)
cd ~/.hermes/hermes-agent && uv pip install -e ".[mcp]"
node --version
npx --version

Then verify your config and restart Hermes.

Tools Not Appearing

Possible causes, as listed in the documentation:

• the server failed to connect
• discovery failed
• your filter config excluded the tools
• the utility capability does not exist on that server
• the server is disabled with enabled: false

If you are intentionally filtering, this is expected.

Why Didn't Resource or Prompt Utilities Appear?

Because Hermes now only registers those wrappers when both are true:

• your config allows them
• the server session actually supports the capability

This is intentional and keeps the tool list honest.

OAuth Flow Fails on Remote Host

If Hermes runs on a different machine than your browser, use the paste-back method or SSH port forwarding as described in the "Remote / Headless Hosts" section above.

OAuth Flow Times Out

If you edit the config file from inside a running Hermes session, the auto-reload has a 30s timeout. Run hermes mcp login <name> from a fresh terminal instead.

Provider Rejects Dynamic Client Registration

If you get a 400 Bad Request during OAuth setup (e.g., with Google Drive), supply your own client_id and client_secret in the config under oauth.client_id and oauth.client_secret, then run hermes mcp login <name> again.

WAF Returns 403 on Authorization Request

If you see {"message":"Forbidden"} when trying to authorize, set oauth.redirect_host: localhost in your config to use http://localhost:<port>/callback instead of 127.0.0.1.

Manifest Version Warning

If the catalog picker shows a warning like ⚠ '<name>' requires a newer Hermes, run hermes update to install the latest Hermes.

Example Use Cases

GitHub Server with a Minimal Issue-Management Surface

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

Use it like: "Show me open issues labeled bug, then draft a new issue for the flaky MCP reconnection behavior."

Stripe Server with Dangerous Actions Removed

mcp_servers:
  stripe:
    url: "https://mcp.stripe.com"
    headers:
      Authorization: "Bearer ***"
    tools:
      exclude: [delete_customer, refund_payment]

Use it like: "Look up the last 10 failed payments and summarize common failure reasons."

Filesystem Server for a Single Project Root

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

Use it like: "Inspect the project root and explain the directory layout."

Recycling Memory-Heavy Stdio Servers

Browser-based MCP servers (e.g., @playwright/mcp) keep a full Chromium resident after their first tool call, hundreds of MB that never get released. Opt in to automatic recycling and the server is torn down after the idle/lifetime limit, then restarted transparently the next time one of its tools is called (its tools stay registered the whole time):

mcp_servers:
  playwright:
    command: "npx"
    args: ["-y", "@playwright/mcp@latest", "--headless"]
    idle_timeout_seconds: 900  # recycle after 15 min without a tool call
    max_lifetime_seconds: 86400  # and at least once a day regardless

Full Configuration Example

mcp_servers:
  github:
    command: "npx"
    args: ["-y", "@modelcontextprotocol/server-github"]
    env:
      GITHUB_PERSONAL_ACCESS_TOKEN: "***"
    tools:
      include: [create_issue, list_issues, search_code]
      prompts: false
  stripe:
    url: "https://mcp.stripe.com"
    headers:
      Authorization: "Bearer ***"
    tools:
      exclude: [delete_customer]
      resources: false
  legacy:
    url: "https://mcp.legacy.internal"
    enabled: false