# 2026-08-04 — Hermes MCP client integration: native tool surface for oikos

**Status:** Plan.
**Context:** Hermes Agent (mac-mini workstation) now connects to oikos's MCP server
as a native MCP client (`mcp_servers.oikos` in `~/.hermes/config.yaml`). All 37+ MCP
tools are available as `mcp__oikos__*` first-class Hermes tool calls — no more raw
curl with batch-initialize SSE parsing. The integration works; this plan tightens the
remaining seams.

**Trigger:** First-use retrospective identified three areas that make the integration
harder to use than it should be.

---

## 1. Motivation

The oikos MCP server (`internal/mcp/`) speaks Streamable HTTP at
`https://mcp.hubris.network/mcp`. Hermes Agent's native MCP client connects to it on
startup, discovers tools, and registers them as callable functions. This replaces the
previous pattern where agents fired raw curl requests with batch `initialize` +
`tools/call` envelopes.

Three friction points observed:

- **No lightweight connectivity check.** The `/healthz` HTTP endpoint exists but isn't
  exposed at the MCP protocol layer. An agent that wants to verify the MCP server is
  reachable must call a real tool (e.g. `list_entities` with a limit of 1) — every call
  carries the Streamable HTTP session-initialization overhead.
- **Bearer token in plaintext.** `~/.hermes/config.yaml` stores the token directly in the
  `mcp_servers.oikos.headers.Authorization` value. Hermes does not support env-var
  interpolation in MCP server configs, so the token can't live only in `.env`.
- **Zero-visibility streaming overhead.** Streamable HTTP batches `initialize` +
  `tools/call` per request. This adds ~2KB of transport per tool call that the agent
  never sees. For a single `get_health_summary` call this is negligible; for a 10-tool
  exploration pass it's 20KB of invisible overhead.

---

## 2. Changes

### I — MCP health/ping tool (`mcp__oikos__ping`)

**Why:** Agents need a zero-cost connectivity check before calling production tools.
Currently every check incurs the full Streamable HTTP initialize + tools/call round-trip.

**What:**

Add a `ping` tool that returns `{"ok": true, "server": "oikos", "version": "dev"}`.
No arguments. No DB hit. No auth check (already protected by the MCP transport's auth
layer — the request won't arrive if the bearer token is missing).

```go
// internal/mcp/tools.go
{
  Name: "ping",
  Description: "Lightweight connectivity check. Returns immediately with server identity, no DB hit.",
  InputSchema: jsonschema.Must(nil), // no params
  Handler: func(ctx context.Context, args json.RawMessage, caller CallerInfo) (json.RawMessage, error) {
    return json.RawMessage(`{"ok":true,"server":"oikos","version":"` + version.Version + `"}`), nil
  },
}
```

**Risk class:** read-only. No auth, no DB, no state. Auto-approves.

**Test:** `hermes mcp test oikos` (from the Hermes CLI) verifies MCP server reachability
independently; the `ping` tool gives agent code the same signal programmatically.

### II — Tool name documentation in server metadata

**Why:** Hermes prefixes MCP tools as `mcp_{server}_{tool}`, so `get_health_summary`
becomes `mcp__oikos__get_health_summary`. Agents discover tool names at runtime via
`tools/list`, but there's no short summary of what each tool group does that survives
into the MCP tool description.

**What:**

Audit and tighten every tool's `Description` field in `internal/mcp/tools.go` so the
first 8–12 words are a searchable one-liner an agent can pattern-match against.
Current descriptions that are vague or redundant get a prefix rewrite:

| Tool | Current description | Revised |
|------|-------------------|---------|
| `get_entity` | "Get entity metadata" | "Look up one entity by slug or UUID — type, state, attributes, health" |
| `list_entities` | "List entities" | "Browse entities by type, state, or name substring — paginated" |
| `upsert_knowledge` | "Record what you learned" | "Write a document/investigation/runbook to the knowledge graph — idempotent" |
| `run` | "Run ANY shell command" | "Execute a shell command on any host/LXC/VM — auto-classified by risk" |

Existing tools pass through unchanged if their description is already crisp. ~15 tools
get description rewrites.

**Risk class:** read-only (config change). No runtime effect.

### III — Env-var interpolation docs for Hermes config (oikos-side documentation)

**Why:** The bearer token lives in `~/.hermes/config.yaml` in plaintext because Hermes
does not support `${VAR}` interpolation in MCP server configs. This is a Hermes
upstream feature request, not an oikos change — but oikos should document the
workaround and track the upstream ask.

**What:**

Add a `### Hermes MCP client` subsection to `docs/infrastructure/mcp-server.md` (or
create it if it doesn't exist) that covers:

1. The config block to add to `~/.hermes/config.yaml` (already done — record it
   for the next person).
2. The token exposure caveat: Hermes doesn't support env-var interpolation in
   `mcp_servers` `headers` yet (upstream issue nousresearch/hermes-agent#TODO — file
   once).
3. Workaround: `hermes config set security.redact_secrets true` (already default) so
   the token value is stripped from tool output and logs even if it appears in
   diagnostic text.
4. How to verify the connection: `hermes mcp list` → `hermes mcp test oikos`.

**Risk class:** docs-only.

---

## 3. Open questions

| Question | Decision |
|----------|----------|
| Should `ping` bypass auth entirely or still require a valid bearer token? | **Still requires auth.** The MCP transport layer validates the token before routing to `ping` — no special treatment needed. If the token is missing, the request never reaches the handler. |
| Who files the Hermes upstream feature request for `${VAR}` interpolation? | **Oikos operator** (dtoro). The need is specific to this deployment. File at https://github.com/NousResearch/hermes-agent/issues. |

---

## 4. Not doing (yet)

- **Persistent MCP sessions** — Streamable HTTP stateless mode is fine for the
  current tool-call volume (~1–5 calls per agent turn). Persistent sessions would
  save ~2KB per call but add connection lifecycle complexity. Revisit if per-turn
  tool calls exceed 20.
- **`tools/list` caching** — Hermes already caches tool discovery at session start.
  The 37-tool list is ~4KB; caching adds complexity for negligible savings.

---

## 5. Verification

1. `curl -X POST https://mcp.hubris.network/mcp ... -d '...ping...'` returns `{"ok":true,"server":"oikos","version":"dev"}`
2. `hermes mcp list` shows `ping` among oikos tools
3. `hermes doctor` passes
4. Tool descriptions are crisp: `hermes mcp list` output for oikos shows prefixed summaries