MCP Server

The AgentInbox MCP (Model Context Protocol) server exposes 12 tools so AI agents can create inboxes, wait for emails, and extract OTPs and magic links directly — no glue code required.

HTTP transport with bearer auth

AgentInbox runs a remote MCP server over streamable HTTP at https://agentinbox.in/api/mcp. Authenticate with an API key (at_live_...) in the Authorization: Bearer header. There is no package to install.

Available Tools

Each tool maps to the same resources and scopes as the REST API. The API key's scopes determine which tools an agent can call.

create_inbox

inbox:create

Create a temporary inbox with optional TTL, purpose, and session.

list_inboxes

inbox:read

List inboxes in your account, newest first.

get_inbox

inbox:read

Retrieve a single inbox by ID.

delete_inbox

inbox:delete

Delete an inbox and stop further delivery.

list_messages

message:read

List messages received in an inbox, newest first.

get_message

message:read

Read a message including its sanitized body and headers.

list_extractions

extraction:read

List structured extractions (OTPs, links, codes) for an inbox.

check_wait

wait:read

Non-blocking status check for a wait: pending, completed, timeout, or cancelled.

wait_for_email

wait:create

Block until any matching email arrives, then return it.

wait_for_otp

wait:create

Block until an OTP is extracted from a received email.

wait_for_magic_link

wait:create

Block until a magic or verification link is extracted.

wait_for_password_reset

wait:create

Block until a password-reset link is extracted.

Setup for Claude & remote-MCP clients

Clients that support remote MCP servers can connect with the endpoint URL and an Authorization header.

mcp config

{
  "mcpServers": {
    "AgentInbox": {
      "url": "https://agentinbox.in/api/mcp",
      "headers": {
        "Authorization": "Bearer at_live_..."
      }
    }
  }
}

Setup for Cursor

Add the server to your Cursor MCP configuration.

.cursor/mcp.json

// ~/.cursor/mcp.json (or .cursor/mcp.json in your project)
{
  "mcpServers": {
    "AgentInbox": {
      "url": "https://agentinbox.in/api/mcp",
      "headers": {
        "Authorization": "Bearer at_live_..."
      }
    }
  }
}

Clients without remote MCP support

For stdio-only clients, bridge to the HTTP endpoint with the community mcp-remote adapter.

claude_desktop_config.json

{
  "mcpServers": {
    "AgentInbox": {
      "command": "npx",
      "args": [
        "-y",
        "mcp-remote",
        "https://agentinbox.in/api/mcp",
        "--header",
        "Authorization: Bearer at_live_..."
      ]
    }
  }
}

Restart required

Restart your client after editing its config so it picks up the new server.

Input & output example

A typical flow: create_inbox, use the address in your product, then call a wait_for_* tool. Waits scan already-arrived messages first, then poll until the timeout.

tool call

// The agent calls wait_for_otp after creating an inbox.
{
  "name": "wait_for_otp",
  "arguments": {
    "inboxId": "inbox_3f2a...",
    "timeoutSeconds": 120
  }
}

tool result

{
  "id": "wait_9c1b...",
  "type": "otp",
  "status": "completed",
  "result": {
    "value": "482931",
    "messageId": "msg_7d2e..."
  }
}

Troubleshooting

401 Unauthorized — the API key is missing, malformed, or revoked. Confirm the Authorization: Bearer at_live_... header.
Tool not available — the key lacks the required scope (for example wait:create). Create a key with the needed scopes.
429 Too Many Requests — you hit a daily quota or rate limit. Check Usage in the dashboard or upgrade your plan.
Wait returns timeout — no matching email arrived in time. Increase timeoutSeconds (max 300) or relax the filters.

Next Steps

Quickstart

Make your first API call

Learn more

API Reference

Complete endpoints and schemas

Learn more

Node SDK

Use AgentInbox from TypeScript

Learn more

Waits

Block until verification emails arrive

Learn more