hyperhive/docs/tools/matrix.md

Matrix MCP tools and extra MCP servers

Built-in matrix MCP (mcp__matrix__*)

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" and a teaser body ([matrix] <sender> in <room>: <first-100c>…).

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.