# MCP: Connect an AI Assistant

The MailReach [Model Context Protocol](https://modelcontextprotocol.io) (MCP) server lets an AI assistant work on your project in plain language: check the reputation of your mailboxes, run spam tests, pause or reconnect inboxes, connect new ones. It works with Claude, ChatGPT, Claude Code, Codex, Cursor and any other MCP-capable client.

```plaintext
https://api.mailreach.co/mcp
```

Tip

**Fastest path:** open **Settings → API → Connected assistants** in your MailReach project. While nothing is connected, that block walks you through the setup for your assistant, with the URL and the commands ready to copy.

## Remote server

The server is hosted by MailReach: there is nothing to install or run. It speaks Streamable HTTP and authenticates with OAuth 2.1, so there is no client ID, secret or API key to paste. The assistant registers itself, sends you to a MailReach page where you pick the project and click **Allow**, and it is connected.

Pick your assistant:

### Claude

In Claude desktop or [claude.ai](https://claude.ai/settings/connectors), open **Settings → Connectors** and click **Add custom connector**. Name it **MailReach**, paste the URL and leave the client ID and secret empty. Click **Connect** and approve the project on the MailReach page.

### ChatGPT

Open **Settings → Connectors**. Under **Advanced**, turn on **Developer mode**, then **Create**. Name it **MailReach**, paste the URL, choose **OAuth** as authentication and create it. Approve the project on the MailReach page that opens.

### Claude Code

```bash
claude mcp add --scope user --transport http mailreach https://api.mailreach.co/mcp
```

`--scope user` registers the server for every project on your machine. Then run `claude`, type `/mcp` and pick **mailreach** to sign in.

### Codex

```bash
codex mcp add mailreach --url https://api.mailreach.co/mcp
codex mcp login mailreach
```

The second command opens the MailReach consent page.

### Cursor

Open **Cursor Settings → Tools & MCP → Add custom MCP** and add the server to `mcp.json`:

```json
{
  "mcpServers": {
    "mailreach": {
      "url": "https://api.mailreach.co/mcp"
    }
  }
}
```

Back in the MCP list, MailReach asks to sign in: your browser opens the consent page.

### Other clients

Add a **remote (HTTP) MCP server** with the URL above and **OAuth** authentication. The client discovers the authorization server from `/.well-known/oauth-protected-resource`, registers dynamically (RFC 7591) and runs the same consent flow. PKCE with `S256` is required. Clients that run in a browser are not supported: the endpoint answers no CORS preflight.

## Authentication

### OAuth (recommended)

The consent flow above connects the assistant **as you**. A connection is bound to one person, one project and one assistant:

* It acts with **your role** on that project and cannot reach your other projects.
* It **expires 30 days** after consent. Access tokens are short-lived and refreshed silently until then; afterwards the assistant asks you to connect again.
* You can **end it at any time** from **Settings → API → Connected assistants**, where every connection is listed with who approved it and when it was last used. Owners, admins and managers see and can revoke every connection; a member sees their own.
* Two-factor authentication applies if it is on for your account.

### API key

Some agent platforms cannot run an OAuth flow and only pass static headers. In that case, authenticate with a project API key, created in **Settings → API** with the scopes you want the agent to have:

```plaintext
Authorization: Bearer mr_live_...
```

With Groq's remote MCP support, for example:

```json
{
  "type": "mcp",
  "server_label": "mailreach",
  "server_url": "https://api.mailreach.co/mcp",
  "headers": { "Authorization": "Bearer mr_live_..." }
}
```

Or with Claude Code, skipping the sign-in step:

```bash
claude mcp add --scope user --transport http mailreach https://api.mailreach.co/mcp \
  --header "Authorization: Bearer mr_live_..."
```

An API key connection has no person attached: its actions are logged under the project with the key as actor, exactly like REST calls made with that key. See the [Quickstart](/) for how API keys and scopes work.

## Tools

The tools a connection gets are exactly what your role, or your key's scopes, allow. Scopes are the same as for the REST API. Tools outside your permissions are not listed to the assistant at all.

### Project

| Tool                 | Scope            | Description                                                          |
| -------------------- | ---------------- | -------------------------------------------------------------------- |
| `get_project`        | –                | Project overview: credits, seats, and what this connection may do    |
| `get_project_stats`  | `accounts:stats` | Aggregated daily inbox, spam and categories numbers across mailboxes |
| `list_notifications` | `accounts:read`  | Open alerts on the project                                           |
| `list_tags`          | `accounts:read`  | Tags and their average reputation                                    |

### Mailboxes

| Tool                      | Scope             | Description                                                                              |
| ------------------------- | ----------------- | ---------------------------------------------------------------------------------------- |
| `list_accounts`           | `accounts:read`   | Connected mailboxes with reputation, status and warming settings; search and tag filters |
| `get_account`             | `accounts:read`   | One mailbox in detail: score history, daily stats, open alerts, SPF/DKIM/DMARC           |
| `update_account_settings` | `accounts:write`  | Sender name, signature, time zone, ramp-up, max conversations, autopilot                 |
| `pause_account`           | `accounts:write`  | Pause a mailbox                                                                          |
| `resume_account`          | `accounts:write`  | Resume a paused mailbox                                                                  |
| `reconnect_account`       | `accounts:write`  | Retry a mailbox whose status is `disconnected`                                           |
| `remove_account`          | `accounts:delete` | Disconnect a mailbox for good. Requires an explicit confirmation                         |

### Spam tests

| Tool               | Scope             | Description                                                              |
| ------------------ | ----------------- | ------------------------------------------------------------------------ |
| `list_spam_tests`  | `spamtests:read`  | Spam tests, paginated                                                    |
| `get_spam_test`    | `spamtests:read`  | Full result of a spam test: placement per provider, score, warnings      |
| `create_spam_test` | `spamtests:write` | Starts a spam test and returns the seed list to send to. Uses one credit |

### Connecting mailboxes

| Tool                        | Scope                    | Description                                                                                     |
| --------------------------- | ------------------------ | ----------------------------------------------------------------------------------------------- |
| `connect_account`           | `accounts:write`         | Connect a mailbox with an app password (Google Workspace, Gmail, Outlook) or IMAP/SMTP settings |
| `get_mailbox_connect_link`  | `accounts:write`         | The dashboard page to connect a mailbox yourself, for a Microsoft 365 sign-in                   |
| `list_email_workspaces`     | `email_workspaces:read`  | The Google Workspace and Microsoft 365 credentials used for batch connections                   |
| `create_email_workspace`    | `email_workspaces:write` | Create one from a Google service account key or a Microsoft app registration                    |
| `import_workspace_accounts` | `email_workspaces:write` | Batch-connect mailboxes through a workspace                                                     |
| `get_import_task`           | `email_workspaces:read`  | Progress and errors of a background import                                                      |

A connection cannot change billing, manage API keys or team members, or access other projects. Mailbox passwords, OAuth tokens and API keys never appear in a tool result.

## Security best practices

* **Grant the least you need.** Connect from an account whose role matches what you want the assistant to do, or use an API key limited to read scopes when the assistant only has to report. A member role has no deletion rights.
* **Keep a human in the loop for destructive actions.** `remove_account` requires an explicit confirmation and the assistant is instructed to ask you first. Say so in your own instructions too if your assistant supports them.
* **Enter credentials in the dashboard when you can.** When you ask an assistant to connect a mailbox, the app password or service account key transits through it. MailReach encrypts it on arrival, never returns it and redacts it from the security log, but `get_mailbox_connect_link` lets you type it in the dashboard instead.
* **Review the security log.** Every call is recorded with the assistant's name, the person behind it and the tool used, exactly like actions taken from the dashboard.
* **Revoke what you no longer use.** Connections end after 30 days on their own; end them earlier from **Connected assistants**. Leaving the project, a password reset or "sign out everywhere" also cut every connection immediately.

## Example prompts

* "Which of my mailboxes have a reputation below 80, and what changed this week?"
* "Run a spam test and tell me where the email landed once it is done."
* "Pause every mailbox tagged `Q3 outreach`."
* "Connect `alice@acme.com` with this app password, then warm it up at 20 emails a day."
* "Import all mailboxes of our Google Workspace into this project, spam-test only."

## Troubleshooting

| Symptom                              | Cause                                                                          | What to do                                         |
| ------------------------------------ | ------------------------------------------------------------------------------ | -------------------------------------------------- |
| The assistant says a tool is unknown | Your role, or the key's scopes, do not include it                              | Ask an owner or admin, or use the dashboard        |
| The assistant asks to connect again  | The 30-day connection ended, or it was revoked                                 | Approve it again from the assistant                |
| "Access token has been revoked"      | The connection was ended from the dashboard, or your sessions were invalidated | Connect again                                      |
| A mailbox refuses to connect         | Wrong app password or IMAP/SMTP settings                                       | Check the values, or connect it from the dashboard |

The MCP endpoint shares the API's [rate limits](/rate-limits). Long operations such as a batch import run in the background: the assistant gets a task to poll with `get_import_task`.