Getting started / quickstart-mcp

Quickstart: MCP agents

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 secret

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

2 · Connect a client

Claude Code is one command:

terminal

$ claude mcp add --transport http mailfixture https://mailfixture.com/mcp \
    --header "Authorization: Bearer $MAILFIXTURE_API_KEY"

Any other MCP client takes the same shape — a Streamable HTTP server with a bearer header:

mcp config (generic)

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

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)
  → { best: "482913" }   # held open server-side, returns when mail lands
… 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 the code.

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 a dedicated number, block until the code arrives — one tool call each. 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

Testing OTP flows

Why long-polling beats sleeps, in depth.

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: Testing OTP flows →