mailfixture ships a remote MCP server at https://mailfixture.com/mcp. Point an agent at it — Claude Code, or any client that speaks Streamable HTTP — and it can create real inboxes, trigger your app's email flows, and read the OTP back by itself. Nothing to install, no glue code to write.

1 · Get a key

Create a key in Dashboard → API keys. The agent authenticates with a normal mfx_ key — same permissions as the REST API, revocable any time. Give agents their own key (label it mcp-agent) so you can pull it without breaking your test suites.

.env / CI secretcopy

MAILFIXTURE_API_KEY=mfx_••••••••••••••••••••

2 · Connect a client

Claude Code can store a project-scoped server definition while leaving the key in the environment:

terminalcopy

$ claude mcp add --transport http mailfixture --scope project https://mailfixture.com/mcp
--header 'Authorization: Bearer ${MAILFIXTURE_API_KEY}'

The single quotes are deliberate: the project config keeps an environment placeholder instead of expanding and writing the secret into .mcp.json. Other clients use the same Streamable HTTP shape, but their environment-variable syntax and top-level key vary; this generic example uses the same placeholder convention:

mcp config (generic)copy

{ "mcpServers": { "mailfixture": { "type": "http", "url": "https://mailfixture.com/mcp", "headers": { "Authorization": "Bearer ${MAILFIXTURE_API_KEY}" } } } }

3 · Let the agent test your email flow

That's the whole setup. Ask the agent to exercise a signup flow and it chains the tools itself:

agent transcript

Sign up a fresh account on staging and verify the OTP email works.

create_inbox(ttl_seconds=900) → k2x9v04qtr@mxsink.sh … agent drives the signup form with that address … wait_for_otp(inbox_id=…, timeout_seconds=45) → { message_id: "…", best: "482913", candidates: […] } … agent submits the code, asserts the account is verified …

tip wait_for_otp, wait_for_link, and wait_for_message long-poll on the server (up to 60s per call) — the agent never writes a sleep-and-retry loop. Racing emails? They take the same match filter as the REST API: subject:, from:, to:.

The tool surface

34 tools — full parity with the /v1 REST API, email and SMS, plus the wait helpers. The high-traffic ones:

create_inbox

A fresh address for the flow under test; optional TTL cleans up after crashed runs.

wait_for_otp

Block until a message with an extracted verification code arrives; returns {message_id, best, candidates}.

wait_for_link

Same, for links — filter by class: verify, reset, unsubscribe.

follow_link

Server-side click of an extracted link (the verify link by default): we GET it, chase redirects, and return status + final URL — no browser needed.

wait_for_message

Block until a matching message arrives; returns full detail with bodies and extraction.

list_messages / get_message

Cursor-based listing and full detail — headers, bodies, attachments metadata.

create_phone_number / wait_for_sms_otp

The same loop for texts (paid plans, US numbers): provision, use list_phone_numbers until status is active, then block for the code. See the SMS quickstart.

…and the rest

Inbox clear/delete, SMS listing + release, attachments (base64 ≤1 MiB), custom domains with DNS verification, API keys, webhooks.

Scope and security

The MCP server is the API — the key is the only credential, and everything the agent does is attributable to it. Three things to know: the tool set includes account administration (keys, domains, webhooks), so treat the key like the secret it is; message bodies flow into the agent's context, so don't point production traffic at inboxes an agent reads; and errors come back structured (status/title/detail, same vocabulary as the REST API) so agents can react instead of guessing.

Next steps

OTP with Playwright + MCP

Agent hands now, frozen Playwright suite for CI.

Quickstart: Playwright

The same flow from a test suite.

AI agents & email

Why the inbox belongs in the agent's toolbox.

Was this page useful? yes no Guide: OTP with Playwright + MCP →

ON THIS PAGE

1 · Get a key 2 · Connect a client 3 · Let the agent test The tool surface Scope and security

edit this page ↗
report an issue ↗