Lumail's Model Context Protocol (MCP) server lets an AI assistant read and manage organization-scoped subscribers, campaigns, Workflows, tags, segments, settings, and analytics.

The tool catalog is generated from the same definitions used by Lumail's in-app agent, CLI, SDK, and Tools API. Use MCP tool discovery as the source of truth instead of relying on a fixed tool count.

## Choose an endpoint

| Client                                  | Endpoint                        | Authentication         | Safety profile                                         |
| --------------------------------------- | ------------------------------- | ---------------------- | ------------------------------------------------------ |
| ChatGPT and Codex                       | `https://lumail.io/mcp`         | Lumail OAuth           | Curated read and draft-write catalog                   |
| Claude, Cursor, and trusted MCP clients | `https://lumail.io/api/mcp/sse` | Organization API token | Full organization tool catalog with confirmation gates |

The OAuth endpoint cannot send, publish, schedule, delete, archive, or unsubscribe. Follow the [ChatGPT and Codex guide](/docs/ai-integration/chatgpt-plugin) for that setup.

The API-token endpoint is intended for trusted clients that need the wider catalog. Every request remains scoped to the organization that owns the token.

## Connect with an API token

Create a token from **Settings → API Tokens**, then add the Streamable HTTP endpoint to your client:

```json
{
  "mcpServers": {
    "lumail": {
      "url": "https://lumail.io/api/mcp/sse",
      "headers": {
        "Authorization": "Bearer lum_your_api_token_here"
      }
    }
  }
}
```

For a stdio-only client, use an HTTP bridge:

```json
{
  "mcpServers": {
    "lumail": {
      "command": "pnpm",
      "args": [
        "dlx",
        "mcp-remote",
        "https://lumail.io/api/mcp/sse",
        "--header",
        "Authorization: Bearer lum_your_api_token_here"
      ]
    }
  }
}
```

Restart the MCP client after changing its configuration.

## Discover resources

After authentication, the server advertises the MCP `resources` capability. Use `resources/list` and `resources/read` to retrieve:

- **Lumail developer and agent start** (`https://lumail.io/`, `text/markdown`) - concise product capabilities and canonical MCP, REST, SDK, CLI, support, and documentation links
- **Lumail OpenAPI 3.1 specification** (`https://lumail.io/openapi.json`, `application/json`) - typed REST operations, bearer authentication, request schemas, response schemas, and structured errors

Every returned URI also resolves over ordinary HTTPS. Resource content is public developer documentation; organization data remains available only through authenticated tools.

## Discover tools dynamically

MCP clients receive the current tool names, descriptions, input schemas, and safety annotations during discovery. The same catalog is available over REST:

```bash
curl https://lumail.io/api/v2/tools \
  -H "Authorization: Bearer lum_your_api_token_here"
```

The `v2` in `/api/v2/tools` is the Tools API version. Workflow tool names are canonical and unversioned.

## Canonical Workflow tools

Lumail has one supported graph-based Workflow engine. Its MCP tools operate on editable drafts, immutable published versions, subscriber runs, goals, exits, and mutual-exclusion groups.

| Area            | Tools                                                                                                                                         |
| --------------- | --------------------------------------------------------------------------------------------------------------------------------------------- |
| Read and create | `list_workflows`, `get_workflow`, `create_workflow`                                                                                           |
| Draft graph     | `configure_workflow_draft`, `update_workflow_draft`                                                                                           |
| Lifecycle       | `publish_workflow`, `update_workflow_status`, `delete_workflow`                                                                               |
| Enrollment      | `add_subscriber_to_workflow`, `add_subscribers_to_workflow`, `remove_subscriber_from_workflow`                                                |
| Runs            | `get_subscriber_workflow_runs`, `fast_forward_workflow_subscriber`                                                                            |
| Groups          | `list_workflow_groups`, `get_workflow_group`, `create_workflow_group`, `update_workflow_group`, `set_workflow_group`, `delete_workflow_group` |

There are no version-suffixed Workflow tools and no step-by-step mutation tools. A Workflow draft is configured as one complete `{ steps, edges }` graph.

### Safe draft flow

1. Call `get_skill` with `{ "type": "workflow" }`.
2. Use `list_workflows` or `create_workflow` to identify the target.
3. Call `get_workflow` immediately before editing and keep its exact `updatedAt`.
4. Resolve referenced tags, senders, snippets, campaigns, fields, goals, and groups with read tools.
5. Call `configure_workflow_draft` once with the complete steps and edges plus `expectedUpdatedAt`.
6. Read the Workflow back, inspect every configured internal email with `get_campaign`, and verify each render with `render_campaign`.

`configure_workflow_draft` creates or updates the internal `WORKFLOW` campaign owned by each EMAIL step. Do not call `create_campaign` for Workflow emails and do not attach broadcast campaigns directly.

Draft configuration never publishes or sends. Publishing and activation are separate, confirmation-gated actions.

## Tool categories

The full catalog also includes tools for:

- Subscribers, composed filters, tags, and custom fields
- Campaign drafting, rendering, history, scheduling, and analytics
- Segments and organization analytics
- Email senders, domains, deliverability, and suppression management
- Snippets, variables, images, imports, and exports
- Transactional email and web content retrieval

Use `get_skill` before specialized operations such as Workflow graph configuration or email copywriting. Pass `{ "type": "docs" }` to list every product docs page, then `{ "type": "docs", "page": "<slug>" }` to read one. Use the schema returned by discovery rather than guessing parameter names.

## Confirmation gates

High-impact tools use a two-call confirmation flow. The first call returns `CONFIRMATION_REQUIRED` with a five-digit `confirmationCode`. Show the proposed action to the user, then repeat the exact same tool call with that code within five minutes.

Confirmation-gated actions include sending or scheduling email, publishing or activating a Workflow, destructive deletion, archiving, and unsubscribe operations. The tool's annotations and first response are authoritative for the current catalog.

Codes are single-use, expire after five minutes, and are bound to the organization, tool, and exact input.

## Operating rules

- Read the current resource immediately before changing it.
- Create campaigns and Workflows as drafts first.
- Never send, publish, activate, schedule, archive, unsubscribe, or delete without explicit user intent.
- Preserve `updatedAt` values for optimistic-concurrency operations.
- Use `edit_campaign` for campaign changes and `configure_workflow_draft` for complete Workflow graphs.
- Read back every mutation before reporting success.
- Keep API tokens secret and out of browser-side code, logs, and prompts.
- Respect organization rate limits and retry `429` responses with backoff.

## Example prompts

```text
Create a welcome Workflow draft with three emails over seven days.
Keep it unpublished, then show me the rendered text and links for every email.
```

```text
List my paused Workflows and explain which published version each one uses.
Do not activate anything.
```

```text
Add the subscriber alex@example.com to the active onboarding Workflow.
Show me the exact action before requesting confirmation.
```

## Troubleshooting

**Tools do not appear:** restart the MCP client, verify the endpoint, and confirm that the token belongs to the intended organization.

**Unauthorized:** create a new organization API token or reconnect the OAuth integration.

**Workflow changed since it was read:** call `get_workflow` again, merge intentionally, and retry with the new `updatedAt`.

**Confirmation required:** repeat the same call with the returned code. Changing another input creates a different confirmation challenge.

## Related

- [Workflow guide](/docs/workflows/workflow)
- [Tools API](/docs/ai-integration/tools-api)
- [Tools API reference](/docs/api-reference/v2-tools)
- [Claude MCP setup](/docs/ai-integration/mcp-claude)
- [Cursor MCP setup](/docs/ai-integration/mcp-cursor)
- [API tokens](/docs/api-reference/api-tokens)