Use mails.ai with the Claude Agent SDK

Connect a Claude agent to the hosted MCP server, in TypeScript or Python.

This guide connects the Claude Agent 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

npm install @anthropic-ai/claude-agent-sdk

pip install claude-agent-sdk

Write the agent

Pass the server in mcpServers. MCP tools need permission before Claude can call them: allowedTools: ["mcp__mails__*"] lets the agent use every mails tool without asking, sending included.

Save this as agent.ts or agent.py:

import { query } from "@anthropic-ai/claude-agent-sdk";

for await (const message of query({
  prompt: "Email reply@test.mails.ai to say the report is ready.",
  options: {
    mcpServers: {
      mails: {
        type: "http",
        url: "https://api.mails.ai/mcp",
        headers: {
          Authorization: `Bearer ${process.env.MAILS_API_KEY}`,
        },
      },
    },
    allowedTools: ["mcp__mails__*"],
  },
})) {
  if (message.type === "result" && message.subtype === "success") {
    console.log(message.result);
  }
}

import asyncio
import os

from claude_agent_sdk import query, ClaudeAgentOptions, ResultMessage


async def main():
    options = ClaudeAgentOptions(
        mcp_servers={
            "mails": {
                "type": "http",
                "url": "https://api.mails.ai/mcp",
                "headers": {"Authorization": f"Bearer {os.environ['MAILS_API_KEY']}"},
            }
        },
        allowed_tools=["mcp__mails__*"],
    )

    async for message in query(
        prompt="Email reply@test.mails.ai to say the report is ready.",
        options=options,
    ):
        if isinstance(message, ResultMessage) and message.subtype == "success":
            print(message.result)


asyncio.run(main())

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

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?