# OpenAI Agents SDK and MCPmailer

The OpenAI Agents SDK connects to MCPmailer as a streamable HTTP MCP server.

Hand an agent an MCPServerStreamableHttp pointed at MCPmailer and it gets the mail tools for the whole run, with the tool list cached between turns.

## Setup

1. **Install the SDK** The MCP client ships inside openai-agents; there is nothing else to add.
1. **Create a mailbox** One per agent, so its address and its key are the same identity.
1. **Open the server in a context manager** The async with block owns the connection and closes it.
1. **Put it on an agent** mcp_servers is per agent, so only the agents you list get mail tools.

## Install

```bash
pip install openai-agents
```

## Agents SDK (Python)

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

async with MCPServerStreamableHttp(
    name="mcpmailer",
    params={
        "url": "https://connect.mcpmailer.com/mcp",
        "headers": {"Authorization": "Bearer mmk_live_..."},
    },
    cache_tools_list=True,
) as server:
    agent = Agent(name="Support", mcp_servers=[server])
    result = await Runner.run(agent, "Reply to the newest support email.")
```

## Answer unread mail

cache_tools_list avoids refetching our tool list on every turn. Leave it off while you are still changing which tools the key can reach.

```py
import asyncio, os
from agents import Agent, Runner
from agents.mcp import MCPServerStreamableHttp

async def main():
    async with MCPServerStreamableHttp(
        name="mcpmailer",
        params={
            "url": "https://connect.mcpmailer.com/mcp",
            "headers": {"Authorization": f"Bearer {os.environ['MCPMAILER_KEY']}"},
        },
        cache_tools_list=True,
    ) as server:
        agent = Agent(
            name="Support",
            instructions="You answer support email. Reply in thread, never start new ones.",
            mcp_servers=[server],
        )
        result = await Runner.run(agent, "Check for unread mail and answer anything you can.")
        print(result.final_output)

asyncio.run(main())
```

## Worth knowing

### Per agent, not per run

mcp_servers hangs off the Agent. In a handoff, the agent you hand off to needs its own reference or it will not have the mail tools.

### Raise the timeout for waiting

The params timeout defaults to 5 seconds. wait_for_reply can block for up to 300, so set a timeout above the wait you intend to use or the transport gives up first.

### Invalidate the cache when scopes change

With cache_tools_list=True the list is fetched once per connection. Narrow an OAuth grant and the agent keeps offering tools it can no longer call until you reconnect.


Docs: https://mcpmailer.com/docs.md