Temp Mail MCP Server: Give Your AI Agent a Working Inbox in One Tool Call (2026)

If you have been building AI agents in 2026, you already know the problem: the moment your agent needs to sign up for a service, verify an email address, or receive a one-time password, the entire workflow grinds to a halt. There is no clean way to hand an LLM a working inbox, wait for an email to arrive, and extract a code — at least not without writing a pile of polling logic, retry handlers, and SMTP glue code.

That is exactly what the FreeCustom.Email MCP server (fce-mcp-server) was built to solve. It wraps our disposable email API behind three intent-driven tools that any MCP-compatible agent can call directly, including Claude Desktop, Cursor, Windsurf, Kilo, and custom agent frameworks built with LangChain or the OpenAI SDK.

This guide covers everything: what the MCP server does, how to install it, every supported tool with real examples, and the use cases where it genuinely saves hours of boilerplate.

What Is MCP and Why Does It Matter for Email Automation?

The Model Context Protocol (MCP) is an open standard originally introduced by Anthropic in November 2024 and now adopted by every major AI provider — OpenAI, Google DeepMind, Microsoft, and Amazon. MCP provides a universal interface for reading files, executing functions, and handling contextual prompts. Think of it as USB-C for AI tool integrations: one standard that every agent and every tool can speak.

MCP turns an LLM from a text-only assistant into an agent that can retrieve information, take actions, and work with real tools and applications through a consistent, universal protocol.

Before MCP, connecting an AI agent to an email inbox meant writing custom code: a function to create an inbox, a polling loop to check for new messages, a regex to extract the OTP, and error handling for timeouts and failures. You had to maintain that code every time the API changed. With an MCP server, you expose that entire workflow as a single tool call. The agent calls create_and_wait_for_otp() and gets back a JSON object with the inbox address and the code. No boilerplate, no polling, no regex.

By March 2026, all major AI providers had adopted MCP, reaching 97 million monthly downloads. Integration cost drops by 60–70% compared to custom connectors.

Installing the FreeCustom.Email MCP Server

The server ships as an npm package and runs locally via npx. You need a Growth or Enterprise API key from your API dashboard — the MCP layer is a premium feature because of the long-polling infrastructure it requires.

Claude Desktop

Add the following block to your config file at ~/Library/Application Support/Claude/claude_desktop_config.json (macOS) or %APPDATA%\Claude\claude_desktop_config.json (Windows):

{
  "mcpServers": {
    "fce-mcp": {
      "command": "npx",
      "args": ["-y", "fce-mcp-server"],
      "env": {
        "FCE_API_KEY": "your_growth_or_enterprise_key"
      }
    }
  }
}

Restart Claude Desktop. The three FCE tools appear automatically in the tool list.

Cursor

Open Settings → Features → MCP Servers → Add New MCP Server. Set type to command, name to fce-mcp, and command to npx -y fce-mcp-server. Add FCE_API_KEY as a system environment variable or pass it inline.

Windsurf

Add the same block to ~/.windsurf/mcp_config.json. Windsurf picks up the server on the next window reload.

Kilo CLI / Kilo Code

{
  "mcp": {
    "fce-mcp": {
      "type": "local",
      "command": ["npx", "-y", "fce-mcp-server"],
      "environment": { "FCE_API_KEY": "your_key" },
      "enabled": true
    }
  }
}

A Note on Claude.ai (Web)

The Claude web interface requires a remote MCP server URL (SSE transport) and cannot execute local npx commands. For browser-based use, either self-host the server on Vercel or Railway, or use the Claude Desktop app instead.

The Three Tools

get_latest_email — 2× credit cost

Retrieves the most recent email for a registered inbox address. Returns the sender, subject, plain-text body, extracted OTP (if any), and verification link.

Args: inbox (string, required)

Example response:

{
  "success": true,
  "data": {
    "id": "msg_01jqz3k4m5n6",
    "from": "noreply@github.com",
    "subject": "Your GitHub verification code",
    "date": "2026-04-03T09:55:00.000Z",
    "text": "Your code is 482931",
    "otp": "482931",
    "verificationLink": "https://github.com/verify?token=abc123"
  }
}

