//Portal MCP

Portal MCP

What it is

Portal MCP is an MCP (Model Context Protocol) server hosted by Nous Portal. It lets an AI agent on your computer, such as Hermes Agent, Claude Code or Codex, manage your Hermes Cloud agents and read your usage and spend when you ask in chat.

For example, you can ask your agent: list my cloud agents, restart the stopped one, or what did I spend yesterday.

Sign in

Sign-in happens in your browser with OAuth. There is no API key to paste. Your MCP client discovers everything automatically, registers itself, opens your browser to sign you in to the Portal, and stores the token. There is no separate approval step.

If you belong to several organisations, the Portal asks which one this session manages. Each session manages one org.

Hermes Agent

hermes mcp add nous-portal --url https://portal.nousresearch.com/mcp --auth oauth

Then start Hermes, or run /reload-mcp in a running session. A browser window opens to sign you in.

The same settings in config.yaml:

mcp_servers:
  nous-portal:
    url: https://portal.nousresearch.com/mcp
    auth: oauth

Claude Code

claude mcp add --transport http nous-portal https://portal.nousresearch.com/mcp

Then run /mcp inside Claude Code to authenticate.

Codex CLI

codex mcp add nous-portal --url https://portal.nousresearch.com/mcp

Then run codex mcp login nous-portal.

Other clients

Any MCP client that supports Streamable HTTP and OAuth with a local (loopback) callback works.

Limitation: sign-in only completes to a callback on your own machine (http://localhost or http://127.0.0.1), so web-hosted connectors, for example adding Portal MCP as a custom connector on a website, and clients that use a custom-scheme callback are not supported.

If the client runs on a remote server, forward its callback port to the computer with your browser. Use the port your client listens on for the callback; some clients pick a new port each time unless you set a fixed one:

ssh -L 8765:127.0.0.1:8765 user@host

What it can do

  • agents (read): list your Hermes Cloud agents, get details, live status, cost estimate.
  • agent (change): start, stop, restart, create, destroy, rename, resize, grow disk, update env vars, update image, toggle Labs features, and reassign ownership (team owners and admins).
  • team_gateway: turn Team Gateway on or off for an agent, see which chat accounts are linked, and read or change who it answers and where (reply policy, principals, scopes, DM default) on Discord, Telegram, Slack or WhatsApp. You can also attach or detach your own linked chat accounts.
  • service_credentials (team owners and admins): create, list and revoke machine credentials, a client ID and secret exchanged for short-lived tokens via client_credentials, for scripts and backends without a browser.
  • usage (read): recent transactions, last 24 hours hourly, last 30 days daily spend.

Example prompts

  • List my cloud agents and their status.
  • Restart the agent that is stopped.
  • What did I spend yesterday?
  • Show my daily spend for the last 30 days.
  • Create an agent named research with the default size.

Permissions and safety

Everything is scoped to the one organisation this session manages, and your membership is re-checked on every call. You see the agents you can see in the Portal.

The token acts as you. It can stop or delete agents, and read usage and spend; members who can view the org's usage see all of it. Treat it like a password. There is no read-only mode.

Agent cost estimates are estimates, not invoices.

Troubleshooting

A create that times out in your client keeps going. Check the agent list by name before retrying: a retry makes a second agent.

To switch org or sign in again in Hermes, run hermes mcp login nous-portal.

More about MCP clients is in the Hermes Agent documentation.