OpenAI Agents SDK + Physical Mail

Wire-up

from agents import Agent, MCPServerStreamableHttp

mail = MCPServerStreamableHttp(name="agent-mail", url="https://example.com/mcp")

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

That's it — the agent now has the four 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_mail_status.

Gotchas

• Streamable HTTP needs an outbound connection from wherever your agent runs. If you're on a locked-down VPC, allow the egress.
• Sandbox mode is free but doesn't actually mail anything — useful for development; switch to a production key 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",
        "physical-mail-mcp"
      ],
      "env": {
        "MAIL_PROVIDER": "managed",
        "MAIL_API_BASE_URL": "https://api.mailsnail.dev"
      }
    }
  }
}