Hermes Agent

Hermes Agent is Nous Research’s open-source AI agent CLI. Its built-in MCP client speaks Streamable HTTP directly and supports both a static bearer token and OAuth 2.1 for remote servers, so it connects to Orbismo either way. Configuration lives in ~/.hermes/config.yaml, under the mcp_servers key.

Before you start

You’ll need:

Hermes Agent installed — see the Hermes Agent docs.
To use the connector: nothing extra, you’ll sign in during setup.
To use an API key: your world’s ID (the UUID in the portal URL, https://app.orbismo.com/worlds/{world_id}/...) and a key from Generate an API key. Use a read-only key for your first connection.

The connector (recommended)

Open (or create) ~/.hermes/config.yaml and add an entry under mcp_servers:

mcp_servers:
  orbismo:
    url: "https://app.orbismo.com/api/v1/mcp"
    auth: oauth

Run the sign-in flow:
Terminal window
```
hermes mcp login orbismo
```
Sign in to Orbismo and choose which worlds this connection may access.

See The connector for how choosing a world and managing access works.

A single world with an API key

Add an entry with a static header instead of auth: oauth:

mcp_servers:
  orbismo:
    url: "https://app.orbismo.com/api/v1/worlds/<world_id>/mcp"
    headers:
      Authorization: "Bearer oc_live_<your_key>"

Replace <world_id> with your world’s UUID and oc_live_<your_key> with your full key. This pins Hermes to that one world — use a separate entry and key per world.

Verify

After editing the config, reload MCP connections with the /reload-mcp slash command inside a running Hermes session, or restart Hermes. Confirm Orbismo’s tools appear in the agent’s tool list. On a single-world URL, a missing tool usually means your access level doesn’t include it. On the connector the tool list is the same for every world. On a read-write connection, write tools stay listed even on worlds where you are a viewer, and the change is refused when the agent tries it. See Troubleshooting.

Use it in a session

Name Orbismo in your prompt so Hermes reaches for the right tools. On the connector, start by picking a world:

Use Orbismo to list my worlds, then work in "Family History".

On a single-world connection there is nothing to list, so just ask for what you want:

Use Orbismo to show me the people added most recently.

What it can do follows your role on whichever world it is working in (or the key’s permission, for an API-key connection).