MCP — AI-Native Email Workflows

Our MCP layer is not just another API client — it is a premium interface built specifically for AI agents, LLMs, and advanced automation systems. It wraps our backend architecture into intent-driven tools that AI agents can use out-of-the-box.

Why MCP?

Traditional APIs require you to build logic: "create inbox", "poll for email", "parse text", "extract OTP". With our MCP, you use AI-native workflows. You provide the intent, and the server handles the complexity.

• No Polling: Powered by long-polling and Redis pub/sub.
• No Complex Logic: Single operations handle multi-step flows (e.g., create_and_wait_for_otp).
• Agent-Ready: Simply attach the server to Claude Desktop, Cursor, or your custom agent framework.

Plan Requirements & Feature Gating

The MCP layer is a premium feature, restricted to our higher-tier plans:

Advanced Pricing & Billing

Because MCP tools perform advanced processing (combining authentication, inbox creation, listening, and extracting), MCP requests consume higher credits than normal API operations.

Tools Provided

We provide three categories of MCP tools: Email Operations, Inbox Management, and Custom Domain Management.

Email Operations

get_latest_email

Retrieves the most recent email for a given inbox address.

Args: inbox string · required — The full email address (e.g. hello@ditube.info)

extract_otp

Directly retrieves the latest 4-6 digit code or verification link.

Args: inbox string · required — The full email address of the inbox

create_and_wait_for_otp 🔥 GOLD

Generates a random inbox on our premium domains and holds the connection open until an OTP arrives. This allows an AI agent to execute a complete signup flow in a single tool call!

Args: domain string · optional · default ditube.info · timeout number (10-60) · optional · default 45

watch_email

Long-polling wait for new emails on an existing inbox. Use this when you've already created an inbox and want to wait for the next incoming email.

Args: inbox string · required · timeout number (10-60) · optional · default 30 · since string · optional · message ID to wait for newer messages

get_messages

Fetches multiple messages from an inbox.

Args: inbox string · required · limit number (1-100) · optional · default 10 · unread_only boolean · optional

delete_email

Deletes a specific email from an inbox.

Args: inbox string · required · message_id string · required

Inbox Management

list_inboxes

Lists all inboxes owned by the API key's account.

Args: (none)

Custom Domain Management

list_custom_domains

Lists all custom domains associated with the account.

Args: (none)

add_custom_domain

Adds a new custom domain to the account.

Args: domain string · required — The custom domain to add (e.g. mail.yourdomain.com)

verify_custom_domain

Initiates DNS verification for a custom domain.

Args: domain string · required — The custom domain to verify

delete_custom_domain

Deletes a custom domain from the account.

Args: domain string · required — The custom domain to delete

MCP Hosting (Cloud-Based AI Agents)

For cloud-based AI platforms that cannot run local commands (like Claude Web, Claude Desktop, Cursor, etc.), we provide hosted MCP endpoints. We support two transport protocols:

Base URL

https://mcp.freecustom.email

Endpoints

Which endpoint should I use?

• Claude Web / Modern clients: Use /mcp (Streamable HTTP)
• Claude Desktop / Legacy clients: Use /sse (SSE)
• Both support the same authentication methods

Authentication

We support two authentication methods:

Option 1: Direct API Key (Simple)

Pass your API key via the Authorization header or access_token query param:

Authorization: Bearer YOUR_API_KEY

Or:

GET /mcp?access_token=YOUR_API_KEY

Option 2: OAuth 2.0 (Required by Some Clients)

Some AI clients (like Claude Web) require OAuth. We implement a simplified OAuth flow where your API key acts as the client_id:

1. Authorize: Redirect user to:

GET /authorize?client_id=YOUR_API_KEY&redirect_uri=REDIRECT_URI&state=STATE&code_challenge=CHALLENGE&code_challenge_method=S256

2. Token Exchange: Client exchanges the auth code for a token:

POST /token
Content-Type: application/x-www-form-urlencoded

grant_type=authorization_code&code=AUTH_CODE&client_id=YOUR_API_KEY

3. Response:

GET /.well-known/oauth-authorization-server

Endpoints

Connecting with Streamable HTTP (/mcp)

