hermes-platform-mcp

A thin MCP bridge that connects Hermes Agent (Nous Research) to the Hermes Intelligence Platform learning API (/api/v1/agent/*). It owns no data — every tool call is forwarded over HTTP to the platform.

Why this exists

The Signal Scout cron agents used to only write_file markdown briefs into the vault and read nothing back at runtime. This bridge gives agents first-class tools to pull the live learning loop (context pack, feedback, examples, memory), push structured findings (signal_submit, memory_save), and answer questions about platform data (signals_get, briefs_get, analytics_get) — the last three power the platform's /chat.

Where this fits

flowchart LR
    Gw["Hermes Gateway :8642\n(always-on)"] -->|"spawns per session\n(3 mcp_servers entries)"| Bridge
    Cron["Cron jobs\n(Reddit / X scouts)"] -.->|via gateway| Gw
    subgraph Bridge["hermes-platform-mcp (this repo)"]
        Srv["server.mjs\none stdio process per session"]
    end
    Bridge -->|"HTTP, Bearer hip_...\n/api/v1/agent/*"| Platform["Hermes Intelligence Platform\n:3050"]

    classDef gateway fill:#AB47BC,stroke:#6A1B9A,color:#ffffff,stroke-width:2px;
    classDef bridge fill:#26A69A,stroke:#00695C,color:#ffffff,stroke-width:2px;
    classDef platform fill:#42A5F5,stroke:#1565C0,color:#ffffff,stroke-width:2px;
    classDef agent fill:#7E57C2,stroke:#4527A0,color:#ffffff,stroke-width:2px;

    class Gw gateway;
    class Srv bridge;
    class Platform platform;
    class Cron agent;

It owns no state and runs no daemon: every process is spawned fresh, bound to one agent identity for its lifetime, and torn down when the session ends.

Transport & auth model

stdio. Hermes Agent spawns one node server.mjs process per session and tears it down when the session ends — there is no standing daemon. Because stdio has no per-request headers, each process is bound to one agent identity via env vars:

• HIP_API_KEY — the agent's hip_ key (forwarded as the platform bearer; the platform resolves identity + per-agent scoping from it). Required.
• HIP_PLATFORM — default platform slug (reddit / x) so tool calls can omit it.
• HIP_BASE_URL — platform base URL (default http://localhost:3050).

So two agents = two mcp_servers entries, each launching the server with its own key (see hermes-config-snippet.yaml).

Tools

Tool	Loop stage	Maps to
ping	—	GET /ping
context_pack_get	read	GET /context-pack
feedback_get	read	GET /feedback
examples_get	read	GET /examples
memory_search	read	GET /memory
signals_get	read	GET /signals
briefs_get	read	GET /briefs
analytics_get	read	GET /analytics
memory_save	write	POST /memory
signal_submit	write	POST /signals
brief_submit	write	POST /briefs
signal_status_update	write	PATCH /signals

Each mcp_servers entry picks its subset via tools.include — the chat entry (hermes_platform) gets reads + memory_save + signal_status_update; the scout entries (hermes_reddit, hermes_x) get reads + signal_submit + memory_save.

A tool call, end to end

%%{init: {'theme':'base', 'themeVariables': {'primaryColor':'#42A5F5','primaryTextColor':'#ffffff','primaryBorderColor':'#1565C0','lineColor':'#5C6BC0','secondaryColor':'#AB47BC','secondaryTextColor':'#ffffff','secondaryBorderColor':'#6A1B9A','tertiaryColor':'#FFCA28','tertiaryTextColor':'#000000','tertiaryBorderColor':'#F57F17','actorBkg':'#42A5F5','actorBorder':'#1565C0','actorTextColor':'#ffffff','actorLineColor':'#5C6BC0','signalColor':'#333333','signalTextColor':'#000000','labelBoxBkgColor':'#FFCA28','labelBoxBorderColor':'#F57F17','labelTextColor':'#000000','noteBkgColor':'#FFF59D','noteBorderColor':'#F9A825','noteTextColor':'#000000','activationBorderColor':'#26A69A','activationBkgColor':'#B2DFDB','sequenceNumberColor':'#000000'}}}%%
sequenceDiagram
    participant Ag as Hermes Agent
    participant Sv as server.mjs (this process)
    participant Pl as Platform :3050

    Ag->>Sv: call tool "signal_submit" {title, external_url, pain_md, ...}
    Sv->>Sv: platformFetch(): attach Bearer HIP_API_KEY,\ndefault platform to HIP_PLATFORM
    Sv->>Pl: POST /api/v1/agent/signals\n(15s timeout via AbortSignal)
    Pl-->>Sv: 201 {id, deduped}
    Sv-->>Ag: tool result (raw JSON passed through)

No business logic lives here — platformFetch() is the only moving part, shared by all 12 tools.

Run (manual debugging only)

Hermes launches this itself; you only run it by hand to test. It speaks MCP over stdin/stdout, so drive it by piping JSON-RPC frames:

HIP_API_KEY=hip_r_... HIP_PLATFORM=reddit ./run.sh   # then type/pipe MCP frames

The old always-on HTTP service (port 3060) and the hermes-platform-mcp.service systemd unit are no longer needed under stdio.

Connect Hermes Agent

Three stdio entries are live in ~/.hermes/config.yaml under mcp_servers: (keys in ~/.hermes/.env): hermes_reddit (HIP_REDDIT_KEY), hermes_x (HIP_X_KEY), and hermes_platform (HIP_CHAT_KEY, cross-platform, used by the platform's /chat). After config changes: /reload-mcp inside Hermes or systemctl --user reload hermes-gateway. Tools appear as mcp_hermes_reddit_* / mcp_hermes_x_* / mcp_hermes_platform_*.