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. Mailcycle can’t read the mail, the same as for any other address. AI agents are on Scale and above.
Connect an agent
Section titled “Connect an agent”- On the machine the agent runs on, run
npx -y mailcycle-mcp pair. It prints a line starting withMC1:. - In the app, open AI agents and paste the line.
- Give the agent an email address. The app seals the address’s keys for the agent and hands them over.
- Add the server to your MCP client, for example
claude mcp add mailcycle -- npx -y mailcycle-mcp.
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.
| 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. |
reply |
Replies to the sender of a message, threaded under it. |
send_message |
Sends a new message. |
Send modes
Section titled “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.
To check a reply, Mailcycle keeps a hash of each address a message to an agent could be answered at (the envelope sender, From and Reply-To), salted with the message id. The server sees these addresses as mail arrives anyway. It keeps a hash that can confirm a guess, not a list, and the hash is deleted with the message.
To send with a name, like “Support at Acme”, set Sender name on the agent’s page in the app. It is sealed into the agent’s key bundle, and the agent picks it up on its next send.
Agents send only from domains in the Scale group and up, or from a domain you brought. An address on a lower-tier shared domain returns 403 domain_not_allowed.
What sees what
Section titled “What sees what”- Mailcycle stores the agent’s mail sealed. Sent mail passes through in plain text and isn’t stored, as for all sending.
- 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. - The model provider sees whatever the agent reads.
Without MCP
Section titled “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.