AI agents

An AI agent can have its own Mailcycle addresses. It reads and replies to mail through mailcycle-mcp, an MCP server that runs next to the agent and decrypts on that machine. Mail is sealed the moment it arrives, and Mailcycle can’t open it after that, the same as for any other address. AI agents are on Scale and above.

Connect an agent

1. On the machine the agent runs on, run npx -y mailcycle-mcp pair. It prints a line starting with MC1:.
2. In the app, open AI agents and paste the line.
3. Give the agent an email address. The app seals the address’s keys for the agent and hands them over.
4. Add the server to your MCP client. See MCP clients.

The pasted line carries the key the agent’s address keys are sealed with. It goes from your terminal to the app and never through Mailcycle, so the key handover is end to end. A line without that key is refused.

MCP clients

Every client runs the same local server, on the machine where you ran pair.

Claude Code

claude mcp add mailcycle -- npx -y mailcycle-mcp

Codex

codex mcp add mailcycle -- npx -y mailcycle-mcp

VS Code

code --add-mcp '{"name":"mailcycle","command":"npx","args":["-y","mailcycle-mcp"]}'

Cursor, Claude Desktop and other clients

Add this to the client’s MCP config: ~/.cursor/mcp.json for Cursor, claude_desktop_config.json for Claude Desktop.

{
  "mcpServers": {
    "mailcycle": {
      "command": "npx",
      "args": ["-y", "mailcycle-mcp"]
    }
  }
}

Tools

Tool	What it does
list_addresses	The agent’s addresses, and what it may send.
list_messages	The newest messages, with a preview of each.
read_message	One message in full.
wait_for_message	Waits for new mail, optionally filtered by sender or subject.
read_attachment	Opens one attachment of a message.
reply	Replies to the sender of a message, threaded under it. Can attach files.
send_message	Sends a new message. Can attach files.

read_message lists attachments by number, name, type and size. read_attachment returns a text file as text and an image as an image. Other files, like PDFs, need save_to, a folder inside the agent’s files folder: the file is decrypted and written there, on the machine running the agent, and the tool returns the path. It never overwrites a file. To attach files to reply or send_message, pass their paths in attachments: up to 10, 3.5 MB between them. Program and script files are never attached.

The files folder is ~/.config/mailcycle/files, or the folders named in MAILCYCLE_FILES_DIR, separated as in PATH. The agent cannot read or write files anywhere else, so mail asking it to attach a private file cannot reach one. Put files there for the agent to send. Needs mailcycle-mcp 0.4.1 or later.

npx -y mailcycle-mcp status shows the agent’s addresses and send mode. To run more than one agent on a machine, give each its own key file with MAILCYCLE_AGENT_FILE.

While it runs, the MCP server checks in every five minutes, and every request it makes counts as activity, so the app shows the agent as online.

Send modes

Every agent has a send mode, set on its page in the app:

Mode	What the agent can send
Reply only	Replies to whoever wrote a message it received. The default.
Send to anyone	Any address, up to 20 messages an hour per agent.
Read only	Nothing.

Mail an agent reads can contain instructions written by whoever sent it. Reply only limits what those instructions can make it do. Only a signed-in session can change the mode. An API key can’t.

In reply-only mode, an agent can answer only addresses the message it names was authenticated from: the From address if the message passed DMARC, the envelope sender if it passed SPF, and a Reply-To on one of those domains. A message that passed neither cannot be answered.

To send with a name, like “Support at Acme”, set Sender name on the address (Email addresses, then Manage, then Edit address), or on the agent’s page for every address it holds. An address’s own name wins. Both are sealed into the agent’s key bundle, and the agent picks them up on its next send.

Agents send only from the addresses assigned to them, on a shared domain or one you brought, within the plan’s daily sending limit.

What sees what

• Mailcycle stores the agent’s mail sealed. Sent mail passes through in plain text, as for all sending, and the copy in the address’s Sent folder is sealed to its key, marked sentVia: "agent".
• The machine running the agent keeps its key in ~/.config/mailcycle/agent.json. Anyone with that file can read the agent’s mail. Removing the agent in the app revokes its credential, and the MCP server deletes the file the next time the server refuses it, so pairing again needs no --force.
• The model provider sees whatever the agent reads.

Without MCP

An agent is a paired device with platform: "agent", so the device endpoints are what the MCP server calls. GET /workers/messages takes after (a message id) or since (a time) to list what arrived since, oldest first, and wait (up to 25 seconds) to hold the request open until something does. Pass the response’s nextCursor back as after to carry on.