OpenAI Agents SDK

Use this page to attach Sendmux to an OpenAI Agents SDK agent. Servers passed to mcp_servers expose their tools to the agent automatically, so you do not write tool wrappers.

Replace placeholder keys and tokens before running any snippet. Do not commit smx_root_, smx_mbx_, or private HTTP bearer tokens to version control.

Requirements

Python 3.10 or newer.
openai-agents installed.
A Sendmux key for the surface you are calling. Mailbox work needs an smx_mbx_ key or a scoped smx_agent_ token.

Install

pip install openai-agents sendmux-mcp

Connect over local stdio

The SDK manages the subprocess for you and passes your key through its environment.

triage.py

import asyncio
import os

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


async def main() -> None:
    async with MCPServerStdio(
        name="Sendmux mailbox",
        params={
            "command": "sendmux-mcp-mailbox",
            "env": {"SENDMUX_API_KEY": os.environ["SENDMUX_MAILBOX_API_KEY"]},
        },
        cache_tools_list=True,
    ) as server:
        agent = Agent(
            name="Inbox agent",
            instructions=(
                "You triage the mailbox you have been granted. "
                "Search before you read, and quote the message you acted on."
            ),
            mcp_servers=[server],
        )

        result = await Runner.run(agent, "What arrived overnight that needs a reply?")
        print(result.final_output)


asyncio.run(main())

Run more than one surface by switching to the sendmux-mcp entry point:

params={
    "command": "sendmux-mcp",
    "env": {
        "SENDMUX_MCP_SURFACES": "mailbox,sending",
        "SENDMUX_MAILBOX_API_KEY": os.environ["SENDMUX_MAILBOX_API_KEY"],
        "SENDMUX_SENDING_API_KEY": os.environ["SENDMUX_SENDING_API_KEY"],
    },
}

Connect over private HTTP

Use this when the agent runs somewhere it cannot spawn a process. Start the server yourself:

SENDMUX_API_KEY=smx_mbx_... \
SENDMUX_MCP_HTTP_BEARER_TOKEN=local-mcp-token \
sendmux-mcp-mailbox --transport http --host 127.0.0.1 --port 8765

Then connect with the streamable HTTP server:

import os

from agents.mcp import MCPServerStreamableHttp

server = MCPServerStreamableHttp(
    name="Sendmux mailbox",
    params={
        "url": "http://127.0.0.1:8765/mcp",
        "headers": {"Authorization": f"Bearer {os.environ['SENDMUX_MCP_HTTP_BEARER_TOKEN']}"},
        "timeout": 10,
    },
    cache_tools_list=True,
    max_retry_attempts=3,
)

Require approval before an agent sends

The SDK can hold a tool for approval before it runs. Pair this with the Sendmux sending gate when a human should see the message first.

server = MCPServerStdio(
    name="Sendmux",
    params={"command": "sendmux-mcp-mailbox", "env": {"SENDMUX_API_KEY": mailbox_key}},
    tool_filter=["mailbox_list_messages", "mailbox_search_message_snippets", "mailbox_get_message"],
    require_approval="never",
)

tool_filter narrows what the model can see at all. Use it to build a read-only triage agent, then add the sending tools only to the agent that is meant to reply.

Give each user their own mailbox

Mailbox-scoped keys are the isolation boundary. Open a server per tenant so the agent working one tenant structurally cannot read another tenant’s mail.

def server_for(mailbox_key: str) -> MCPServerStdio:
    return MCPServerStdio(
        name="Sendmux mailbox",
        params={
            "command": "sendmux-mcp-mailbox",
            "env": {"SENDMUX_API_KEY": mailbox_key},
        },
        cache_tools_list=True,
    )

Sending stays gated

A durable smx_agent_ token includes mailbox.read and email.receive, not email.send. After a named human owner accepts the invite and approves sending, exchange the durable token for a one-hour Sending-resource token and pass that as SENDMUX_SENDING_API_KEY.

Troubleshooting

The agent sees no tools

Confirm the surfaces the server started with. sendmux-mcp requires SENDMUX_MCP_SURFACES; the single-surface entry points do not. Check tool_filter as well, since it hides everything it does not name.

The subprocess exits immediately

Check the key prefix. Mailbox accepts smx_mbx_ or a scoped smx_agent_, Sending accepts a send-capable smx_mbx_ or an owner-approved Sending-resource smx_agent_, and Management requires smx_root_.

Tool calls time out

Raise client_session_timeout_seconds, and set max_retry_attempts so transient list and call failures retry with backoff.

You granted more than one mailbox

Start the workflow with mailbox_list_granted_mailboxes and pass the returned mailbox_id to tools that act on one mailbox.

Getting started

Developer tools

AI integrations

Sending

Receiving

Domains

Monitoring

Webhooks

Use cases

Integrations

Account and billing

OpenAI Agents SDK

Requirements

Install

Connect over local stdio

Connect over private HTTP

Require approval before an agent sends

Give each user their own mailbox

Sending stays gated

Troubleshooting

Next steps

Agent frameworks

MCP

Agent access

Python SDK

​Requirements

​Install

​Connect over local stdio

​Connect over private HTTP

​Require approval before an agent sends

​Give each user their own mailbox

​Sending stays gated

​Troubleshooting

​Next steps

Agent frameworks

MCP

Agent access

Python SDK

Requirements

Install

Connect over local stdio

Connect over private HTTP

Require approval before an agent sends

Give each user their own mailbox

Sending stays gated

Troubleshooting

Next steps