Give an MCP agent its own email address

Connect your client#

Mailbay runs a remote MCP server at https://mcp.mailbay.dev/mcp (streamable HTTP). It authenticates with a Mailbay API key in the Authorization header; OAuth sign in is planned. Create a key on the API keys page of the dashboard first.

Claude Code

claude mcp add --transport http mailbay https://mcp.mailbay.dev/mcp \
  --header "Authorization: Bearer $MAILBAY_API_KEY"

Cursor and other clients with remote servers

{
  "mcpServers": {
    "mailbay": {
      "url": "https://mcp.mailbay.dev/mcp",
      "headers": { "Authorization": "Bearer mb_live_xxxxxxxxx" }
    }
  }
}

Claude Desktop and other stdio only clients

mailbay-mcp stdio is a small local process that forwards every request to the remote server with your key, so its tools and errors are always the remote ones.

{
  "mcpServers": {
    "mailbay": {
      "command": "mailbay-mcp",
      "args": ["stdio"],
      "env": { "MAILBAY_API_KEY": "mb_live_xxxxxxxxx" }
    }
  }
}

The tools#

Fifteen tools, each a thin wrapper over the same code the REST API runs:

Each description tells the model what the tool returns, which errors it can raise and which tool to call next. Errors come back as tool results with isError: true and a fix, so the agent can correct itself instead of stopping. Why we wrote them that way is in the design notes.

Try it#

Once connected, ask in plain words:

Create a Mailbay inbox called "newsletter-test", subscribe it to the newsletter
on example.com, then wait for the confirmation email and open the link in it.

The agent should make two Mailbay calls around its own browsing:

create_inbox    {"name": "newsletter-test"}
                → {"id": "ibx_…", "address": "newsletter-test@k7m3qz.mailbay.email", "created_at": "…"}

wait_for_email  {"inbox_id": "ibx_…", "after": "<created_at>", "timeout_seconds": 120}
                → {"message": {…}, "codes": [], "links": ["https://example.com/confirm?t=…"]}

For one address per task without creating inboxes, use the Catch-all: any address under your code works, and wait_for_email takes a to argument with the exact address.

Keep it contained#

• Use an inbox key for an agent that should only ever touch one inbox. Tools that reach beyond it answer insufficient_scope.
• Sending is sandboxed until you verify a domain: from mailbay.email addresses, mail only reaches your own team and the test addresses.
• Every message carries its SPF, DKIM and DMARC results and a spam flag, so you can tell the agent to ignore mail that fails them before it follows a link.
• Keys are revocable at once. The MCP server checks the key on every request, so deleting it stops the agent immediately.

Full reference: MCP docs. Building the agent in code instead of a client? Email inboxes for AI agents has the same flow over HTTP.

The MCP setup for each agent tool is on Mailbay for AI agent builders.