OpenAI Agents SDK + Physical Mail

Wire-up

from agents import Agent, MCPServerStdio

mail = MCPServerStdio(
    name="mailsnail",
    params={
        "command": "npx",
        "args": ["-y", "mailsnail"],
        "env": {
            "MAIL_PROVIDER": "managed",
            "MAIL_API_BASE_URL": "https://api.mailsnail.dev",
        },
    },
)

agent = Agent(
    name="Mailer",
    instructions="You can send physical mail via the Mailsnail MCP server.",
    mcp_servers=[mail],
)

That's it — the agent now has the mail tools available alongside whatever else it can do.

A practical example

A classic loop: a CRM webhook fires when a deal closes, the agent drafts a personalized thank-you letter to the buyer, and send_letter puts it in the mail. The whole sequence is one tool-using turn for the agent.

response = await agent.run(
    "A new deal closed: contact_id=c_42. Mail them a thank-you note."
)

The agent fetches the contact, drafts a letter, and calls send_letter. You get back a tracking ID it can poll later via get_letter.

Gotchas

• The server runs over stdio via npx, so Node.js 18+ must be installed wherever your agent process runs.
• By default the server is in dry-run mode and won't actually mail anything — set MAIL_MCP_ALLOW_LIVE=1 (and a spend cap) when you're ready to print.
• The agent SDK's tool-use loop occasionally retries. Make sure your prompts make it obvious that one piece per request is the intended behavior.

{
  "mcpServers": {
    "mailsnail": {
      "command": "npx",
      "args": [
        "-y",
        "mailsnail"
      ],
      "env": {
        "MAIL_PROVIDER": "managed",
        "MAIL_API_BASE_URL": "https://api.mailsnail.dev"
      }
    }
  }
}