Lupyd.
Product Integrations

How to Connect an AI Agent to Lupyd with MCP: firefly-mcp, Claude and Custom Bots

Since Lupyd 1.1.6, an AI agent can join your chats as an ordinary, end-to-end encrypted member through firefly-mcp, a local Model Context Protocol server. Here's how it works, how to set it up with Claude Desktop or Claude Code, how to run several agents, and how to keep your chats safe.

Published: Nov 14, 2026
•
9 min read
How to Connect an AI Agent to Lupyd with MCP: firefly-mcp, Claude and Custom Bots

Since Lupyd 1.1.6 you can bring your own AI agent into Lupyd chats. The agent gets its own Lupyd account and joins as an ordinary user, through firefly-mcp: a small Model Context Protocol server that runs on your machine. It holds the agent's encryption keys and decrypts messages locally, then hands them to whatever model and MCP client you choose, such as Claude Desktop or Claude Code. People message the agent or add it to groups like anyone else, and the group's roles decide what it can do. Nothing is hosted by us, and our server never sees the messages. This guide covers how it works, the setup, and what to watch out for.

What firefly-mcp Is

MCP is an open standard that lets an AI application call tools provided by a separate program. firefly-mcp is one of those programs. It lives in crates/mcp of Firefly, our open-source (MIT) messaging engine, and is written in Rust on the same client code the Lupyd apps use.

The important design choice is that an agent is not a special kind of account. There is no bot flag, no separate bot API and no server-side integration. The agent signs up with an email, a password and a username, exactly as a person would, and firefly-mcp becomes one device of that account, just like a phone or laptop. It speaks the same Signal Protocol for direct messages and MLS for group channels as every other device. To everyone else in a chat, the agent is just another member.

That has a few consequences worth knowing up front:

  • It only sees what it's given. The agent reads direct messages sent to it and the groups people add it to. It can't read your account, your other chats or any group it isn't in.
  • Groups stay in charge. Adding, removing and limiting the agent works through the same roles and channel permissions as any member. If it lacks the permission to manage members, add_group_member fails.
  • The keys live with the agent. Messages are decrypted on the machine running firefly-mcp and stored in its data directory. Our server relays encrypted messages and sees group membership, roles and group names, as it does for any member, but not message content.

What an Agent Can Do in Lupyd

firefly-mcp exposes the account's chats as MCP tools. The model decides when to call them.

firefly-mcp tools, from the crate's README (November 2026)
Tool What it does
whoami The agent's username, connection state, and the devices to remove if its account is full
list_conversations Direct conversations with unread counts and message requests, plus the groups the agent is in
read_direct_messages A direct conversation, oldest first, with edits, deletes and reactions applied; reading the latest page marks it read
read_group_messages One group channel, or every channel the agent can see, the same way
get_group A group's channels, roles and members
wait_for_events Long-polls for new messages and group changes; a harness loops on it
send_direct_message, send_group_message Send a message, optionally as a reply
edit_message, delete_message, react Edit or delete the agent's own messages, or react to any message
search_messages Full-text search over the messages stored on the agent's machine
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, only as far as the group's permissions allow

Two limits for now: attachments show up as a count only, so the agent can't open files people send it, and message ids are the server's timestamp in microseconds, which matters if you write your own harness around the tools.

Some things people use this for: a support or FAQ agent that answers direct messages, a team assistant in a project group that summarises a channel when asked, an agent that searches old discussions for a decision, or a personal assistant only you message.

Before You Start

  • A separate Lupyd account for the agent. Sign it up in the app or at app.lupyd.com with an email and password, and pick a username that makes it obvious it's an agent, such as acme_assistant. Don't run an agent on your personal account: it would see everything you see.
  • Rust, from rustup.rs, to build firefly-mcp. There's no prebuilt binary yet.
  • An MCP client. Claude Desktop and Claude Code are used below, but any client or agent framework that can start a stdio MCP server works.

Step 1: Install firefly-mcp

cargo install --git https://github.com/lupyd/firefly firefly-mcp

This builds the latest version from GitHub and puts firefly-mcp on your PATH (in ~/.cargo/bin). The first build takes a few minutes.

Firefly isn't tied to one server, so firefly-mcp needs to be told which one to use. These are Lupyd's endpoints and sign-in settings. Set them in your shell for the next step:

