OTPBox

OTPBox for agents: MCP and REST

OTPBox gives an AI agent disposable e-mail inboxes to sign up to sites and read one-time codes and verification links. It is MCP-first: connect your MCP client to https://otpbox.rc.center/mcp and sign in with rc.center. Everything the tools do is also in the REST API (OpenAPI 3.1).

Connect an MCP client

The server URL is https://otpbox.rc.center/mcp (Streamable HTTP). Clients discover the OAuth server, register themselves and open a browser: sign in with rc.center, review the permissions, and allow.

claude.ai

Settings, Connectors, Add custom connector. Name: OTPBox. URL: https://otpbox.rc.center/mcp. Then Connect.

Claude Code

claude mcp add --transport http otpbox https://otpbox.rc.center/mcp

Then run /mcp inside Claude Code and choose otpbox to sign in.

Codex

codex mcp add otpbox --url https://otpbox.rc.center/mcp
codex mcp login otpbox

Cursor

{"mcpServers": {"otpbox": {"url": "https://otpbox.rc.center/mcp"}}}

in ~/.cursor/mcp.json (or the project's .cursor/mcp.json).

Headless agents and scripts

Create an API key in the web UI (Inboxes page, API keys) and send it as Authorization: Bearer obx_... to /mcp or /v1. API keys are created only in the web UI, by you: no tool or endpoint lets an agent mint its own long-lived key.

The flow an agent follows

1. inbox_create {"prefix": "signup"}
   -> {"id": "...", "address": "signup.k3m9qa@<account>.otpbox.org"}
2. use the address on the site
3. message_wait {"inbox_id": "...", "timeout_seconds": 60, "from": "acme"}
   -> {"found": true, "codes": ["482913"], "verify_link": "https://..."}
4. type codes[0] into the site, or open verify_link

message_wait also returns messages of the last 10 minutes, so call it right after triggering the e-mail. Errors come back as tool errors with the next step (unknown inbox, plan without OTPBox, inbox limit, missing permission).

Tools, permissions and the REST equivalent

  • inbox_create inboxes:write POST /v1/inboxes
  • inbox_list inboxes:read GET /v1/inboxes
  • inbox_get inboxes:read GET /v1/inboxes/{id}
  • inbox_delete inboxes:write DELETE /v1/inboxes/{id}
  • inbox_webhook_set inboxes:write PUT /v1/inboxes/{id}/webhook
  • inbox_webhook_clear inboxes:write DELETE /v1/inboxes/{id}/webhook
  • messages_list messages:read GET /v1/inboxes/{id}/messages
  • message_wait messages:read GET /v1/inboxes/{id}/wait
  • message_get messages:read GET /v1/messages/{id}
  • message_delete messages:write DELETE /v1/messages/{id}
  • attachment_get messages:read GET /v1/messages/{id}/attachments/{index}
  • usage_get inboxes:read GET /v1/usage

REST quickstart

export OTPBOX_KEY=obx_...   # from the web UI

# create an inbox
curl -s -X POST https://otpbox.rc.center/v1/inboxes -H "Authorization: Bearer $OTPBOX_KEY" \
  -H 'Content-Type: application/json' -d '{"prefix":"signup"}'

# wait up to 60 s for the code (returns found=false on timeout)
curl -s "https://otpbox.rc.center/v1/inboxes/$INBOX_ID/wait?timeout=60&subject=verification" \
  -H "Authorization: Bearer $OTPBOX_KEY"

# usage and quotas
curl -s https://otpbox.rc.center/v1/usage -H "Authorization: Bearer $OTPBOX_KEY"

Errors are JSON: {"error": "plan_required", "message": "..."} with 400, 401, 403, 404, 409 or 413.

OAuth details (for client authors)

  • Protected resource metadata: https://otpbox.rc.center/.well-known/oauth-protected-resource
  • Authorization server metadata: https://otpbox.rc.center/.well-known/oauth-authorization-server
  • Dynamic client registration (RFC 7591), authorization code with PKCE S256 only, refresh tokens rotate, revocation (RFC 7009).
  • Callbacks: loopback http, or https on claude.ai, claude.com and the other hosted clients listed in the registration error.
  • Scopes: inboxes:read inboxes:write messages:read messages:write