<!-- Canonical: https://startupmail.dev/docs/mcp -->
<!-- Documentation index: https://startupmail.dev/llms.txt -->

# MCP for agents

> Give an agent narrowly scoped tools for listing, reading, sending, and replying to mailbox conversations.

## Endpoint and authentication

Startup Mail exposes a stateless Streamable HTTP MCP endpoint at:

```text
https://api.startupmail.dev/mcp
```

Use the same Bearer API key as the REST API. Available tools are determined when the connection is created from that key’s scopes.

## Configure a client

The exact configuration format depends on the MCP client. A typical HTTP entry needs the URL and authorization header:

```json
{
  "startupmail": {
    "type": "http",
    "url": "https://api.startupmail.dev/mcp",
    "headers": {
      "Authorization": "Bearer ${STARTUPMAIL_API_KEY}"
    }
  }
}
```

Do not paste a production key into a configuration file that will be committed or shared. Prefer environment-variable interpolation supported by your client.

## Available tools

| Tool               | Required scope   | Purpose                                             |
| ------------------ | ---------------- | --------------------------------------------------- |
| `list_mailboxes`   | `mailboxes:read` | See addresses available to the key                  |
| `list_threads`     | `mail:read`      | List recent threads for a mailbox and label         |
| `get_thread`       | `mail:read`      | Read a thread with messages and attachment metadata |
| `send_email`       | `mail:send`      | Start a conversation from an accessible mailbox     |
| `reply_to_message` | `mail:send`      | Continue a thread from a specific message           |

## Permission an agent safely

Create a dedicated key for one agent or workload. Start with read-only scopes, add `mail:send` only when the workflow needs it, and keep human approval around ambiguous or high-impact sends.

> **Scope is necessary, not sufficient**
>
> Your agent instructions and application should still restrict recipients, sending purpose, and
> when a human must approve. Startup Mail’s acceptable use policy applies to agent actions exactly
> as it does to human sends.