export FIREFLY_API_URL=https://firefly.lupyd.com
export FIREFLY_WS_URL=wss://firefly.lupyd.com/
export AUTH0_DOMAIN=https://auth.lupyd.com
export AUTH0_CLIENT_ID=GnfEyGY0JdD0Oige2HSpeErcaWLrvObm
export AUTH0_AUDIENCE=https://lupyd.com

Internally we ship the same program preconfigured with these values as lupyd-mcp. Every firefly-mcp command and flag below works the same way there.

Step 2: Sign the Agent In Once

firefly-mcp login --email helper@example.com   # asks for the password
firefly-mcp status                              # prints the agent's username

Log in with the agent's email and password, not your own. For scripts, FIREFLY_MCP_PASSWORD supplies the password without a prompt. The sign-in is saved in the agent's data directory with owner-only permissions and renews itself, so you only do this once.

Step 3: Connect Claude Desktop or Claude Code

Claude Desktop. Add a server to claude_desktop_config.json (Settings, Developer, Edit Config), then restart the app:

{
  "mcpServers": {
    "lupyd": {
      "command": "firefly-mcp",
      "args": ["serve"],
      "env": {
        "FIREFLY_API_URL": "https://firefly.lupyd.com",
        "FIREFLY_WS_URL": "wss://firefly.lupyd.com/",
        "AUTH0_DOMAIN": "https://auth.lupyd.com",
        "AUTH0_CLIENT_ID": "GnfEyGY0JdD0Oige2HSpeErcaWLrvObm",
        "AUTH0_AUDIENCE": "https://lupyd.com"
      }
    }
  }
}

If Claude Desktop can't find the command, put the full path in command, for example /home/you/.cargo/bin/firefly-mcp.

Claude Code. One command registers it:

claude mcp add lupyd \
  -e FIREFLY_API_URL=https://firefly.lupyd.com \
  -e FIREFLY_WS_URL=wss://firefly.lupyd.com/ \
  -e AUTH0_DOMAIN=https://auth.lupyd.com \
  -e AUTH0_CLIENT_ID=GnfEyGY0JdD0Oige2HSpeErcaWLrvObm \
  -e AUTH0_AUDIENCE=https://lupyd.com \
  -- firefly-mcp serve

Anything else. Any client that launches stdio servers needs the same two things: the command firefly-mcp serve and the five environment variables. Logs go to stderr, so they won't corrupt the MCP stream; raise detail with RUST_LOG=debug.

Step 4: Talk to Your Agent

From your own Lupyd account, search for the agent's username and send it a message, or add it to a group from the group's member settings. Then, in Claude, try:

  • "Check my Lupyd conversations and reply to anything unread."
  • "Read the last day of the #planning channel in the Launch group and post a summary there."
  • "Search my Lupyd messages for what we decided about the pricing page."

A desktop chat client only acts when you ask it to. For an agent that answers on its own, run it in a harness that keeps a loop going: call wait_for_events, which waits for new messages and group changes, act on what arrives, then call it again with the next_after_seq value it returned. Claude Code in headless mode, the Claude Agent SDK or your own script around an MCP client all work for this.

Running Several Agents on One Machine

Each agent needs its own account and its own data directory. Use a profile name (or --data-dir) on both login and serve:

firefly-mcp --profile support login --email support-bot@example.com
firefly-mcp --profile notes   login --email notes-bot@example.com

# each MCP client entry then runs its own profile
firefly-mcp --profile support serve

Only one serve can run per data directory; a second one refuses to start, because two copies sharing the same keys would break their encryption sessions.

Keeping the Agent and Your Chats Safe

  • The data directory is the agent. It holds the device keys and the decrypted messages. Keep it private and back it up. If it's lost, the account comes back as a new device and has to be added to its groups again. logout forgets the sign-in but keeps the keys.
  • Messages go to the model you choose. End-to-end encryption protects messages until they reach the agent's machine. After that, whatever the agent reads is sent to the model behind your MCP client: a cloud API, or a local model if you run one. People in your groups can see the agent's account, but not where its model runs. Tell them.
  • Give it the least it needs. Add the agent only to the groups and channels it should read, and use roles so it can't manage members unless that's its job. See roles and channel permissions for how that works.
  • Watch for prompt injection. Anyone who can message the agent can try to instruct it. Keep a human approving tool calls that send, delete or change membership until you trust the setup.
  • It counts as a device. An account can have at most five devices, and firefly-mcp is one of the agent's. If the agent's account is full, serve doesn't sign another device out: it waits, whoami lists the devices under waiting_for_device_removal, and it connects once you remove one in Settings, Devices.

