Connect Hermes

Configure the connection

The easiest route is to sign in at /account, choose Connect an agent, select View and edit, and follow the generated connection steps. See Your account & agents for initial owner setup.

Hermes supports remote MCP endpoints with a bearer credential. For manual setup, first issue a contributor token, then merge this block into the active Hermes profile’s config.yaml:

mcp_servers:
  orbit:
    url: "https://YOUR_ORBIT_DOMAIN/mcp/orbit"
    headers:
      Authorization: "Bearer ${ORBIT_MCP_TOKEN}"
    skip_preflight: true
    tools:
      include:
        - workspace_context
        - contacts_search
        - contacts_get
        - contacts_create
        - contacts_update
        - contacts_archive
        - contacts_restore
        - tags_list
        - fields_list
        - activity_append
        - organisations_archive
        - projects_archive
        - tasks_archive
        - contacts_brief
        - organisations_create
        - projects_create
        - tasks_create
        - organisations_get
        - projects_get
        - tasks_get
        - activity_link
        - activity_list
        - affiliations_list
        - participants_list
        - projects_brief
        - affiliations_remove
        - participants_remove
        - organisations_restore
        - projects_restore
        - tasks_restore
        - organisations_search
        - projects_search
        - tasks_search
        - affiliations_set
        - participants_set
        - organisations_update
        - projects_update
        - tasks_update
        - tasks_claim
        - tasks_claim_renew
        - tasks_claim_release
        - tasks_complete
        - tasks_attempts
      resources: false
      prompts: false

Replace the domain with your real endpoint. Save ORBIT_MCP_TOKEN in the active profile’s secret source, normally ~/.hermes/.env. Keep the credential out of prompts and version control.

skip_preflight avoids rejecting Laravel MCP’s intentional 405 response to GET or HEAD requests. MCP calls use POST. Keep TLS certificate verification enabled.

Check your tools

hermes mcp test orbit

Start a new Hermes session or use /reload-mcp. A contributor should see all 43 tools. A reader sees 17 read-only tools: discovery, search/get, relationship/activity lists, and briefs. Tool discovery is paginated by MCP; clients must follow nextCursor to collect the full inventory. When upgrading, update this allowlist and reload MCP so the new tools are available.

Ask Hermes to call workspace_context and confirm the workspace name and permission level before adding data.

Create your first contact

Search for a unique test name first. Then ask Hermes to call contacts_create with:

{
  "display_name": "Orbit connection test",
  "idempotency_key": "hermes-connection-test-1"
}

Save the returned contact ID. Close the session, reconnect, and retrieve it using contacts_get. The ID and the stored record should be unchanged.

Repeat the original creation with exactly the same arguments. It should return the original record with replayed: true. This confirms that retrying a creation does not add another contact.

Troubleshooting

The live Forge-to-Hermes connection remains an acceptance check for the first milestone. See the official Hermes MCP configuration reference for client-specific settings.