Oleksandr Kuzmenko, EditorPublished 5 min readAI-assisted · editor-reviewed
TL;DR
- Install @moemail/mcp via stdio to give Claude Code and Cursor disposable email verification capabilities.
- Design MCP tools to return waiting states and polling timeouts as structured data rather than throwing exceptions.
- Use moemail skill install to auto-configure the create-wait-read-delete loop in Codex and Claude Code.
Key facts
- MCP Tools Registered
- 8 tools
- Blocking Timeout Window
- Up to 90 seconds
- Package License
- MIT
- Self-Host Infrastructure
- Cloudflare Workers
Source: Key facts — MCP Tools Registered
Source: Key facts. MCP Tools Registered: 8 tools. Each figure is copied from the story.
- MCP Tools Registered8 tools
Overcoming the Agent Inbox Bottleneck
Autonomous testing agents in Claude Code, Cursor, and Codex frequently fail during registration workflows because they lack access to an email inbox. The open-source @moemail/mcp package bridges this gap by running an MCP server locally over stdio via npx, requiring zero persistent background infrastructure.
Tool Primitives and Blocking Timeouts
The server exposes eight core tools: create_email, wait_for_email, list_messages, read_message, list_emails, send_email, delete_message, and delete_email. The critical primitive is wait_for_email, which blocks for up to 90 seconds while polling the inbox. Crucially, if no email arrives before the limit expires, the tool returns a { status: 'timeout' } payload rather than throwing an exception. Returning expected waiting states as data prevents LLMs from hallucinating errors or abandoning the run prematurely.
Integration with Claude Code and Codex
For interactive workflows, developers can install the tool directly into Claude Code using claude mcp add moemail -e MOEMAIL_API_KEY=... -- npx -y @moemail/mcp. For automated continuous integration pipelines, the @moemail/cli package supports structured --json output and auto-detects skill installations for both Claude Code and Codex via moemail skill install.
Try it in 2 minutes
claude mcp add moemail -e MOEMAIL_API_KEY=mk_live_key -- npx -y @moemail/mcpWhen to use
- Automating end-to-end integration and staging tests for signup and password-reset flows.
- Running headless CI checks that require disposable account creation.
When NOT to use
- Mass account registration or abusive free-tier farming against third-party platforms.
- Production transactional email delivery requiring permanent mailbox persistence.
What to do today
- Add the @moemail/mcp server to your Claude Code or Cursor configuration.
- Run moemail skill install to register the disposable inbox workflow in Codex or Claude Code.
- Refactor custom agent tools to return pending or timeout states as JSON objects instead of runtime exceptions.
Step names are taken from What to do today.
Step names are taken from What to do today. Add the @moemail/mcp server to your Claude Code or Cursor configuration.. Run moemail skill install to register the disposable inbox workflow in Codex or Claude Code.. Refactor custom agent tools to return pending or timeout states as JSON objects instead of runtime exceptions.
- Add the @moemail/mcp server to your Claude Code or Cursor configuration.
- Run moemail skill install to register the disposable inbox workflow in Codex or Claude Code.
- Refactor custom agent tools to return pending or timeout states as JSON objects instead of runtime exceptions.
