Give Your AI Coding Agent a Test Inbox: the Official Mailsac MCP Server

By Mailsac Engineering. Written for @mailsac/mcp 0.1.0.

AI coding agents can now build a sign-up flow in minutes. Checking that it works is still awkward: the last step happens in an inbox the agent can’t see. So the agent stops and asks you to open your email, or it marks the task done without knowing whether the confirmation email arrived, whether the link works, or whether the code is six digits or five.

The official Mailsac MCP server closes that gap. It gives any agent that speaks the Model Context Protocol (Claude Code, Cursor, VS Code, Claude Desktop and others) its own disposable test inboxes. The agent creates an address, uses it in your app, waits for the email, and reads the link or code itself.

What the agent can do

Tool	What it does
create_test_address	Makes a new unique address, such as signup-mf3k2a1b-9c41d2@mailsac.com. It can receive mail immediately; there is nothing to create first.
wait_for_email	Waits for the email to arrive (optionally matching a subject, sender or time), then returns the subject, text, every link, the link most likely to confirm, reset or log in (actionLink), and any one-time codes.
list_emails / read_email	Lists what arrived, and reads one email as text, HTML, raw source or headers.
delete_emails	Cleans up after a test.
list_domains	Shows your private domains, so the agent can use one instead of a public address.

Set it up in a minute

Create a free Mailsac account and an API key, then add the server.

Claude Code

claude mcp add mailsac -e MAILSAC_API_KEY=your-key -- npx -y @mailsac/mcp

Cursor (.cursor/mcp.json) or Claude Desktop

{
  "mcpServers": {
    "mailsac": {
      "command": "npx",
      "args": ["-y", "@mailsac/mcp"],
      "env": { "MAILSAC_API_KEY": "your-key" }
    }
  }
}

VS Code (.vscode/mcp.json)

{
  "servers": {
    "mailsac": {
      "type": "stdio",
      "command": "npx",
      "args": ["-y", "@mailsac/mcp"],
      "env": { "MAILSAC_API_KEY": "your-key" }
    }
  }
}

The documentation lists every setting, including MAILSAC_DOMAIN for private domains.

What it looks like

Ask the agent to check a flow the way a person would:

Sign up on http://localhost:3000 with a fresh test address and confirm the account by email.

The agent calls create_test_address, fills in your form, then calls wait_for_email. When the email arrives, the tool hands back something like this (from our own test run):

{
  "subject": "Confirm your Example account",
  "from": "no-reply@example.test",
  "actionLink": "https://example.test/verify?token=e2e-abc123",
  "codes": ["731905"],
  "polls": 1
}

The agent opens actionLink (or types the code), checks that the account is confirmed, and reports back, including when something is wrong: no email within a minute, a link pointing at the wrong host, or a code the form rejects. delete_emails then tidies up.

The same works for password resets, magic-link logins, invitations and two-factor codes.

Turn the check into a test

An agent’s check proves the flow works today. A test keeps it working. Once the agent has seen the email, ask it to write an end-to-end test for the flow. Our Playwright CI example shows the pattern it can follow: a unique address per test, polling with a timeout, and assertions on the link and code, in GitHub Actions and GitLab CI. For Cypress there is @mailsac/cypress, and any language can use the REST API.

Public addresses and private domains

Addresses at @mailsac.com are public: anyone who guesses the address can read the mail. They are perfect for made-up test data and need no setup, which is why the server uses them by default. For a staging environment that sends real names or data, use a private domain: your own subdomain or a zero-setup yourteam.msdc.co subdomain. Set MAILSAC_DOMAIN and every new address uses it. Mail to a private domain is visible only to your account.

What it costs

Each API call uses one Mailsac operation. wait_for_email checks every three seconds, so an email that arrives within a few seconds typically costs two to five operations, and creating an address costs nothing. The free plan includes 1,500 operations a month, enough for a few hundred agent checks; paid plans start at 25,000.

Open source

The server is MIT-licensed on GitHub and published to npm as @mailsac/mcp. Requests from it identify themselves with a Mailsac-Client: mcp header, so we can count how many people use Mailsac through AI agents. We never look at your email content for that. Issues and pull requests are welcome.