When to use it: Your agent already knows which inbox to check and just needs the latest message content. Useful for polling a shared test inbox in a CI script.

extract_otp — 3× credit cost

Parses the most recent email in an inbox and returns only the OTP or verification link — nothing else. No regex. No parsing. One call.

Args: inbox (string, required)

Example response:

{
  "success": true,
  "otp": "482931",
  "verification_link": "https://github.com/verify?token=abc123",
  "from": "noreply@github.com",
  "timestamp": 1743674100000
}

When to use it: Your agent already triggered the signup or verification flow and now needs to retrieve the code. Typically called after waiting for an email via the REST wait endpoint or a webhook.

create_and_wait_for_otp 🔥 — 5× credit cost

The gold feature. Creates a random inbox on a premium domain, holds the HTTP connection open using long-polling and Redis pub/sub, and returns the moment an OTP email arrives — all in a single tool call. Timeout is configurable between 10 and 60 seconds (default 45).

Args:

• domain (string, optional) — defaults to ditube.info

• timeout (number 10–60, optional) — seconds to wait before giving up

Example response:

{
  "success": true,
  "inbox": "x7k9mq2p@ditube.info",
  "otp": "847291",
  "verification_link": null,
  "from": "service@acme.com",
  "subject": "Your verification code"
}

When to use it: Any workflow where the agent needs to complete a signup or verification flow. One tool call does everything: creates the inbox, waits for the email, extracts the OTP. Your agent just uses the returned inbox for the signup form and the returned otp for the verification step.

Real-World Use Cases

1. Automated QA with Claude Desktop

Instead of writing Playwright scripts to poll a shared inbox, you tell Claude directly:

"I'm testing the Acme signup flow. Use create_and_wait_for_otp to generate an inbox, tell me the address, and wait for the OTP. I'll trigger the signup manually."

Claude calls create_and_wait_for_otp(timeout=45), returns the inbox and OTP, and you paste them into the browser. The entire verification step takes under a minute with no code.

For a fully automated version, combine FCE MCP with a browser automation MCP like Playwright MCP. See our Playwright & Selenium use case guide for the full pattern.

2. LangChain Agent Verification Node

from langchain.tools import tool
import requests, os

FCE_HEADERS = {"Authorization": f"Bearer {os.environ['FCE_API_KEY']}"}

@tool
def create_inbox_and_wait_for_otp(timeout: int = 45) -> dict:
    """Creates a disposable inbox and waits up to timeout seconds for an OTP."""
    r = requests.post(
        "https://api2.freecustom.email/v1/mcp/create-and-wait-otp",
        headers={**FCE_HEADERS, "Content-Type": "application/json"},
        json={"timeout": timeout},
        timeout=timeout + 5,
    )
    return r.json()

Drop this into any LangChain agent or LangGraph node. The agent calls it when it needs a working inbox. See the full AI agents guide for LangGraph and OpenAI function calling examples.

3. CI/CD Pipeline — Parallel Inbox Provisioning

// helpers/inbox.ts
export async function createInboxAndWaitOtp(): Promise<{ inbox: string; otp: string }> {
  const res = await fetch("https://api2.freecustom.email/v1/mcp/create-and-wait-otp", {
    method: "POST",
    headers: {
      Authorization: `Bearer ${process.env.FCE_API_KEY}`,
      "Content-Type": "application/json",
    },
    body: JSON.stringify({ timeout: 45 }),
  });
  const data = await res.json();
  if (!data.success || !data.otp) throw new Error("No OTP received");
  return { inbox: data.inbox, otp: data.otp };
}

Each parallel test worker calls this function, gets its own isolated inbox, and proceeds independently. No shared state, no flaky tests. See our CI/CD pipelines guide for GitHub Actions YAML.

4. n8n and Zapier Workflows

Both n8n and Zapier support HTTP Request nodes. Point one at POST https://api2.freecustom.email/v1/mcp/create-and-wait-otp with your API key in the Authorization header. Use the returned otp field in subsequent nodes to complete verification steps automatically.

5. Multi-Agent Orchestration (LangGraph)

