Connect AI agent frameworks to MailSlurp MCP

Agents that act on the web keep running into email. They sign up for services and need the verification code, wait for a password reset link, read a support request or reply to a customer. Giving an agent a shared personal mailbox is risky, and writing a custom email integration for every framework is slow.

MailSlurp runs a hosted Model Context Protocol server that gives an agent scoped access to MailSlurp inboxes and phone numbers. Most agent frameworks can call a remote MCP server, so the same MailSlurp tools work in each of them with a few lines of setup. This page shows that setup for the Claude API, the OpenAI Agents SDK, the Vercel AI SDK and LangChain.

For desktop and coding clients such as Claude Code, Codex and Cursor, follow Install in your AI client instead. Those clients can sign in with OAuth and need no key.

Before you start

Every example connects to the same endpoint over Streamable HTTP:

https://api.mailslurp.com/mcp

Server-side frameworks authenticate with a scoped agent key rather than OAuth:

Open Create a scoped agent key in MailSlurp.
Choose the least-privileged role that fits the task. A read-only role is enough for reading verification codes and links; choose a responder or support role only if the agent must draft or send replies.
Select the inboxes or phone numbers the agent may use.
Copy the key and store it as MAILSLURP_AGENT_KEY in the environment where the agent runs.

The server accepts the key in an x-api-key header or as Authorization: Bearer <key>. Use a dedicated agent key for each agent rather than an account API key, so that each agent’s access, activity and revocation stay separate. Create a scoped agent key explains roles and scopes in more detail.

Claude API

The Claude Messages API connects to remote MCP servers for you. Pass MailSlurp in mcp_servers and enable its tools with an mcp_toolset entry of the same name:

pip install anthropic

import os

import anthropic

client = anthropic.Anthropic()

response = client.beta.messages.create(
    model="claude-opus-5-5",
    max_tokens=16000,
    betas=["mcp-client-2025-11-20", "server-side-fallback-2026-07-01"],
    fallbacks="default",
    mcp_servers=[
        {
            "type": "url",
            "url": "https://api.mailslurp.com/mcp",
            "name": "mailslurp",
            "authorization_token": os.environ["MAILSLURP_AGENT_KEY"],
        }
    ],
    tools=[{"type": "mcp_toolset", "mcp_server_name": "mailslurp"}],
    messages=[
        {
            "role": "user",
            "content": "Find the newest email in my MailSlurp inbox and tell me the verification code it contains.",
        }
    ],
)

if response.stop_reason == "refusal":
    print("The request was declined:", response.stop_details)
else:
    for block in response.content:
        if block.type == "text":
            print(block.text)

Anthropic calls the MailSlurp tools server-side within the same request, so there is no tool loop to write. fallbacks="default" lets the API retry a declined request on another model; remove it and its beta flag if you don’t want that behavior.

OpenAI Agents SDK

The OpenAI Agents SDK connects to Streamable HTTP servers with MCPServerStreamableHttp:

pip install openai-agents

import asyncio
import os

from agents import Agent, Runner
from agents.mcp import MCPServerStreamableHttp


async def main() -> None:
    async with MCPServerStreamableHttp(
        name="MailSlurp",
        params={
            "url": "https://api.mailslurp.com/mcp",
            "headers": {"x-api-key": os.environ["MAILSLURP_AGENT_KEY"]},
            "timeout": 30,
        },
        cache_tools_list=True,
    ) as mailslurp:
        agent = Agent(
            name="Inbox assistant",
            instructions=(
                "Use the MailSlurp tools to read email. Call "
                "mailslurp.list_accessible_inboxes before using an inbox ID."
            ),
            mcp_servers=[mailslurp],
        )
        result = await Runner.run(
            agent,
            "Find the newest email in my MailSlurp inbox and return the verification code.",
        )
        print(result.final_output)


asyncio.run(main())

Keep the agent inside the async with block so the MCP connection stays open while it runs.

Vercel AI SDK

The AI SDK turns a remote MCP server’s tools into ordinary AI SDK tools:

npm install ai @ai-sdk/mcp

import { createMCPClient } from '@ai-sdk/mcp';
import { generateText, stepCountIs } from 'ai';

const mailslurp = await createMCPClient({
  transport: {
    type: 'http',
    url: 'https://api.mailslurp.com/mcp',
    headers: { 'x-api-key': process.env.MAILSLURP_AGENT_KEY! },
  },
});

try {
  const tools = await mailslurp.tools();
  const result = await generateText({
    model: 'anthropic/claude-opus-5-5',
    tools,
    stopWhen: stepCountIs(5),
    prompt: 'Find the newest email in my MailSlurp inbox and return the verification code.',
  });
  console.log(result.text);
} finally {
  await mailslurp.close();
}

stopWhen lets the model call several MailSlurp tools in sequence, for example listing inboxes and then reading the latest email, before it writes the answer. Use any model your AI SDK project is configured for.

LangChain

LangChain loads MCP tools through its MCP adapter and passes them to any LangChain agent:

pip install "langchain[mcp]"

import asyncio
import os

from fastmcp.client import Client
from langchain.agents import create_agent
from langchain.mcp import MCPAdapter


async def main() -> None:
    client = Client("https://api.mailslurp.com/mcp", auth=os.environ["MAILSLURP_AGENT_KEY"])
    async with MCPAdapter(client) as adapter:
        tools = await adapter.list_tools()
        agent = create_agent("claude-opus-5-5", tools)
        result = await agent.ainvoke(
            {
                "messages": [
                    {
                        "role": "user",
                        "content": "Find the newest email in my MailSlurp inbox and return the verification code.",
                    }
                ]
            }
        )
        print(result["messages"][-1].content)


asyncio.run(main())

The adapter sends the key as a bearer token. Run the agent inside the async with block so the tools stay connected.

Check what the agent can do

The tools an agent sees depend on the role and scope of its key. A read-only key covers finding inboxes, waiting for and reading email, threads and attachments, and work-queue and human-review tools such as:

mailslurp.list_accessible_inboxes
mailslurp.get_latest_inbox_email
mailslurp.search_inbox_emails
mailslurp.get_email and mailslurp.get_email_thread
mailslurp.extract_email_attachment_text
mailslurp.request_human_review

Roles that can respond add draft, reply and send tools, and keys scoped to phone numbers add SMS tools such as mailslurp.list_received_sms and mailslurp.reply_to_sms. Ask your agent to list its MailSlurp tools to see exactly what its key allows. The full MCP tool list describes each tool and its permissions.

Keep agents safe

Give each agent its own key, with only the inboxes and phone numbers it needs.
Start with a read-only role and add reply or send permissions only when the workflow needs them.
Route outgoing messages through drafts and human review until you trust the agent’s output.
Store keys in your secret manager, never in prompts or source control.
Revoke a key from Agents in MailSlurp when the agent is retired.

To give an agent a phone number for SMS verification codes, see Receive SMS OTP codes with an AI agent.

Build with MailSlurp

Connect & learn