# Alienmail MCP server (/guides/mcp-server)

Alienmail has a [Model Context Protocol](https://modelcontextprotocol.io) server. Connect it to an AI tool and the assistant can work with your workspace: list campaigns, add leads, check mailboxes and more. Sign in from the AI tool with your Alienmail account, or use an API key.

```txt
https://app.alienmail.io/api/mcp
```

<Callout type="info">
This is not the [docs MCP server](/ai-tools#docs-mcp-server). That one only reads this documentation and needs no key. This one acts on your account.
</Callout>

Building your own app or agent? See [Connect your own app](/guides/mcp-oauth) for the OAuth flow, the endpoints and the errors.

## Connect by signing in [#connect-by-signing-in]

Most AI tools can sign in to Alienmail for you (OAuth). You only need the server address; no key to create or paste.

1. Add `https://app.alienmail.io/api/mcp` as a connector in your AI tool (below).
2. When the tool asks, sign in to Alienmail in the browser window it opens.
3. Pick the workspace the tool may use (if you have more than one), check what it will be able to do, and choose **Allow**.

<Tabs items={["Claude","ChatGPT","Claude Code","Cursor"]}>
<Tab value="Claude">
In claude.ai or Claude Desktop, open **Settings → Connectors**, choose **Add custom connector**, enter `https://app.alienmail.io/api/mcp` and choose **Connect**. Leave the advanced settings (client ID and secret) empty.
</Tab>

<Tab value="ChatGPT">
In ChatGPT, open **Settings → Connectors** (developer mode), create a connector with the URL `https://app.alienmail.io/api/mcp` and authentication **OAuth**.
</Tab>

<Tab value="Claude Code">
```bash
claude mcp add --transport http alienmail https://app.alienmail.io/api/mcp
```

Then run `/mcp` in Claude Code and choose **Authenticate** for `alienmail`.
</Tab>

<Tab value="Cursor">
Add to `.cursor/mcp.json` in your project, or to `~/.cursor/mcp.json` for every project, then choose **Connect** next to the server in Cursor's MCP settings:

```json
{
  "mcpServers": {
    "alienmail": { "url": "https://app.alienmail.io/api/mcp" }
  }
}
```
</Tab>
</Tabs>

### What a connected app can do [#what-a-connected-app-can-do]

- It works in **the one workspace you picked**, as you, with **your role** in that workspace. It can never do more than you can, and it never sees your other workspaces.
- On the screen where you allow the app, each permission has a switch. Turn off the one for creating and changing things and the app only gets the tools that read (campaigns, leads, templates, mailboxes, analytics). Connected apps then shows it as **Read** only, without **Make changes**.
- `get_user_profile`, `list_workspaces` and `create_workspace` are not available to connected apps.
- To use an app with another workspace, connect it again and pick that workspace. Connecting the same app to the same workspace again replaces the earlier connection.
- See and disconnect connected apps in **Workspace settings → Integrations → Connected apps**. Owners and admins see every member's apps; other members see their own. A disconnected app stops at once.

The app gets an access token that lasts an hour and renews itself while you keep using it; after 90 days without use you sign in again. Only a fingerprint of each token is stored.

### When a connected app stops working [#when-a-connected-app-stops-working]

A connected app loses access, and asks you to sign in again, when:

- you or a workspace owner or admin disconnected it in **Connected apps**;
- you changed or reset your Alienmail password (this ends every app you connected, in every workspace);
- you left the workspace, or your account was suspended or deleted;
- the workspace was archived or deleted;
- the app wasn't used for 90 days.

To fix it, remove the Alienmail connector in the AI tool, add it again and sign in. If the sign-in screen says the link has expired, start again from the AI tool: the screen stays valid for 15 minutes and works once.

## Connect with an API key [#connect-with-an-api-key]

For tools that can't sign in, or for automation without a person, create an [API key](/authentication#api-keys) in **Workspace settings → Integrations** and send it in the `Authorization` header. The same page in Alienmail shows these snippets with your endpoint filled in.

<Tabs items={["Claude Code","Claude Desktop","Cursor","Other"]}>
<Tab value="Claude Code">
```bash
claude mcp add --transport http alienmail https://app.alienmail.io/api/mcp \
  --header "Authorization: Bearer YOUR_API_KEY"
```
</Tab>

<Tab value="Claude Desktop">
Add to `claude_desktop_config.json`:

```json
{
  "mcpServers": {
    "alienmail": {
      "command": "npx",
      "args": ["-y", "mcp-remote", "https://app.alienmail.io/api/mcp", "--header", "Authorization: Bearer YOUR_API_KEY"]
    }
  }
}
```
</Tab>

<Tab value="Cursor">
Add to `.cursor/mcp.json` in your project, or to `~/.cursor/mcp.json` for every project:

```json
{
  "mcpServers": {
    "alienmail": {
      "url": "https://app.alienmail.io/api/mcp",
      "headers": { "Authorization": "Bearer YOUR_API_KEY" }
    }
  }
}
```
</Tab>

<Tab value="Other">
Any client that supports remote MCP servers over Streamable HTTP can use `https://app.alienmail.io/api/mcp` with the header `Authorization: Bearer YOUR_API_KEY`. A client that supports OAuth for MCP can sign in instead, with only the address. For your own code, see [Connect your own app](/guides/mcp-oauth).
</Tab>
</Tabs>

<Callout type="warn" title="Send the key in a header">
Don't put the key in the URL. URLs end up in logs, proxies and browser history.
</Callout>

### What the key can do [#what-the-key-can-do]

An API key works in its own workspace only, and each tool needs the same permission as the matching action in Alienmail. The tool list your AI tool receives shows only the tools the key's role allows, so a read-only key is not offered tools that change anything. Calling a tool the role doesn't allow returns an error instead of a result.

Three tools work across workspaces and are not available to API keys: `get_user_profile`, `list_workspaces` and `create_workspace`.

## Tools [#tools]

| Area | Tools |
|---|---|
| Workspace | `get_workspace_credits`, `get_workspace_analytics` |
| Campaigns | `list_campaigns`, `get_campaign`, `create_campaign`, `update_campaign`, `duplicate_campaign`, `delete_campaign`, `start_campaign`, `toggle_campaign_status`, `update_campaign_settings` |
| Sequence and templates | `get_campaign_flow`, `list_templates`, `create_template`, `get_campaign_conditions`, `create_campaign_condition` |
| Leads | `list_leads`, `get_lead`, `add_lead_to_campaign`, `import_leads_csv`, `enroll_leads_in_campaign`, `bulk_enroll_leads`, `bulk_update_lead_status`, `get_lead_email_timeline`, `create_lead` (deprecated: use `add_lead_to_campaign`) |
| Mailboxes | `list_smtp_accounts`, `add_smtp_account`, `update_smtp_account`, `delete_smtp_account`, `test_smtp_connection` |

Your AI tool reads each tool's description and inputs from the server, so you don't need to copy them from here. Each tool also says whether it only reads, whether it deletes or can't be undone (deleting a campaign or a mailbox, changing many leads' status, starting a campaign), and whether it reaches outside Alienmail. Most AI tools use this to ask you before they run one that changes things.

## Limits [#limits]

Each API key, and each connected app, can make **60 tool calls per minute and 2,000 per day**. Over the limit, the tool call returns an error that says how long to wait.

Repeated requests with a wrong API key are also limited: after 30 in a minute from one IP address, the server answers `429` with a `Retry-After` header. The sign-in endpoints have their own limits, listed in [Connect your own app](/guides/mcp-oauth#limits).

## Try it [#try-it]

After connecting, ask for example:

- _"List my active Alienmail campaigns and how many leads each has."_
- _"Add ada@example.com to the Q1 outreach campaign."_
- _"Which of my mailboxes are disconnected?"_

<Callout type="warn">
The assistant acts on your real account. Give the key a role with only the access it needs (or connect the app read-only), and review what the assistant plans to do before it starts campaigns or changes leads.
</Callout>