fabricatedemail

MCP server

An AI coding agent that is writing a sign-up test needs an email address and the message that lands in it. Rather than telling the agent how to call the HTTP API, point it at the Model Context Protocol server on the same host and let it register the address and read the mail itself.

POST https://api.fabricatedemail.com/mcp

Streamable HTTP transport. It takes the same Authorization: Bearer <api-key> as every other endpoint, with the same key rules, the same suspension 403 and the same rate limit. The server holds no session: each request is answered with a single JSON response.

Connecting a client

Most MCP clients take an HTTP endpoint and a header:

{
  "mcpServers": {
    "tempmail": {
      "type": "http",
      "url": "https://api.fabricatedemail.com/mcp",
      "headers": { "Authorization": "Bearer <api-key>" }
    }
  }
}

Use a key minted for the agent rather than the one your CI uses, so you can revoke it on its own. Revoking a key deletes the addresses it created and their mail.

The tools

Tool Arguments
create_address localPart (optional — a random one of 64 bits is generated without it), ttlSeconds (optional, null for permanent)
list_addresses —
delete_address subscriptionId
wait_for_message subscriptionId, after (optional), waitSeconds (optional, at most 30)
get_message subscriptionId, messageId
extract subscriptionId, messageId

Each tool is a thin call to the endpoint of the same name in the HTTP API contract, and answers with that endpoint's JSON response. A status the endpoint refuses with — a 404 for a mailbox that is gone, a 409 for an address another key holds — comes back as a tool error carrying the status and the error text, so the agent is told exactly what a client would be told.

extract is the one worth knowing about before the agent needs it: it returns the one-time codes and links found in a message, which is what a sign-up test is usually after. See One-time codes and links.

What does not change for an agent

The tools do what the endpoints do and nothing more. The same account caps, the same rate limit, the same 24-hour retention, and the same reasons a message may never arrive — start with Why mail might not arrive when an agent reports that it is still waiting.

Two habits are worth putting in the agent's instructions: