Home › Connect › Hermes Agent

Connect Hermes Agent to an MCP gateway — two lines of YAML

Hermes Agent (Nous Research) ships a full OAuth 2.1 MCP client: dynamic client registration, PKCE, token refresh — all automatic. The config is the shortest of any client on this site.

TL;DR

# ~/.hermes/config.yaml
mcp_servers:
  cortex:
    url: "https://mcp.cortex-gateway.dev/mcp"
    auth: oauth

On first connect, Hermes prints an authorize URL and opens your browser. Sign in, approve — done.

Steps

Declare the gateway in ~/.hermes/config.yaml under mcp_servers (block above — replace the URL with your own gateway's /mcp endpoint). If Hermes is running, reload with /reload-mcp.
Complete the OAuth flow: Hermes handles discovery and Dynamic Client Registration against the gateway's authorization server, then waits for the callback on a local loopback port. On the public demo, sign in with a magic link (first sign-in creates your account) and approve the consent screen.
Verify: ask Hermes to call the gateway's whoami tool — identity, scopes, and the health of every federated backend in one response. Tokens live in ~/.hermes/mcp-tokens/cortex.json and refresh silently.

Headless / remote machines

No local browser? Two supported options:

Paste-back: open the printed authorize URL anywhere, then paste the redirect URL back at the Hermes prompt.
SSH port forwarding: tunnel the loopback callback port — ssh -N -L <port>:127.0.0.1:<port> host.

Note on Dynamic Client Registration

Cortex Gateway's demo authorization server accepts DCR (RFC 7591), so the minimal two-line config just works. If you self-host against an authorization server that rejects automatic registration, create the OAuth client manually and add it to the block:

mcp_servers:
  cortex:
    url: "https://mcp.your-domain.com/mcp"
    auth: oauth
    oauth:
      client_id: "<your-id>"
      client_secret: "<your-secret>"

Then run hermes mcp login cortex.

Why this pairing works well

Hermes is a messaging-native agent that acts on your behalf across platforms — the sharpest case for user-level permissions. Behind a gateway, everything it does is bound to your OAuth identity: backends apply your rights, the audit trail shows what the agent did as you, and one revocation cuts it all.

Deploying Hermes for a company rather than for yourself? The default shared-VPS install fails the four questions access audits ask — see Hermes Agent in a company: what an auditor will ask (ISO 27001, SOC 2, GDPR, and the installer's checklist).

Troubleshooting

Symptom	Likely cause
Authorize URL printed but flow never completes	Loopback callback blocked (headless host) — use paste-back or SSH forwarding above.
401 on every call after weeks	Refresh failed (grant revoked or rotated away). Delete `~/.hermes/mcp-tokens/cortex.json` and reconnect.
Fewer tools than expected	Scope filtering at the gateway — `whoami` shows your grants.

Self-hosting your own gateway: github.com/wellknownmcp/cortex-gateway.