Use mails.ai with the OpenAI Agents SDK

Connect an OpenAI agent to the hosted MCP server, in Python or TypeScript.

This guide connects the OpenAI Agents SDK to the hosted mails.ai MCP server at https://api.mails.ai/mcp. It sends your API key in the Authorization header and gets the tools that key may call, as any other MCP client does (the tool list). With a test key (mk_test_…), the tools run in the sandbox and no email leaves mails.ai.

Before you start

The sample reads your key from MAILS_API_KEY. The framework also needs a key for its model provider, set the way its own documentation says.

export MAILS_API_KEY=mk_test_xxxxxxxx

The sample asks the agent to email reply@test.mails.ai. Nothing sent to that address leaves mails.ai, and it answers, so your agent gets a reply.received event back.

The TypeScript sample runs as an ES module with tsx. In a new folder:

npm init -y
npm pkg set type=module
npm install --save-dev tsx

Install

pip install openai-agents

npm install @openai/agents zod

Write the agent

Connect with MCPServerStreamableHttp and hand the server to the agent in mcp_servers (Python) or mcpServers (TypeScript).

Save this as agent.py or agent.ts:

import asyncio
import os

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


async def main() -> None:
    async with MCPServerStreamableHttp(
        name="mails",
        params={
            "url": "https://api.mails.ai/mcp",
            "headers": {"Authorization": f"Bearer {os.environ['MAILS_API_KEY']}"},
        },
    ) as server:
        agent = Agent(
            name="Assistant",
            instructions="Use the mails tools to send and read email.",
            mcp_servers=[server],
        )
        result = await Runner.run(agent, "Email reply@test.mails.ai to say the report is ready.")
        print(result.final_output)


asyncio.run(main())

import { Agent, run, MCPServerStreamableHttp } from "@openai/agents";

const mails = new MCPServerStreamableHttp({
  url: "https://api.mails.ai/mcp",
  name: "mails",
  requestInit: {
    headers: { Authorization: `Bearer ${process.env.MAILS_API_KEY}` },
  },
});

const agent = new Agent({
  name: "Assistant",
  instructions: "Use the mails tools to send and read email.",
  mcpServers: [mails],
});

try {
  await mails.connect();
  const result = await run(agent, "Email reply@test.mails.ai to say the report is ready.");
  console.log(result.finalOutput);
} finally {
  await mails.close();
}

Set OPENAI_API_KEY, then run python agent.py or npx tsx agent.ts.

Next steps

MCP serverEvery tool, and the settings for each AI client.Agent skillsUse these tools safely on mail from strangers.IntegrationsEvery framework and AI client.

Was this page helpful?