An email MCP server for agents that need to receive mail

An agent testing a sign-up flow gets stuck at "we've emailed you a code" because it has nowhere to receive the email. OTPBox runs a hosted MCP server that fixes this. The agent creates a disposable inbox, puts the address in the form, waits for the email and reads the extracted code or link, all through tool calls and without a script written in advance.

Which kind of email MCP server is this? OTPBox gives an agent new, throwaway inboxes for receiving test email: sign-up confirmations, OTPs, magic links. It does not connect to your own Gmail or Outlook mailbox, and it can't send mail. If you want an agent to read or answer your personal email, you need a server that connects to your mail account instead. For agents that need a standing mailbox of their own, see Best email tools for AI agents.

What you're connecting to

Endpoint: https://otpbox.io/mcp, a remote server using the streamable HTTP transport. It's hosted, so there's no local process to install or keep running.
Auth: Authorization: Bearer <key>, the same key as the REST API. There's no separate MCP credential.
Tools: 13 of them, backed by the same inboxes, messages and quota as /api/v1.

1. Get a key

Mint a free key with no account (200 requests a month, 5 keys a day per IP):

curl -X POST https://otpbox.io/api/v1/keys/free

{ "id": "lic_...", "key": "...", "plan": "free", "quotaLimit": 200 }

If several agents or projects should share one pooled quota, mint an organization key in the dashboard instead. For deterministic agent tests that don't depend on real delivery, POST /api/v1/keys/sandbox mints a sandbox key. With a sandbox key, create_test_inbox returns an inbox that already holds one synthesized message from noreply@sandbox.otpbox.io with a random 6-digit code. See Get a key.

2. Connect your client

Most MCP clients that support remote servers take this shape:

{
  "mcpServers": {
    "otpbox": {
      "url": "https://otpbox.io/mcp",
      "headers": { "Authorization": "Bearer <your-otpbox-key>" }
    }
  }
}

A few clients use a different key name or file. The exact syntax for the common ones:

Claude Code

claude mcp add --transport http otpbox https://otpbox.io/mcp \
  --header "Authorization: Bearer <your-otpbox-key>"

Add --scope project to share it with your team via .mcp.json. Claude Code setup

Cursor

In .cursor/mcp.json (project) or ~/.cursor/mcp.json (global), use the JSON above. Cursor resolves ${env:OTPBOX_KEY} inside headers, so the raw key can stay out of the file. Cursor setup

GitHub Copilot in VS Code

// .vscode/mcp.json
{
  "servers": {
    "otpbox": {
      "type": "http",
      "url": "https://otpbox.io/mcp",
      "headers": { "Authorization": "Bearer <your-otpbox-key>" }
    }
  }
}

GitHub Copilot setup

Gemini CLI

// ~/.gemini/settings.json
{
  "mcpServers": {
    "otpbox": {
      "httpUrl": "https://otpbox.io/mcp",
      "headers": { "Authorization": "Bearer <your-otpbox-key>" }
    }
  }
}

Gemini CLI uses httpUrl for streamable HTTP. A plain url is treated as the older SSE transport. Gemini CLI setup

Codex

# ~/.codex/config.toml
[mcp_servers.otpbox]
url = "https://otpbox.io/mcp"
bearer_token_env_var = "OTPBOX_KEY"

Codex reads the token from the OTPBOX_KEY environment variable. Codex setup

Devin Desktop, Qwen Code, Trae, Kimi Code CLI, iFlow CLI, GigaCode and SourceCraft each have their own page under per-client setup.

3. The tools

Inbox and message tools take the inbox id returned by create_test_inbox.

Tool	What it does
`create_test_inbox`	Create a disposable inbox (optional `domain`, `local`). Returns its id, address and expiry.
`wait_for_email`	Block until a new message arrives or the timeout passes (`timeoutSeconds` 1–25, default 20). Use this rather than polling.
`get_otp`	The most recently extracted one-time code in the inbox.
`get_verification_link`	The most recently extracted confirmation or verification link (`url`, `host`, `type`).
`get_latest_email`	The full most recent message: sender, subject, text/HTML, code, link and attachments.
`search_emails`	List messages newest first (up to 50), optionally filtered by a substring of the sender or subject.
`delete_inbox`	Permanently delete an inbox and every message in it.
`create_batch`	Create 1–50 inboxes in one call.
`create_test_identity`	A synthetic persona (name, email, country, profile) backed by a real inbox.
`create_bulk_test_identities`	1–50 test identities in one call.
`delete_test_identity`	Delete a test identity and its backing inbox.
`register_webhook`	Register an HTTPS webhook for inbox, message, link and identity events.
`get_usage`	Plan, quota, usage this cycle and reset date.

Full argument and return shapes are in the MCP section of the docs.

4. What a run looks like

Give the agent a browser tool as well, then a prompt such as:

"Create a disposable inbox, sign up for my app at localhost:3000 with it,
wait for the verification email, and finish the signup with the code."

The agent's model picks the order, but the tool calls usually come out like this:

1. create_test_inbox()
   -> { id: "a1b2c3", address: "bold.quartz844@otpbox.io", expiresAt: ... }
2. (browser) fill the email field with that address and submit
3. wait_for_email({ inboxId: "a1b2c3", timeoutSeconds: 20 })
   -> { timedOut: false, message: { code: "482913", ... } }
4. (browser) type 482913 into the code field and submit
5. delete_inbox({ inboxId: "a1b2c3" })

If the app emails a link instead of a code, the agent calls get_verification_link after the wait and opens the url in the browser. Inboxes expire 1 hour after creation by default, so one that gets left behind cleans itself up.

Limits worth knowing

Each tool call counts as one request against the key's monthly quota: 200 on a free key, 5,000 pooled on Pro.
Separately, MCP allows 60 tool calls per minute per key, which stops a runaway agent loop early.
Failures come back as MCP tool errors rather than HTTP status codes. A missing, invalid, expired or inactive key is rejected with 401/402 before any tool runs.
Tools enforce the same key scopes as REST. For example, a key scoped to inbox:create and otp:read can create inboxes and read codes and links, but can't register webhooks or create batches.

Next steps

Rather skip the account? curl -X POST https://otpbox.io/api/v1/keys/free gives you a free key with 200 requests a month, and it works in every config above.

API docs Pricing All guides Changelog

← Back to OTPBox