# MCP email server reference and tools

> Connect any MCP client to the Trotta Mail server over Streamable HTTP, with an API key or OAuth. The tools an agent gets to read, send, reply and draft.

Source: https://trotta.email/docs/mcp

Trotta Mail speaks the Model Context Protocol, so an agent in an MCP client can use its inbox as tools.

## Connect

The server is at `https://api.trotta.email/mcp`. It uses Streamable HTTP and it is stateless. It takes the same bearer key as the REST API, or an assistant signs in with OAuth: see [Connect ChatGPT, Claude and other assistants](https://trotta.email/docs/connect). A session cookie is ignored.

MCP client configuration:

```json
{
  "mcpServers": {
    "trotta-mail": {
      "url": "https://api.trotta.email/mcp",
      "headers": { "Authorization": "Bearer tm_live_..." }
    }
  }
}
```

Need a key first? [Sign the agent up](https://trotta.email/docs#get-an-inbox) with one call.

## Tools

| Tool | What it does |
| --- | --- |
| `create_inbox` | Creates an inbox and returns its address. |
| `list_inboxes` | Lists the inboxes the key can reach. |
| `list_messages` | Lists messages in an inbox. |
| `get_inbox_updates` | What is new since a time, ranked, each with a one-line reason. |
| `read_message` | Reads one message in the safe view. |
| `wait_for_message` | Waits for the next delivered message, with the same filters as the REST call. |
| `send_message` | Sends a new message. Screened before it leaves. With send_at, schedules it. |
| `reply_to_message` | Replies in the thread. With send_at, schedules the reply. |
| `cancel_scheduled_message` | Stops a scheduled message. It goes back to drafts. |
| `create_draft` | Leaves a draft for a human to read and send. Works where the inbox allows drafts. |
| `thread_context` | Returns a thread as model-ready text with a trust level. Earlier messages come as their new part only. |
| `read_attachment_text` | Reads the text inside a PDF, Word, Excel, PowerPoint or OpenDocument file, instructions taken out. |
| `answer_invitation` | Accepts, declines or tentatively accepts a calendar invitation. |
| `list_held` | Lists what is waiting on a human. |
| `scan_content` | Runs any content through the guard and returns the verdict. |

Every tool runs through the same checks as the REST route behind it. Results are the safe view, even with a `mail:full` key. Held mail is withheld. Tools take ids only: an argument that is not an id is refused before any request is made.

In a human's inbox an agent starts with drafts only: `send_message` and `reply_to_message` answer `403 agent_drafts_only`, and `create_draft` is the way through. Login mail is sealed there: no tool returns it. See the [security model](https://trotta.email/docs/security#agent-writes).

A tool call:

```json
{
  "name": "wait_for_message",
  "arguments": { "inbox_id": "inb_7Qh2mXc4", "has_code": true, "timeout": 60 }
}
```

## Email sending

Each key and each connected app has a setting for the tools that send: `send_message`, `reply_to_message` and `answer_invitation`. Change it in the console, under [API keys](https://trotta.email/console/keys) or [Connected apps](https://trotta.email/console/apps), or with `PATCH /v1/keys/{id}` and `send_mode`.

| Setting | What the client sees |
| --- | --- |
| Ask before every email (`ask`, the default) | The tools are marked `destructiveHint: true`, so the client asks before each send. |
| Don't send email (`off`) | The tools are left out, and a call to one answers `sending_off`. Use `create_draft`. |
| Send without asking (`auto`) | The tools are marked `destructiveHint: false`, so the client may let you allow them once. |

It only narrows what a connection can do. Mail is screened before it leaves in every mode, and the inbox's own rules and limits still apply. A change takes effect on the next request; a client may keep its tool list for up to a minute.
