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 can store a project-scoped server definition while leaving the key in the environment:

terminal

$ 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)

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

Discovery for clients that look before they connect: the server card (v1 Server Card schema — transport URL, the Bearer header it needs, supported protocol versions) is served at /.well-known/mcp/server-card.json, /.well-known/mcp-server-card, and /mcp/server-card; the api-catalog links it, and /llms.txt says when to reach for the server at all. An unauthenticated call answers 401 with a WWW-Authenticate: Bearer challenge, and every authenticated response carries the same RateLimit headers as the REST API.

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

41 tools — full parity with the /v1 REST API, email, SMS, and webhook capture, 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 →