# 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

### 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`](../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.