website/docs/guides/manage-hermes-cloud-with-mcp.md
Hermes Cloud runs hosted Hermes Agent instances for you. Normally you manage them from the /agents page in the Nous Portal. This guide connects your local Hermes Agent to the Portal's MCP server so you can manage those cloud instances by just asking — "list my cloud agents", "restart the stopped one", "what's it costing me" — without leaving your terminal.
It's a standard MCP server hosted by Nous Research, gated by the same OAuth login you already use for the Portal. Once connected, Hermes gets two tools it can call on your behalf.
Once connected, the model can call these on your Hermes Cloud org:
| Ask for… | Under the hood |
|---|---|
| "List my cloud agents" | agents (list) |
"What's the status of <name>?" | agents (get / status) |
| "Roughly what is this instance costing?" | agents (cost_estimate) |
"Start / stop / restart <name>" | agent (start / stop / restart) |
"Spin up a new instance called <name>" | agent (create) |
"Destroy <name>" | agent (destroy) |
"Update the env / image on <name>" | agent (update_env / update_image) |
Every call runs against your org with your Portal identity, and membership is re-checked on each call — the connection can only touch instances you already control from the web UI.
A Nous Portal account with Hermes Cloud access (at least one instance, or the ability to create one).
MCP support installed. If you used the standard install script it's already there; otherwise:
cd ~/.hermes/hermes-agent
uv pip install -e ".[mcp]"
You do not need a separate API key or client secret — the server uses OAuth with PKCE, and the login is a browser round-trip.
hermes mcp add --url https://portal.nousresearch.com/mcp --auth oauth hermes-cloud
--auth oauth tells Hermes this is an OAuth-protected HTTP server. On first connect Hermes:
~/.hermes/mcp-tokens/ and reuses it (refresh is automatic).If your Portal account belongs to more than one organization, the browser shows an org picker during authorization — pick which org this connection should manage. The choice is made once, in the browser; there's nothing to pass on the command line. Single-org accounts skip this step and bind automatically.
If you ever need to point the connection at a different org, remove and re-add the server (hermes mcp remove hermes-cloud, then the add command again) and pick the other org in the browser.
hermes mcp test hermes-cloud
Then start (or reload) a session:
hermes chat
/reload-mcp
Ask a read-only question to confirm the tools are live:
List my Hermes Cloud agents and their current status.
You should get back the same instances you see on the Portal's /agents page.
Read-only questions are always safe:
Which of my cloud agents is currently running, and roughly what is each one costing?
Lifecycle actions map to plain requests:
Restart the instance called research-bot.
Create a new Hermes Cloud instance named scratch, then tell me when it's ready.
Hermes reports what each tool returned — the instance list, the new status, the created instance's details — so you can confirm the action landed.
After hermes mcp add, the server lives in ~/.hermes/config.yaml:
mcp_servers:
hermes-cloud:
url: "https://portal.nousresearch.com/mcp"
auth: oauth
No credentials go in config.yaml — the OAuth token is kept separately under ~/.hermes/mcp-tokens/, the same way the Portal refresh token stays out of your config.
The server exposes both read (agents) and mutating (agent) tools. If you want the connection to be read-only — list and inspect, but never start/stop/create/destroy — restrict it to the agents tool:
mcp_servers:
hermes-cloud:
url: "https://portal.nousresearch.com/mcp"
auth: oauth
tools:
include: [agents]
Run /reload-mcp after changing the config. See Use MCP with Hermes for the full filtering model (include/exclude, prompts, resources).
You belong to multiple Portal organizations. Pick the org whose Hermes Cloud instances you want to manage from this connection. If you're unsure, it's the org that owns the instances you see on the Portal /agents page. You can re-choose later by removing and re-adding the server.
The stored client registration no longer matches the server (for example, you connected to a different environment previously). Clear this server's cached OAuth state and re-add it:
hermes mcp remove hermes-cloud
rm -f ~/.hermes/mcp-tokens/hermes-cloud.*
hermes mcp add --url https://portal.nousresearch.com/mcp --auth oauth hermes-cloud
Reload MCP inside the session and re-check:
/reload-mcp
Tell me which MCP-backed tools are available right now.
If they're still missing, run hermes mcp test hermes-cloud to see the connection error directly.
OAuth tokens refresh automatically, but if the Portal invalidates your session (password change, revoke, expiry) the next call asks you to re-authorize. Re-run the hermes mcp add command — the browser flow re-mints a token.
The OAuth browser callback runs on the machine where Hermes is running. On a remote host, forward the loopback port over SSH — the same pattern as any other OAuth login. See OAuth over SSH / Remote Hosts.
mcp_servers field, including auth: oauth