# Connect Hermes

> Give Hermes a secure connection to your shared context.

## 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](/docs/account) for initial owner setup.

Hermes supports remote MCP endpoints with a bearer credential. For manual setup, first [issue a contributor token](/docs/authentication), then merge this block into the active Hermes profile’s `config.yaml`:

```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

```sh
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:

```json
{
  "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

| Response | What to check |
| --- | --- |
| 401 | The bearer token is missing, invalid, rotated, or revoked. |
| 403 | Check HTTPS and, for a browser-based request, the allowed origin. |
| 405 on GET | Expected. Use the POST MCP endpoint and `skip_preflight`. |
| 413 | Reduce the request body below 64 KiB. |
| 429 | Wait for the `Retry-After` interval before retrying. |
| Creation tool missing | Confirm the agent has the contributor role and reload its tools. |

The live Forge-to-Hermes connection remains an acceptance check for the first milestone. See the official [Hermes MCP configuration reference](https://hermes-agent.nousresearch.com/docs/reference/mcp-config-reference/) for client-specific settings.