---
title: Use mailfloss from AI agents (MCP)
slug: mcp
docTags: 
createdAt: 2026-10-20T03:00:00.000Z
---

mailfloss runs a remote [MCP](https://modelcontextprotocol.io) server at
`https://api.mailfloss.com/mcp`. It exposes the v1 REST API as tools, so an AI
agent in Claude, ChatGPT, Cursor or any other MCP client can verify an address,
verify a list, or check your account in the middle of a task.

Every tool call is the equivalent REST call, made with your credentials. It has
the same org scoping, credits, rate limits and [error envelope](errors).

## Connect

There are two ways to authenticate: sign in with OAuth, or send an API key.

### Sign in (OAuth)

Add the server with no credentials. Your client opens a browser, you sign in to
the mailfloss dashboard, and you approve the connection.

```bash
claude mcp add --transport http mailfloss https://api.mailfloss.com/mcp
```

In Claude (web, desktop or mobile) or ChatGPT, add `https://api.mailfloss.com/mcp`
as a custom connector. Any MCP client that supports OAuth works the same way,
as long as its redirect URI is one we accept: a loopback address
(`http://localhost`, `http://127.0.0.1` or `http://[::1]`, any port) or the
callback of a supported client. Other clients can use an API key.

The connection acts as you, with your dashboard role's access. Access tokens last
one hour and refresh automatically. To disconnect a client, open
**Account Settings → Connected apps** and click **Disconnect**.

An MCP sign-in works only on `/mcp`, not on the REST API. To call the REST API
with OAuth, [build an app](build-an-app).

### API key

Send your API key as a Bearer token, exactly as for the REST API. Create a key
in the mailfloss dashboard under **Developers → API keys**.

**Claude Code**

```bash
claude mcp add --transport http mailfloss https://api.mailfloss.com/mcp \
  --header "Authorization: Bearer YOUR_API_KEY"
```

**Cursor**: add this to `~/.cursor/mcp.json`, or to the project's `.cursor/mcp.json`:

```json
{
  "mcpServers": {
    "mailfloss": {
      "url": "https://api.mailfloss.com/mcp",
      "headers": { "Authorization": "Bearer YOUR_API_KEY" }
    }
  }
}
```

Any client that supports MCP Streamable HTTP with custom headers works the same
way. The key must be in the `Authorization` header. A key in the URL doesn't
work: the client connects, but every tool call fails with `401`. A request with
no credential gets `401 Unauthorized`.

Send one JSON-RPC request per POST; batching isn't supported. Each POST counts
once against your API rate limit, and the REST call a tool makes doesn't count
again.

## Tools

| Tool                       | REST call                                            | Cost                                              |
| -------------------------- | ---------------------------------------------------- | ------------------------------------------------- |
| `verify_email`             | `GET /v1/verify`                                     | **1 credit** per call                             |
| `start_batch_verification` | `POST /v1/batch-verify`                              | **1 credit per email**                            |
| `get_batch_status`         | `GET /v1/batch-verify/{id}/status`                   | free                                              |
| `get_batch_results`        | `GET /v1/batch-verify/{id}/results`                  | free                                              |
| `cancel_batch`             | `POST /v1/batch-verify/{id}/cancel`                  | changes the account (refunds unprocessed credits) |
| `get_organization`         | `GET /v1/organization`                               | free                                              |
| `get_account`              | `GET /v1/account`                                    | free                                              |
| `list_integrations`        | `GET /v1/integrations`                               | free                                              |
| `get_integration`          | `GET /v1/integrations/{type}`                        | free                                              |
| `get_connection`           | `GET /v1/integrations/{type}/connections/{id}`       | free                                              |
| `connect_integration`      | `POST /v1/integrations/{type}/connections`           | changes the account                               |
| `update_settings`          | `PATCH /v1/integrations/{type}/connections/{id}`     | changes the account                               |
| `disconnect_integration`   | `DELETE /v1/integrations/{type}/connections/{id}`    | changes the account                               |
| `resync_integration`       | `POST /v1/integrations/{type}/connections/{id}/sync` | refreshes stored audiences                        |
| `test_integration`         | `POST /v1/integrations/{type}/connections/{id}/test` | free                                              |
| `get_usage_report`         | `GET /v1/reports/usage`                              | free                                              |
| `list_jobs`                | `GET /v1/jobs`                                       | free                                              |

Tools that spend credits or change the account say so in their description.
Read-only tools carry `readOnlyHint: true`. `verify_email` and
`resync_integration` carry `readOnlyHint: false`. `start_batch_verification`,
`cancel_batch`, `connect_integration`, `update_settings` and
`disconnect_integration` also carry `destructiveHint: true`. These annotations are
hints. Whether your client asks you to confirm a credit-spending or
account-changing call depends on its own permission settings, so check them
before you turn on auto-approval.

A tool's result is the REST response body. When the REST call fails, the tool
returns an error result whose text is the v1 error envelope. Branch on
`error.code` as you would with the REST API.

## Example prompts

- "Verify [sarah@example.com](mailto\:sarah@example.com) before I add her to the newsletter."
- "Verify these 40 addresses as a batch and tell me which ones are undeliverable."
- "How many credits do I have left this month?"
- "Is my Klaviyo integration still connected, and are its credentials still working?"

## Not yet supported

Keyword rules, webhooks, users, erasures, account updates, the activity
timeline and single-job details (`GET /v1/jobs/{id}`) have no tools yet. Use
the REST API for them.