The recommended endpoint for modern MCP clients. Uses the new Streamable HTTP transport protocol.

# Streamable HTTP (recommended)
curl -X POST https://mcp.freecustom.email/mcp \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "jsonrpc": "2.0",
    "method": "initialize",
    "params": {
      "protocolVersion": "2024-11-05",
      "capabilities": {},
      "clientInfo": {
        "name": "claude-web",
        "version": "1.0.0"
      }
    },
    "id": 1
  }'

SSE Connection Example

# With Direct API Key
curl -N https://mcp.freecustom.email/sse \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -H "Accept: text/event-stream"

# With OAuth Token
curl -N https://mcp.freecustom.email/sse \
  -H "Authorization: Bearer OAUTH_ACCESS_TOKEN" \
  -H "Accept: text/event-stream"

# With Query Param
curl -N "https://mcp.freecustom.email/sse?access_token=YOUR_API_KEY" \
  -H "Accept: text/event-stream"

Send Messages Example

curl -X POST "https://mcp.freecustom.email/messages?sessionId=SESSION_ID" \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "jsonrpc": "2.0",
    "id": 1,
    "method": "tools/call",
    "params": {
      "name": "create_and_wait_for_otp",
      "arguments": {
        "domain": "ditube.info",
        "timeout": 45
      }
    }
  }'

JSON-RPC 2.0 Protocol

The MCP server follows JSON-RPC 2.0 specification:

Request Format

{
  "jsonrpc": "2.0",
  "id": 1,
  "method": "tools/call",
  "params": {
    "name": "TOOL_NAME",
    "arguments": { ... }
  }
}

Response Format

{
  "jsonrpc": "2.0",
  "id": 1,
  "result": { ... }
}

Error Format

{
  "jsonrpc": "2.0",
  "id": 1,
  "error": {
    "code": -32600,
    "message": "Invalid Request",
    "data": "Details here"
  }
}

Available Methods

Initialize Request Example

{
  "jsonrpc": "2.0",
  "id": 1,
  "method": "initialize",
  "params": {
    "protocolVersion": "2024-11-05",
    "capabilities": {},
    "clientInfo": {
      "name": "claude-web",
      "version": "1.0.0"
    }
  }
}

{
  "jsonrpc": "2.0",
  "id": 1,
  "result": {
    "protocolVersion": "2024-11-05",
    "capabilities": { "tools": {} },
    "serverInfo": {
      "name": "fce-mcp",
      "version": "1.0.9"
    }
  }
}

List Tools Request Example

{
  "jsonrpc": "2.0",
  "id": 2,
  "method": "tools/list"
}

Installation & Setup

You can run our MCP server via npx or by installing it from source.

Option 1: NPX (Recommended)

Configure your MCP client (e.g., Claude Desktop claude_desktop_config.json):

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

Option 2: From Source

1. Clone this repository and navigate to mcp-server/.
2. Run npm install and npm run build.
3. Add to your configuration using node and the build/index.js path.

Abuse & Limits

To ensure stability, MCP traffic runs through our Abuse Engine with strict limits applied before the normal rate-limiter:

• Ops/Minute Caps: 60 for Growth, 200 for Enterprise.
• Timeout Caps: Connections are forcefully closed after 60 seconds to prevent hanging.
• Multiplier Consumption: Requests immediately deduct their respective multipliers (1x, 2x, 3x, 5x, 10x) from your monthly allocation.

Error Responses

{
  "jsonrpc": "2.0",
  "id": 1,
  "error": {
    "code": -32001,
    "message": "FreeCustom.Email API Error: MCP not available on your plan...",
    "data": "Plan upgrade required"
  }
}

{
  "jsonrpc": "2.0",
  "id": 1,
  "error": {
    "code": -32002,
    "message": "API error: Invalid API key",
    "data": "Authentication failed"
  }
}

{
  "jsonrpc": "2.0",
  "id": 1,
  "error": {
    "code": -32601,
    "message": "Method not found",
    "data": "Tool 'invalid_tool' does not exist"
  }
}

{
  "jsonrpc": "2.0",
  "id": 1,
  "error": {
    "code": -32602,
    "message": "Invalid params",
    "data": "Missing required parameter: inbox"
  }
}