MCP Email Server: Giving Claude and Any MCP Client a Real Inbox

The Model Context Protocol (MCP) is rapidly becoming the standard for connecting AI agents to external tools. AgentMailr ships a native MCP server, which means any MCP-compatible agent including Claude Desktop, Claude Code, Cursor, and any custom agent built on the MCP SDK can provision inboxes, extract OTPs, and receive emails without any custom integration code.

What Is an MCP Server?

MCP (Model Context Protocol) is an open protocol developed by Anthropic that standardizes how AI models connect to data sources and tools. An MCP server exposes a set of tools that any compatible client can call. When Claude or another MCP client connects to the AgentMailr MCP server, it gains access to email tools natively — the same way it can use a filesystem tool or a database query tool.

Connecting to Claude Desktop

Add the AgentMailr MCP server to your Claude Desktop configuration file. On macOS, this is at ~/Library/Application Support/Claude/claude_desktop_config.json.

{
  "mcpServers": {
    "agentmailr": {
      "command": "npx",
      "args": ["-y", "@agentmailr/mcp-server"],
      "env": {
        "AGENTMAILR_API_KEY": "your_api_key_here"
      }
    }
  }
}

Restart Claude Desktop after saving. Claude will now have access to the AgentMailr tools automatically, with no further setup needed.

Available MCP Tools

Once connected, the following tools are available to any MCP client:

• create_inbox: Provisions a new temporary email inbox. Returns an address like agent-x7k2@in.agentmailr.com. Use this before any signup flow.
• wait_for_otp: Blocks until an OTP or verification code arrives in the specified inbox. Returns the extracted numeric code. Supports a configurable timeout.
• wait_for_email: Blocks until any email arrives. Returns the full parsed message including from, subject, body text, and any links found in the body.
• list_messages: Returns all messages currently in an inbox. Useful for reading confirmation emails or finding magic links after a non-blocking wait.
• delete_inbox: Permanently deletes an inbox and all its messages. Call at the end of each workflow run to keep your account clean.

Prompting Claude to Use Email Tools

With the MCP server connected, Claude understands how to use the email tools contextually. You can give it a natural language instruction and it will handle the tool orchestration:

Claude will call create_inbox to get an address, use it in the form, then call wait_for_otp to retrieve the code — all without you writing a single line of tool integration code.

Using the MCP Server Programmatically

For custom agents built on the MCP TypeScript or Python SDK, you can connect to the AgentMailr server and call tools directly in code:

import { Client } from "@modelcontextprotocol/sdk/client/index.js";
import { StdioClientTransport } from "@modelcontextprotocol/sdk/client/stdio.js";

const transport = new StdioClientTransport({
  command: "npx",
  args: ["-y", "@agentmailr/mcp-server"],
  env: { AGENTMAILR_API_KEY: process.env.AGENTMAILR_API_KEY },
});

const client = new Client({ name: "my-agent", version: "1.0.0" }, {});
await client.connect(transport);

// Create inbox
const { content } = await client.callTool({
  name: "create_inbox",
  arguments: {},
});
const { address, id } = JSON.parse(content[0].text);

// ... run your signup automation with address ...

// Wait for OTP
const otpResult = await client.callTool({
  name: "wait_for_otp",
  arguments: { inboxId: id, timeout: 30000 },
});
const { otp } = JSON.parse(otpResult.content[0].text);
console.log("Got OTP:", otp);

// Clean up
await client.callTool({ name: "delete_inbox", arguments: { inboxId: id } });

Connecting to Other MCP Clients

The AgentMailr MCP server works with any client that implements the MCP protocol. The configuration pattern is the same across clients: point the client at the @agentmailr/mcp-server package and pass your API key as an environment variable.

• Claude Desktop and Claude Code — add to mcpServers in config
• Cursor — add via the MCP settings panel
• Windsurf — add via the Cascade tools configuration
• Custom agents — use @modelcontextprotocol/sdk with StdioClientTransport
• Any future MCP-compatible host — same package, same pattern