> ## Documentation Index
> Fetch the complete documentation index at: https://docs.mermail.app/llms.txt
> Use this file to discover all available pages before exploring further.

# MCP

> Connect AI assistants to Mermail over Streamable HTTP MCP with OAuth or an API key.

Mermail exposes a [Model Context Protocol](https://modelcontextprotocol.io) server that wraps the sold HTTP API. Assistants call the same workspace-scoped endpoints as authenticated clients — including usage, workspaces, mailboxes, email, agent conversations, and task triage.

## Endpoint

| Item      | Value                                                                     |
| --------- | ------------------------------------------------------------------------- |
| URL       | `https://console.mermail.app/mcp`                                         |
| Transport | **Streamable HTTP** (JSON-RPC over `POST`)                                |
| Auth      | **OAuth 2.1 Bearer** (interactive) or `x-api-key: sk-proj-…` (automation) |
| Methods   | `POST` only — `GET` / `DELETE` return `405`                               |

The server is **stateless**: there is no SSE subscription. Clients that expect long-lived SSE should use a Streamable HTTP–capable MCP host instead.

## Authentication

### OAuth (browser-parity)

MCP clients that support OAuth discover Mermail via Protected Resource Metadata, open the console authorize page, and receive a Bearer access token after the user signs in with Enoki (same as the web app) and picks a workspace. The consent UI shows a friendly client name (for example ChatGPT or Cursor), not the opaque `mcp_client_…` id.

| Item        | Value                                                                |
| ----------- | -------------------------------------------------------------------- |
| PRM         | `https://console.mermail.app/.well-known/oauth-protected-resource`   |
| AS metadata | `https://console.mermail.app/.well-known/oauth-authorization-server` |
| Scopes      | `mcp:tools`, `openid`, `offline_access`                              |

Unauthenticated calls return `401` with a `WWW-Authenticate` challenge pointing at the PRM document.

### API key (automation / CLI)

1. Create a workspace API key in **Settings → API Keys**. See [Authentication](/api-reference/authentication).
2. Send it on every MCP `POST` as `x-api-key`.
3. Cookie / console sessions alone are **rejected** for MCP.

Both auth modes scope tools to one workspace and consume that workspace’s **RPM** and **API credits**.

## Discover the server

```bash theme={null}
curl -sS https://console.mermail.app/.well-known/mcp/server-card.json | jq .
```

The card includes Streamable HTTP transport, **OAuth 2.1 and optional API-key** authentication, `serverInfo.description`, icons at `https://console.mermail.app/brand/icon-primary.png`, and the full tool list.

### Official MCP Registry

Mermail is published as **`app.mermail/mcp`** on the [Official MCP Registry](https://registry.modelcontextprotocol.io/v0/servers?search=app.mermail). Clients and aggregators (PulseMCP, Smithery, Glama, and others) discover remote Streamable HTTP servers from that feed.

| Item            | Value                                               |
| --------------- | --------------------------------------------------- |
| Registry name   | `app.mermail/mcp`                                   |
| Website         | [mermail.app/agents](https://mermail.app/agents)    |
| Ownership proof | `https://mermail.app/.well-known/mcp-registry-auth` |

The card includes OAuth and API-key authentication options, Streamable HTTP transport, icons/description metadata, and the full tool list.

<Tip>
  Prefer the URL and tool list from the live server card for your host. Do not hardcode a host if you deploy to a custom domain.
</Tip>

## Connect an assistant

Use the interactive guide at [mermail.app/agents](https://mermail.app/agents) for host-specific steps.

| Host                    | Auth                                                                                                         |
| ----------------------- | ------------------------------------------------------------------------------------------------------------ |
| Cursor, Claude, ChatGPT | **OAuth** — connect to `https://console.mermail.app/mcp` and complete browser consent (no API key in config) |
| Codex, OpenClaw         | **API key** — Streamable HTTP + `x-api-key`                                                                  |

**API-key** example:

```json theme={null}
{
  "mcpServers": {
    "mermail": {
      "url": "https://console.mermail.app/mcp",
      "headers": {
        "x-api-key": "sk-proj-YOUR_KEY"
      }
    }
  }
}
```

Exact config keys differ by host. The important parts are the `/mcp` URL and Streamable HTTP (not SSE).

For packaged workflows, install [Mermail Skills](/ai/skills) (`npx skills add Nudgen-Marketing/mermail-skills`) or connect via the registry id `app.mermail/mcp` when your host supports Official Registry install.

## How tools map to the API

Each tool (except `prepare_destructive_action`) maps to one sold API operation:

| Argument            | Use                                                                                                                                                                                                |
| ------------------- | -------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| Path params         | Top-level strings (`mailboxId`, `workspaceId`, …) matching the OpenAPI path. `mailboxId` accepts `public_id` (UUID), hosted alias id, or current email — prefer `public_id` from `list_mailboxes`. |
| `query`             | Optional object of query-string values                                                                                                                                                             |
| `body`              | Optional JSON body for `POST` / `PUT` / `PATCH`                                                                                                                                                    |
| `idempotencyKey`    | Optional; sent as `Idempotency-Key`                                                                                                                                                                |
| `confirmationToken` | Required on **destructive** tools (see below)                                                                                                                                                      |

Nest Sold API fields under the MCP `body` argument. If agents pass Sold fields flat at the top level (`to`, `subject`, `text`, …), Mermail folds them into `body`.

### Email write payloads

| Tools                                           | Content fields                                                                                                                                              |
| ----------------------------------------------- | ----------------------------------------------------------------------------------------------------------------------------------------------------------- |
| `send_email`, `reply_to_email`, `forward_email` | `html` and/or `text` (required one of them) plus required `from`. Aliases: string `body` or `content` → `text` (or `html` when the string looks like HTML). |
| `save_draft`, `schedule_email_send`             | String field `body` (HTML or text). Do **not** use `html`/`text` for drafts. Schedule also needs `scheduled_send_at`.                                       |

Validation failures return `code: "validation_failed"` with a `details` array of field paths (for example `body: Either 'html' or 'text' must be provided`) so agents can self-correct. Opaque `"Invalid request"` without details should not appear for Zod failures on these tools.

Server instructions: prefer read-only tools before writes. Responses are JSON text plus object-shaped `structuredContent`. JSON arrays are exposed as `{ "items": [...] }` so the result conforms to the MCP schema. Binary payloads (for example attachments) are capped at **1 MiB**; larger downloads should use the REST attachment endpoint.

## Destructive actions

Destructive tools (delete workspace/member/domain/email/folder/label/conversation/triager, bulk delete, empty trash, …) require a short-lived confirmation token:

1. Call `prepare_destructive_action` with:
   * `action` — the destructive tool name
   * `arguments` — the same arguments you will pass to that tool (without `confirmationToken`)
2. Receive `{ confirmationToken, expiresInSeconds }` (token prefix `mcp_confirm_`, TTL **5 minutes**, single-use, Redis-backed).
3. Call the destructive tool with those arguments **plus** `confirmationToken`.

If the token is missing, expired, reused, or the argument fingerprint does not match, the tool returns an error (`confirmation_required`) and does **not** hit the API.

<Warning>
  Confirmations require Redis. If Redis / cache is disabled, `prepare_destructive_action` fails with `503` `confirmation_unavailable`.
</Warning>

## Tool catalog

The live server exposes **63** tools: `prepare_destructive_action` + **62** API wrappers. Grouped by area:

<AccordionGroup>
  <Accordion title="Usage">
    `get_api_credit_usage`, `get_email_usage`
  </Accordion>

  <Accordion title="Workspaces & members">
    `list_workspaces`, `get_workspace`, `update_workspace`, `delete_workspace`, `get_workspace_storage`, `list_workspace_members`, `update_member_role`, `remove_workspace_member`, `invite_workspace_member`, `resend_workspace_invite`
  </Accordion>

  <Accordion title="Custom domains (Developer+)">
    `list_email_domains`, `add_email_domain`, `delete_email_domain`, `verify_email_domain`

    These hit Developer-gated REST paths. Free workspaces receive `403` when the tool runs.
  </Accordion>

  <Accordion title="Mailboxes">
    `list_workspace_mailboxes`, `list_mailboxes`, `create_mailbox`, `get_mailbox`, `update_mailbox_settings`, `get_mailbox_storage`
  </Accordion>

  <Accordion title="Emails, drafts, threads, folders, labels">
    `list_emails`, `send_email`, `get_email`, `update_email`, `delete_email`, `bulk_delete_emails`, `bulk_mark_emails_read`, `bulk_move_emails`, `move_email`, `reply_to_email`, `forward_email`, `download_attachment`, `save_draft`, `regenerate_draft`, `schedule_email_send`, `empty_trash`, `get_thread`, `mark_thread_read`, `list_folders`, `create_folder`, `update_folder`, `delete_folder`, `search_emails`, `list_custom_labels`, `create_custom_label`, `update_custom_label`, `delete_custom_label`
  </Accordion>

  <Accordion title="AI agent & task triage">
    `list_agent_conversations`, `create_agent_conversation`, `rename_agent_conversation`, `delete_agent_conversation`, `list_agent_messages`, `chat_with_mailbox_agent`, `list_task_triagers`, `create_task_triager`, `list_recent_triager_runs`, `update_task_triager`, `delete_task_triager`, `set_default_task_triager`, `get_or_create_triager_conversation`
  </Accordion>

  <Accordion title="Safety">
    `prepare_destructive_action` — issues confirmation tokens for destructive tools
  </Accordion>
</AccordionGroup>

Open-world tools (outbound email / invites / agent chat) are annotated `openWorldHint` for MCP clients that surface that signal.

For request/response shapes of each underlying HTTP route, use the [API Reference](/api-reference/overview).

## Related

<CardGroup cols={2}>
  <Card title="Skills" icon="puzzle-piece" href="/ai/skills">
    Install Mermail workflows in Codex, Claude Code, and Cursor.
  </Card>

  <Card title="Authentication" icon="key" href="/api-reference/authentication">
    Create and use `sk-proj-` API keys.
  </Card>

  <Card title="Discovery" icon="radar" href="/api-reference/discovery">
    Public discovery URLs including the MCP server card.
  </Card>
</CardGroup>