from langgraph.graph import StateGraph, END
from typing import TypedDict
import requests, os

class State(TypedDict):
    inbox: str | None
    otp: str | None
    verified: bool

def provision_email(state: State) -> State:
    r = requests.post(
        "https://api2.freecustom.email/v1/mcp/create-and-wait-otp",
        headers={"Authorization": f"Bearer {os.environ['FCE_API_KEY']}",
                 "Content-Type": "application/json"},
        json={"timeout": 45},
        timeout=50,
    )
    data = r.json()
    return {**state, "inbox": data.get("inbox"), "otp": data.get("otp")}

Each sub-agent in a multi-agent graph gets its own isolated inbox. No inbox collisions, no shared state between parallel agents. This is the pattern Pinterest uses at scale for production MCP deployments.

Plan Requirements and Rate Limits

Exceeding the ops/minute cap returns a structured 429 with upgrade_required: true. Credits are deducted at call time: 2× for get_latest_email, 3× for extract_otp, and 5× for create_and_wait_for_otp.

See the MCP documentation for the full rate limit and abuse protection reference.

Best Practices for Agent Prompts

AI models have guardrails against "automated bot behavior." When prompting an agent to use the FCE tools, use developer framing:

❌ Bad: "Go to acme.com/signup, register a new account using a disposable email, and return the OTP."

✅ Good: "I'm a QA engineer testing the Acme signup flow. Use create_and_wait_for_otp to generate a test inbox. I'll trigger the signup on my end and you wait for the code."

The second prompt establishes a legitimate testing context, which is accurate — this is exactly what the tool is for.

Frequently Asked Questions

What is an MCP server for email? An MCP server for email is a local process that exposes email operations (creating inboxes, waiting for messages, extracting OTPs) as callable tools that any MCP-compatible AI agent can invoke. The FreeCustom.Email MCP server wraps our disposable email API into three intent-driven tools so agents don't need to manage polling logic.

Do I need a Growth plan to use the MCP server? Yes. The MCP layer requires a Growth ($49/mo) or Enterprise ($149/mo) plan because it uses persistent long-polling connections backed by Redis pub/sub. Lower plans receive a structured 403 error with an upgrade hint.

Can I use the MCP server with GPT-4o or Gemini? Yes. The server implements the standard MCP protocol, so any MCP-compatible client works — Claude Desktop, Cursor, Windsurf, Kilo, and custom agents built with the Python mcp SDK or the JavaScript @modelcontextprotocol/sdk package.

What happens if no email arrives within the timeout? create_and_wait_for_otp returns { "success": false, "inbox": "...", "message": "Timeout reached, no OTP received" }. The inbox is still created and registered, so you can retry with extract_otp if the email arrives slightly later.

Is the connection secure? Yes. All traffic between the MCP server and the FCE API uses HTTPS. The API key is passed as a Bearer token and never logged. See our API authentication docs for details.

Can I use a custom domain with the MCP server? Yes, on Growth and Enterprise plans. Register and verify your domain via the custom domains API, then pass "domain": "mail.yourdomain.com" to create_and_wait_for_otp.

How is this different from just using the REST API directly? The REST API requires you to write your own polling loop, handle timeouts, parse OTPs, and wire everything together. The MCP server does all of that for you in a single tool call that any agent can invoke without custom integration code. It is the difference between GET /v1/inboxes/{inbox}/otp in a loop versus create_and_wait_for_otp().

What domains are available for generated inboxes? By default: ditube.info, ditapi.info, ditplay.info, and other platform domains listed in GET /v1/domains. Growth and Enterprise plans have access to additional pro-tier domains. See the domains reference.

Related Resources

• MCP API Reference — full tool documentation with request/response schemas

• AI Agent Integration Guide — Claude Desktop, LangChain, LangGraph, OpenAI, Cursor

• Playwright & Selenium Guide — E2E browser test automation

• CI/CD Pipeline Guide — GitHub Actions, GitLab CI, CircleCI

• Webhooks Documentation — server-to-server push notifications

• Wait API Documentation — long-polling without MCP

• API Pricing — plan comparison and credit packs