Exit code 78 means the agent must sign in again (a changed password, or a revoked or expired session). Run login again; the keys stay, so the agent keeps its groups.

Writing Your Own Bot in Code

MCP is the right choice when an LLM drives the agent. For a bot with fixed behaviour, such as commands, reminders or welcome messages, Firefly also ships a TypeScript bot framework that runs on Bun over the same encryption client compiled to WebAssembly. Handlers look like other chat bot frameworks:

  • bot.command("remind", handler) for slash commands in direct messages and groups, with ctx.reply() to answer
  • bot.onMemberJoin(handler) to react when people join a group
  • state kept in a local SQLite file, sign-in renewal while running, and a runner that restarts bots and rotates their logs

The repository has two working examples, a greetings bot that welcomes new group members and a self-hosted reminder bot, plus a setup guide covering accounts, first sign-in, systemd and backups. Code bots sign in once through a browser, like most command-line tools: the bot listens on a free port on 127.0.0.1, and after you log in as the bot, Lupyd's redirector sends the one-time code back to that port. The code only works with a secret the bot generated when it started the sign-in (PKCE), so it's useless anywhere else. On a server, set FIREFLY_AUTH_PORT and forward that port over SSH. After that first sign-in the bot renews its own session.

Frequently Asked Questions

Can I add an AI assistant to Lupyd chats?

Yes. Since Lupyd 1.1.6, an AI agent can join Lupyd as an ordinary user through firefly-mcp, a local MCP server. You give the agent its own account, connect firefly-mcp to an MCP client such as Claude Desktop or Claude Code, and then message the agent or add it to groups like anyone else.

Does connecting an AI agent break end-to-end encryption?

Not between devices. The agent is a member with its own keys, and messages are encrypted all the way to the machine running firefly-mcp. But the agent decrypts what it can read and sends it to the model behind its MCP client, so those messages are only as private as that model provider. People in the group should know an agent is there.

Can the agent read all my chats?

No. The agent has its own account, so it only sees direct messages sent to it and groups it has been added to, within the permissions its role allows. Don't run firefly-mcp on your personal account, since it would then see everything you can.

Which AI models and apps work with firefly-mcp?

Any MCP client that can start a local stdio server, including Claude Desktop, Claude Code and agent frameworks with MCP support. firefly-mcp doesn't choose or call a model itself; the client and the model behind it decide what to read and send.

Is there a hosted Lupyd MCP server?

No. firefly-mcp always runs on your own machine as one device of the agent's account, and keeps its keys and decrypted messages in a local data directory. Lupyd's server only relays encrypted messages, as it does for every device.

Try It

Create an account for your agent, install firefly-mcp, and add it to a test group before you trust it with a real one. If you're new to Lupyd, download Lupyd for desktop or Android, or use it on the web. To learn more about the engine underneath, read introducing Firefly and libsignal vs MLS. If you're weighing the privacy side of AI in chats more generally, see AI and your chats. Lupyd is young and hasn't had an external security audit yet.

Sources & References

Last updated: 14 November 2026.

Key Takeaways
  • ✓ firefly-mcp is a local MCP server in the open-source Firefly repository that signs an AI agent in to Lupyd as an ordinary user, one device of the agent's own account.
  • ✓ There's no special bot account or hosted integration: the agent's keys and decrypted messages stay on the machine running firefly-mcp, and Lupyd's server never sees message content.
  • ✓ Setup is three steps: install with cargo, run firefly-mcp login once with the agent's email and password, and point Claude Desktop, Claude Code or any stdio MCP client at firefly-mcp serve.
  • ✓ The agent sees only direct messages sent to it and groups it's added to, and group roles decide what it can do; what it reads goes to whichever model you connect, so tell your group.
  • ✓ For bots with fixed behaviour, Firefly also includes a TypeScript bot framework with greetings and reminder bot examples; bots sign in once through a browser and renew their own session.
Try Lupyd

The workspace where nothing leaks

End-to-end encrypted channels and chat for your team, built on the Signal Protocol and MLS. Available on macOS, Windows, Linux and Android.

Open Source

Explore Lupyd on GitHub

Inspect our open-source repositories, cryptography libraries, and client tools on GitHub.

Explore Lupyd on GitHub