DearAgent: An MCP Server That Gives AI Agents a Self-Hosted Mailbox

DearAgent is an AI agent email API self-hosted on Cloudflare Workers, storing mail in D1 and attachments in R2. Positioned as an open-source alternative to AgentMail, it exposes a stateless Streamable HTTP MCP server through the /mcp endpoint on the Worker.

Who It's For

• Developers who want their AI agents to have real inbox capabilities: the typical flow is create an inbox, wait for a verification email, then read the verification link.
• Clear prerequisites: a Cloudflare account, a dedicated top-level domain for Cloudflare Email Routing, Node 20+ and running npx wrangler login. Receiving mail is free; only sending mail requires Workers Paid.
• The API and MCP share a single API_KEY as the sole bearer token — one key grants full permissions (single tenant), so it's not suitable for multi-user scenarios requiring fine-grained permission isolation.
• Not a good fit if: you don't own a domain, you can't accept the responsibility of self-hosted deployment and maintenance, or you need multi-tenant permission isolation. Aspects not covered by official evidence (such as data retention or deletion policies) are unknown; verify them yourself.

First Attempt in 3 Minutes

The only main path officially recommended is to clone the repository and run the interactive setup script, which automatically configures D1, R2, secrets, Email Routing/Sending, completes deployment, and creates a catch-all rule:

git clone https://github.com/panda-sandeep/dearagent && cd dearagent
npm install
npm run setup

Prerequisites: you are already logged into Cloudflare via npx wrangler login, and your domain is usable with Email Routing. The script guides you through setting the required API_KEY (you can also set it with npx wrangler secret put API_KEY); this key is the sole bearer token for both the API and MCP.

For your first call, use the low-risk read-only tool list_inboxes: configure your MCP client to point at the Worker's /mcp endpoint with the bearer key, then call list_inboxes. If it returns a list of inboxes, deployment and authentication succeeded. Note this is a self-hosted service, not a remote third-party hosted write; create_inbox writes to your own D1 database.

If you only need to receive mail, Workers Paid isn't required. Only when you're ready to call send_message should you confirm Workers Paid is enabled, because sending produces real outbound email (which cannot be revoked at the MCP layer; assess based on Email Sending's actual behavior).

Use Cases

Case 1: Let an agent complete registration verification automatically. Call create_inbox to create an inbox, enter that address in the target website's signup form, then use wait_for_message to wait for the verification email and read the verification link from the message body. This is the typical flow described by the official documentation; the tools return real email content from your own service.

Case 2: Retrieve historical mail. Call search_messages to search by keyword, or use list_threads / get_thread to view threads, get_message to read a specific message, and get_attachment to fetch attachments. These are all read-only queries over data already in your D1/R2 — useful for auditing mail your agent previously received.

The remaining tools (such as send_message, reply_to_message, forward_message, list_webhooks, create_webhook) are listed as available in the evidence, but their parameter details are not provided there — consult the repository README before use.

Usage Boundaries

• Read/write nature: list_*, get_*, search_messages, and wait_for_message are query operations; create_inbox, create_webhook, send_message, reply_to_message, and forward_message write data or trigger real outbound actions — confirm before calling.
• Credentials and data: a single API_KEY grants full access, so keep it safe; all email data lives in your own Cloudflare D1/R2.
• Side effects: sending mail requires Workers Paid and really dispatches email; the official documentation doesn't describe any recall mechanism after sending, so it cannot be treated as revocable.
• Unknowns: mail retention periods, deletion tools, and privacy handling details are not covered by the official evidence; these remain unconfirmed and do not constitute a risk-free conclusion.