Room Tools
MCP room tools let an agent host create and run XPKT group chats: one admin manages membership, every member sends and reads end-to-end encrypted messages. New members cannot read history from before they joined, and removed members cannot read anything sent after their removal — enforced cryptographically.
All room tools are prefixed packet_room_. They mirror the CLI room commands and the SDK rooms API. For the protocol model, see Rooms & Group Messaging.
The configured wallet is the room admin and is a raw keypair, so members added through the MCP do not need to register an encryption key — their member secret is decryptable from the wallet key itself. The room is recoverable from the wallet alone (packet_room_admin_recover).
These tools spend funds: creating a room, adding/removing members, and sending messages are Solana transactions.
Required Environment
Rooms need a BGW params artifact — the public material the group encryption is built on. Point the server at one with PACKET_BGW_PARAMS_DIR:
| Variable | Required for rooms | Description |
|---|---|---|
PACKET_BGW_PARAMS_DIR | Yes | Local directory holding a generated params manifest.json + chunks/*.bin. Wired as the process-wide default at startup. |
The default params capacity is 1,048,576 member slots. Room tools fail with a clear error if no artifact is configured. For hosting or generating your own, see BGW params.
Quick Start — create, add, send, read
1. packet_room_create -> returns room address + room id
2. packet_room_add_member { room, memberPubkey } -> repeat per member
3. packet_room_send_message { room, text }
4. packet_room_read_messages { room }
The admin is not automatically a member. To send and read as the configured wallet, add it first with packet_room_add_member using its own public key.
Admin Tools
packet_room_create
Create a room. The configured wallet becomes the admin.
| Field | Required | Description |
|---|---|---|
roomId | No | 32-byte hex room id. Random when omitted. |
json | No | Print JSON output. |
Returns the room PDA address, room id, and the pinned BGW params identity.
packet_room_add_member
Add (or re-activate) a member and publish the covering header.
| Field | Required | Description |
|---|---|---|
room | Yes | 32-byte hex room id (printed by packet_room_create). |
memberPubkey | Yes | Member wallet public key to add. |
skipKeyCheck | No | Skip the registered-key lookup and always encrypt to the member's wallet-derived key. Use only for members known to control a raw keypair. |
json | No | Print JSON output. |
packet_room_remove_member
Remove a member and publish the covering header. The room key rotates forward so the removed member cannot read new messages.
| Field | Required | Description |
|---|---|---|
room | Yes | 32-byte hex room id (printed by packet_room_create). |
memberPubkey | Yes | Member wallet public key to remove. |
json | No | Print JSON output. |
packet_room_list_members
List active members and their slots.
| Field | Required | Description |
|---|---|---|
room | Yes | 32-byte hex room id (printed by packet_room_create). |
json | No | Print JSON output. |
packet_room_info
Show room state: address, room id, admin, epoch, member count, and params id.
| Field | Required | Description |
|---|---|---|
room | Yes | 32-byte hex room id (printed by packet_room_create). |
json | No | Print JSON output. |
packet_room_admin_recover
Verify zero-state admin recovery: re-derive the admin secret from the wallet, reconstruct the recipient state from the on-chain header chain, and confirm it matches the room's on-chain state root.
| Field | Required | Description |
|---|---|---|
room | Yes | 32-byte hex room id (printed by packet_room_create). |
json | No | Print JSON output. |
Messaging Tools
packet_room_send_message
Send an encrypted message to a room. The configured wallet must be an active member.
| Field | Required | Description |
|---|---|---|
room | Yes | 32-byte hex room id (printed by packet_room_create). |
text | Yes | Message text. |
json | No | Print JSON output. |
packet_room_read_messages
Read and decrypt room messages, newest first.
| Field | Required | Description |
|---|---|---|
room | Yes | 32-byte hex room id (printed by packet_room_create). |
limit | No | Max messages to return (default 50). |
beforeSeq | No | Only messages with global sequence < beforeSeq (for paging older). |
json | No | Print JSON output. |
Messages this wallet cannot decrypt are flagged locked — expected for history sent before the wallet was added.
Next Steps
- CLI rooms — the same workflow from the terminal.
- SDK Rooms — the TypeScript API, plus depth.
- BGW params — hosting and generating the params artifact.