Documentation/AI agents & assistants/MCP server

MailFlat MCP server: an inbox for any AI client

Run the MailFlat MCP server and any Model Context Protocol client gains real inbox tools: open an address, wait for the one-time code, send mail, clean up.

How it fits together

MCP is how a model gets tools: the client starts a small server process, asks it what it can do, and the model calls those tools by name. The MailFlat server exposes seven of them, so a model can open an inbox, read the code that arrives in it, and delete the inbox again — without you writing a polling loop or handing it your dashboard password.

The tools

Everything the server can do. The Vercel AI SDK suite exposes the same seven; the LangChain toolkit leaves out delete_message.

Tool	Arguments	What it does
create_inbox	prefix? · label? · retention_hours?	Opens a real inbox and returns its address.
list_inboxes	—	Every inbox this API key can see.
read_messages	address	All messages in an inbox, newest first.
wait_for_otp	address · timeout?	Polls until a one-time code arrives, then returns it.
send_email	address · to · subject? · body? · html?	Sends a DKIM-signed email from the inbox.
delete_inbox	address	Deletes the inbox and every message in it.
delete_message	address · message_id	Deletes one message; the inbox itself stays.

Run the server

The server talks over stdio, so you normally never start it by hand — the client does. Running it once yourself is still the fastest way to prove the key works.

Shell

# zero-install, isolated (recommended)
MAILFLAT_API_KEY=mf_live_... uvx mailflat-mcp
 
# or install it once
pipx install mailflat-mcp
MAILFLAT_API_KEY=mf_live_... mailflat-mcp

uvx ships with uv (brew install uv). Either way the server needs Python 3.10 or newer.

Point a client at it

Every MCP client reads a config file with this shape. Only the file location differs — see the Claude Desktop and Cursor pages for exact paths.

JSON

{
  "mcpServers": {
    "mailflat": {
      "command": "uvx",
      "args": ["mailflat-mcp"],
      "env": { "MAILFLAT_API_KEY": "mf_live_..." }
    }
  }
}

Your own domain, or a self-hosted API

MAILFLAT_API_URL moves every tool call to another origin. Bring-your-own-domain inboxes do not need it — those already live on mailflat.net.

JSON

{
  "mcpServers": {
    "mailflat": {
      "command": "uvx",
      "args": ["mailflat-mcp"],
      "env": {
        "MAILFLAT_API_KEY": "mf_live_...",
        "MAILFLAT_API_URL": "https://mail.example.com"
      }
    }
  }
}

When a tool call fails, check the key first

This is the same credential the server uses. If curl works and the client does not, the problem is the client's config, not MailFlat.

Shell

curl -s https://mailflat.net/api/v1/inboxes \
  -H "X-API-Key: $MAILFLAT_API_KEY"

401 means the key is wrong or revoked. An empty list means the key is fine and simply has no inboxes yet.

Worth knowing

An end-to-end encrypted inbox cannot hand over a code. The server never sees the plaintext, so wait_for_otp returns an error instead of a number. Give agents a normal inbox and keep encryption for the mail you read yourself.

retention_hours is capped by your plan. Asking for 720 hours on the free plan gives you the free plan's ceiling, not an error — so an agent cannot quietly buy itself more storage.

The key is account-wide. Anything you hand it to can list and delete every inbox that key can see, so give the agent its own key and rotate it from Agents when the experiment is over.