# Cloudflare Agents SDK and MCPmailer

Agents built on the Cloudflare Agents SDK add MCPmailer as an MCP client connection.

Agents SDK has a built-in MCP client. One addMcpServer call and your Durable Object agent has an inbox.

## Setup

1. **Create a mailbox** One per agent, so its address and its key are the same identity.
1. **Put the key in a secret** wrangler secret put MCPMAILER_KEY, so it is not in your config.
1. **Connect once, not per request** addMcpServer in onStart; the connection is part of the agent state.
1. **Deploy** The Durable Object keeps the connection across requests and hibernation.

## Install

```bash
npm install agents
```

## Agents SDK

```ts
await this.addMcpServer('mcpmailer', 'https://connect.mcpmailer.com/mcp', {
  transport: {
    type: 'streamable-http',
    headers: { Authorization: 'Bearer mmk_live_...' }
  }
});
```

## Connect on start, then use the tools

Headers go inside transport. Passed at the top level they are silently dropped, and every call reaches us unauthenticated.

```ts
import { Agent } from 'agents';

export class SupportAgent extends Agent<Env> {
  async onStart() {
    await this.addMcpServer('mcpmailer', 'https://connect.mcpmailer.com/mcp', {
      transport: {
        type: 'streamable-http',
        headers: { Authorization: `Bearer ${this.env.MCPMAILER_KEY}` }
      }
    });
  }

  async onRequest(request: Request) {
    const { tools } = this.getMcpServers();
    return Response.json({ tools: tools.length });
  }
}
```

## Worth knowing

### Headers belong under transport

The third argument is an options object. An older signature took callbackHost as a bare third argument, so { headers } at the top level is accepted and then ignored.

### Connect in onStart

Calling addMcpServer per request reconnects every time. onStart runs once per Durable Object instance, which is the lifetime you want.

### We use a bearer key, so no OAuth callback

addMcpServer can return state "authenticating" with an authUrl for servers that need OAuth. With a key you get "ready" straight away and never handle the redirect.


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