Get access

Agent clients · 27 / 42

Hermes Agent

Connect Hermes Agent to Northsun with an environment-backed header, verify prefixed MCP tools, and remove the connection or replace an exposed key.

Hermes Agent can load Northsun as a remote HTTP MCP server from ~/.hermes/config.yaml. Reference NORTHSUN_API_KEY in the authorization header, reload the MCP configuration, test the server, and verify one read-only tool. This is protocol interoperability with Hermes Agent, not a Nous Research partnership or a promise of native product support.

Prerequisites

  • A current Hermes Agent installation with MCP support.
  • A Northsun API key stored as NORTHSUN_API_KEY in Hermes's environment or ~/.hermes/.env.
  • A controlled caller already present in the target Northsun tenant.
# ~/.hermes/.env
NORTHSUN_API_KEY=...

Hermes resolves ${VAR} placeholders in remote MCP URLs and headers when it connects. Keep the real value out of config.yaml.

Configure Northsun

Add this block to ~/.hermes/config.yaml:

mcp_servers:
  northsun:
    url: "https://mcp.northsun.ai/mcp"
    headers:
      Authorization: "Bearer ${NORTHSUN_API_KEY}"
    enabled: true
    tools:
      include:
        - caller_lookup
        - recall_and_enrich
        - calls_end
      resources: false
      prompts: false

The allowlist starts with the stable caller-memory tools. Remove the include block only after you have inspected the broader contact and governed-context schemas and intentionally want them available.

Reload a running Hermes session with:

/reload-mcp

Verify the connection

Test and list the server from a terminal:

hermes mcp test northsun
hermes mcp list

Hermes prefixes server-native tools as mcp_<server>_<tool>. For this configuration, verify mcp_northsun_caller_lookup, then call it with a controlled test number. A successful protocol test plus an authenticated read proves more than tool discovery alone.

Common failures

SymptomLikely causeFix
${NORTHSUN_API_KEY} resolves emptyHermes did not load the expected environment or .env fileRestart Hermes from the correct environment and test again.
401 unauthorizedMissing or invalid bearer keyCheck environment loading without printing the secret; if exposure is possible, ask us to revoke it through the contact page, naming the last six characters of the key.
Test succeeds but expected tools are absentThe tools.include list excludes them or the server schema changedRun hermes mcp configure northsun or update the allowlist after reviewing live discovery.
Tool names look unfamiliarHermes prefixes and sanitizes MCP tool namesUse mcp_northsun_<tool> in Hermes while keeping original names in the include list.
Connection times outNetwork path or initial handshake is failingCheck remote connectivity, then adjust connect_timeout only after confirming the endpoint and auth.

Remove the connection or replace the key

Remove the server with:

hermes mcp remove northsun

Delete the corresponding key from ~/.hermes/.env only if no other approved client uses it. If the value was exposed, ask us to revoke it through the contact page, naming the last six characters of the key first, replace the environment value with the key you are issued, and restart Hermes. Local removal alone does not invalidate the credential.

Stable and beta boundaries

The three frozen public REST endpoints remain defined in the API reference. The MCP server also exposes evolving contact and governed-context tools. Re-run discovery before widening the Hermes allowlist. The connection does not imply Beacon, proactive delivery, or cross-session behavior beyond the tools you explicitly observe and call.

This guide is based on Hermes Agent's public MCP configuration contract. It does not claim catalog inclusion, certification, partnership, endorsement, or support from Nous Research.

Related links