MCP server (firefly-mcp)
firefly-mcp (in the firefly
repository) lets an LLM take part in Firefly as an ordinary user. It’s a local
Model Context Protocol server on stdio: one device of the
signed-in account, built on firefly-client. It holds the
account’s keys, decrypts messages on the machine it runs on, and exposes the account’s direct
messages and groups as MCP tools.
It runs only where someone installs and starts it. There’s no hosted MCP endpoint, and the Lupyd apps don’t include or start it. To set it up for Lupyd step by step, see Agents and bots.
Install
Section titled “Install”RUSTFLAGS="--cfg mls_build_async" \
cargo install --locked --git https://github.com/lupyd/firefly firefly-mcp
RUSTFLAGS is needed because cargo install doesn’t read the repository’s
.cargo/config.toml, which enables mls-rs’s async mode.
Commands
Section titled “Commands”| Command | |
|---|---|
login --email E |
Signs in with the account’s email and password (asked for, read from stdin, or FIREFLY_MCP_PASSWORD) using the Auth0 password-realm grant, and saves the session (owner-only permissions). The account must already have a username. |
serve |
The MCP server on stdin and stdout; logs go to stderr (RUST_LOG). What an MCP client starts. |
status |
Prints the signed-in username. |
logout |
Forgets the sign-in. The device’s keys stay, so logging in again keeps its groups. |
Exit code 78 means a person has to sign in again: a wrong password, or a revoked or expired
refresh token.
Settings
Section titled “Settings”Every flag can also be set with its environment variable.
| Flag | Environment | |
|---|---|---|
--api-url |
FIREFLY_API_URL |
Firefly HTTP API, e.g. https://firefly.lupyd.com |
--ws-url |
FIREFLY_WS_URL |
Real-time endpoint, e.g. wss://firefly.lupyd.com/ |
--wt-url |
FIREFLY_WT_URL |
WebTransport endpoint, tried first; none turns it off |
--auth0-domain |
AUTH0_DOMAIN |
The tenant the server trusts, e.g. https://auth.lupyd.com |
--auth0-client-id |
AUTH0_CLIENT_ID |
Lupyd’s public client: GnfEyGY0JdD0Oige2HSpeErcaWLrvObm |
--auth0-audience |
AUTH0_AUDIENCE |
e.g. https://lupyd.com |
--auth0-realm |
AUTH0_REALM |
Default Username-Password-Authentication |
--data-dir |
FIREFLY_MCP_DATA_DIR |
Default <user data dir>/firefly-mcp/<profile> |
--profile |
FIREFLY_MCP_PROFILE |
Default default; keeps several accounts apart |
For a self-hosted Firefly, point these at your server
and your Auth0 tenant; the client must allow the password-realm grant and offline_access.
| Tool | |
|---|---|
whoami |
The username and connection state, and the account’s devices while it waits for one to be removed |
list_conversations |
Direct conversations (latest first, with unread counts and message requests) and groups |
read_direct_messages |
A direct conversation, oldest first, with edits, deletes and reactions applied; reading the latest page marks it read |
read_group_messages |
A group channel (or all channels), the same way |
get_group |
A group’s channels, roles and members |
wait_for_events |
Long-polls for new messages and group changes; call it in a loop, passing next_after_seq back |
send_direct_message, send_group_message |
Send, optionally as a reply (reply_to) |
edit_message, delete_message |
The account’s own messages |
react |
An emoji on any message; an empty one takes it back |
search_messages |
Full-text search over the messages on this device |
respond_to_message_request |
Accept or decline a message request (replying also accepts) |
create_group, create_channel, add_group_member, remove_group_member, leave_group, create_join_link, join_group_via_link |
Groups and membership, as far as the group’s permissions allow |
Message ids are the server’s time in microseconds. Attachments show as a count; their contents aren’t available.
Events
Section titled “Events”wait_for_events returns events with an increasing seq:
type |
|
|---|---|
direct |
A direct message, edit, delete or reaction from someone (kind: message, edit, delete, reaction, call) |
group |
The same in a group channel |
added_to_group |
The account was added to a group |
members_changed |
People joined or left a group |
group_updated |
A group’s name, channels, roles or settings changed |
device_limit_reached |
The account already has five devices; this one waits until one is removed |
signed_out |
The sign-in ended or this device was removed; run login again |
The device
Section titled “The device”- Only one
servecan run per data directory; a second one refuses to start. - An account has at most five devices, and this is one of them. When the account is full, the
server doesn’t add it and doesn’t sign another device out:
servekeeps waiting,whoamilists the account’s devices underwaiting_for_device_removal, and adevice_limit_reachedevent says so. Once a device is removed it connects by itself. - The LLM sees whatever the account can read, and what it reads goes to whichever model runs it. Other members can see the account but not where its model runs.