Hermes Agent integration

Hermes is an open-source agent framework by Nous Research with full MCP support. Oka Reason works as a standard stdio MCP server.

Setup

1. Add to your Hermes config

Edit ~/.hermes/config.yaml:

mcp_servers:
  oka:
    command: "npx"
    args: ["-y", "@oka-core/reason"]

2. Authenticate

In a Hermes session, use the login tool. This opens your browser to id.oka.so where you sign in or create an account. Your credentials are stored locally and refresh automatically.

CI/CD or headless?

Add OKA_API_KEY to the env section. See API key auth.

3. Verify the connection

Start a Hermes session. Oka’s 19 tools should be discovered automatically.

Hermes-specific features

Bidirectional MCP

Hermes can both connect to MCP servers and act as an MCP server. This means you can chain Hermes with Oka: Hermes agents use Oka’s tools, and other MCP clients can use Hermes as an intermediary.

Runtime tool discovery

Hermes supports MCP’s notifications/tools/list_changed — if @oka-core/reason adds new tools in a future version, Hermes auto-refreshes without requiring a restart.

Tool filtering

Restrict which Oka tools Hermes can use:

mcp_servers:
  oka:
    command: "npx"
    args: ["-y", "@oka-core/reason"]
    tools:
      - context
      - observe
      - decision
      - done

Timeouts

mcp_servers:
  oka:
    command: "npx"
    args: ["-y", "@oka-core/reason"]
    timeout: 30

Tips

• Hermes does not pass your full shell environment to MCP servers. If using API key auth, always set OKA_API_KEY explicitly in the env block.
• Use enabled: false to temporarily disable Oka without removing the configuration.
• Hermes supports MCP sampling (sampling/createMessage) — advanced workflows can have MCP servers request LLM inference from the Hermes agent itself.