Matrix MCP tools and extra MCP servers

Built-in matrix MCP (`mcpmatrix*`)

When hyperhive.matrix.enable = true and the host-level matrix tuwunel is configured, the harness auto-injects hive-matrix-mcp as a second stdio MCP server. Tools land as mcp__matrix__<name>:

Messaging

send_message(room, body) — send a markdown message; room accepts !id:server or #alias:server, daemon resolves either
send_dm(user_id, body) — send a direct message to a matrix user
send_reply(room, event_id, body) — threaded reply to a specific event
send_reaction(room, event_id, key) — react to a message with an emoji key

Reading

read_room(room, limit?) — recent timeline events
list_rooms() — enumerate joined rooms ({ id, canonical_alias, name, member_count } per room)
list_room_members(room) — members of a room

Room membership

invite_user(room, user_id) — invite @user:server into a room you're already in; you must have a high enough power level. The invitee sees a pending invite and accepts via join_room.
join_room(room) — join a room by id or alias, or accept a pending invite.
list_invites() — rooms this agent has been invited to but not yet joined ({ id, canonical_alias, name } per room).

Receipts

mark_read(room, event_id) — advance the read receipt

Architecture

The daemon (hive-matrix-daemon) holds the long-running matrix-sdk Client + sync loop; the stdio bridge (hive-matrix-mcp) is spawned per turn and forwards tool calls over /run/hive-matrix.sock. Both silently exit when <state>/matrix-token is absent (account not yet provisioned).

Incoming room events wake the agent via AgentRequest::Wake with from: "matrix". The wake body format depends on the unread state:

Single room, one message: [matrix] <sender> in <room>: <body> — use read_room to view, mark_read to clear
Single room, multiple messages: [matrix] N unread in <room> — use read_room to view, mark_read to clear
Multiple rooms: [matrix] unread messages: followed by a bulleted list (- <room>: <sender>: <body> or - <room>: N unread per room)

The same per-room breakdown is included in the UnreadMatrix entry returned by get_loose_ends so unread rooms surface in the loose-ends list between turns.

Auto-accept invites: when the daemon's sync loop receives an m.room.member invite event for the agent's own user, it immediately calls join_room_by_id and fires a wake so the agent learns about the new room. This closes the gap where invites (e.g. the hive Matrix Space created by hive-c0re on boot) would sit in the invited_rooms() list indefinitely until the agent called join_room manually.

Pending invites as loose ends: any remaining pending invites (not yet auto-accepted, e.g. delivered while the daemon was down) are written to mcp-loose-ends/matrix.json and appear in get_loose_ends output as [matrix] pending invite: <room> — use list_invites to see, join_room to accept. The file is updated atomically after each invite arrives or a room is joined.

See docs/matrix.md for the homeserver setup, provisioning flow, and federation config.

Extra MCP servers (per-agent)

Each agent's NixOS config can declare additional MCP servers via hyperhive.extraMcpServers.<key> = { command, args, env, allowedTools }. The module writes the map to /etc/hyperhive/extra-mcp.json; the harness reads it at boot and merges every entry into --mcp-config (under mcpServers.<key>) and --allowedTools (as mcp__<key>__<pattern>).

The agent's flake.nix forwards every flake input to agent.nix as the flakeInputs module arg, so external MCP-server flakes are pulled in by adding them to inputs.* and referenced as flakeInputs.<name>.packages.${pkgs.system}.default — the resolved sha lands in the agent's own flake.lock and rolls up to meta's.

allowedTools defaults to ["*"], which expands to mcp__<key>__* (every tool from that server auto-approved). Restrict to specific tool names when you want finer control.

4 KiB Raw Blame History