Skip to content

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.

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.

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.

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.

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
  • Only one serve can 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: serve keeps waiting, whoami lists the account’s devices under waiting_for_device_removal, and a device_limit_reached event 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.