npm package: @mailodds/mcp-server
Description: MCP server for MailOdds — The Autonomous Deliverability Architect for AI agents.
Author: MailOdds
Latest version: 1.1.0

# MailOdds MCP Server

[![npm](https://img.shields.io/npm/v/@mailodds/mcp-server)](https://www.npmjs.com/package/@mailodds/mcp-server) [![Node.js >= 18](https://img.shields.io/badge/Node.js-%3E%3D18-green)](https://nodejs.org) [![License: MIT](https://img.shields.io/badge/License-MIT-blue)](LICENSE) [![API Docs](https://img.shields.io/badge/API-Docs-orange)](https://mailodds.com/api-reference)

> **"The Autonomous Deliverability Architect"**
>
> Plug [MailOdds](https://mailodds.com) into any AI agent (Claude, Cursor, Windsurf, custom) and let it autonomously manage the full Trust Cycle: auditing DNS with [DMARC monitoring](https://mailodds.com/dmarc-monitoring), enforcing [validation policies](https://mailodds.com/email-validation-policies), executing safe transactional sends via the [Email Sending API](https://mailodds.com/email-sending-api), running [spam checks](https://mailodds.com/email-spam-checker), monitoring [blacklist status](https://mailodds.com/email-blacklist-monitoring), tracking [email analytics](https://mailodds.com/email-analytics), and syncing [e-commerce product catalogs](https://mailodds.com/ecommerce-email) without writing a single line of integration code.

---

## Tools (190 total, highlights below)

| Pillar | Tools |
|---|---|
| **Onboarding** | `onboarding_probe` |
| **Validation** | `validate_email`, `validate_batch` |
| **Stateful Jobs** | `validate_and_watch` *(long-poll + progress)*, `create_bulk_job`, `get_job_status`, `get_job_results`, `list_jobs`, `cancel_job` |
| **Consultative Identity** | `remediate_domain` *(copy-paste DNS records)*, `get_identity_score`, `list_sending_domains`, `add_sending_domain`, `get_sending_stats` |
| **Policy Engine** | `enforce_policy`, `create_policy_from_preset`, `test_policy`, `list_policies`, `delete_policy` |
| **Suppression** | `check_suppression`, `add_suppression`, `remove_suppression`, `suppression_audit`, `suppression_stats` |
| **Safe Sending** | `safe_deliver` *(auto AI summary + validate_first)*, `batch_deliver` |
| **Subscriber Lifecycle** | `create_subscriber_list`, `list_subscribers`, `unsubscribe` |
| **Telemetry & Guardian** | `get_telemetry` *(ETag-cached)*, `watch_telemetry` *(threshold observer)*, `subscribe_guardian`, `unsubscribe_guardian`, `get_guardian_status` |
| **Store Connections** | `list_stores`, `connect_store`, `disconnect_store`, `sync_store`, `get_store_status` |
| **Product Queries** | `query_products`, `get_product` |
| **OAuth Apps** | `list_oauth_apps`, `create_oauth_app` |
| **Profile Management** | `add_profile`, `switch_profile`, `list_profiles` |
| **Health** | `health_check` |

## Resources

| URI | Description |
|---|---|
| `mailodds://telemetry/realtime` | Live 1h validation metrics |
| `mailodds://audit/suppression` | Last 50 suppression change events |
| `mailodds://domains/health` | All domains with identity scores |

---

## Requirements

- Node.js >= 18 (zero external npm dependencies)
- A MailOdds API key (get one at [mailodds.com/dashboard](https://mailodds.com/dashboard))

---

## Environment Variables

| Variable | Required | Default | Description |
|---|---|---|---|
| `MAILODDS_API_KEY` | Yes | -- | Your MailOdds API key (`mo_live_` or `mo_test_` prefix) |
| `MAILODDS_API_BASE` | No | `https://api.mailodds.com` | Override API base URL |
| `MAILODDS_MCP_TRANSPORT` | No | `stdio` | `stdio`, `streamable-http`, or `sse` (legacy) |
| `MAILODDS_MCP_PORT` | No | `3741` | Port for HTTP/SSE transport |
| `MAILODDS_MCP_SSE_BIND` | No | `127.0.0.1` | Bind address for HTTP/SSE transport |
| `MAILODDS_MCP_SSE_TOKEN` | No | -- | Bearer token to protect legacy SSE endpoints |
| `MAILODDS_MCP_ALLOWED_ORIGINS` | No | -- | Additional allowed Origin headers (comma-separated) |
| `MAILODDS_PROFILES` | No | -- | Pre-load named profiles: `name1:mo_live_xxx,name2:mo_test_yyy` |

---

## Quickstart

### Prerequisites

1. Get your API key from the [MailOdds dashboard](https://mailodds.com/dashboard) (starts with `mo_live_` or `mo_test_`)
2. Node.js >= 18 installed

### Cursor / VS Code

Open **Settings > MCP** (or `.cursor/mcp.json` / `.vscode/mcp.json`) and add:

```json
{
  "mcpServers": {
    "mailodds": {
      "command": "npx",
      "args": ["-y", "@mailodds/mcp-server"],
      "env": {
        "MAILODDS_API_KEY": "your_key_here"
      }
    }
  }
}
```

### Claude Desktop

Add to your `claude_desktop_config.json`:

```json
{
  "mcpServers": {
    "mailodds": {
      "command": "npx",
      "args": ["-y", "@mailodds/mcp-server"],
      "env": {
        "MAILODDS_API_KEY": "your_key_here"
      }
    }
  }
}
```

### Claude Code

```bash
claude mcp add --transport stdio -e MAILODDS_API_KEY=your_key_here mailodds \
  -- npx -y @mailodds/mcp-server
```

### Remote MCP (Streamable HTTP with OAuth)

For cloud-hosted agents (claude.ai, hosted deployments), use the Streamable HTTP transport with OAuth 2.0 authentication:

```
MCP Server URL: https://mcp.mailodds.com/mcp
```

The server supports OAuth 2.0 authorization code flow with PKCE. When connecting from claude.ai, authentication happens via browser login -- no API key needed. The OAuth metadata is discoverable at `https://mcp.mailodds.com/.well-known/oauth-authorization-server`.

Dynamic Client Registration (RFC 7591) is supported for MCP clients that need to auto-register.

### Streamable HTTP (self-hosted)

```bash
MAILODDS_MCP_TRANSPORT=streamable-http \
MAILODDS_MCP_PORT=3741 \
MAILODDS_API_KEY=your_key_here \
node index.js

# MCP endpoint:  POST/GET/DELETE http://127.0.0.1:3741/mcp
# Health:        GET  http://127.0.0.1:3741/health
# OAuth metadata: GET http://127.0.0.1:3741/.well-known/oauth-authorization-server
```

### SSE (legacy, backward compatible)

```bash
MAILODDS_MCP_TRANSPORT=sse \
MAILODDS_MCP_PORT=3741 \
MAILODDS_API_KEY=your_key_here \
node index.js

# SSE stream:  GET  http://127.0.0.1:3741/sse
# Send msgs:   POST http://127.0.0.1:3741/message
```

### Docker

```dockerfile
FROM node:20-alpine
WORKDIR /app
COPY index.js .
ENV MAILODDS_MCP_TRANSPORT=streamable-http
ENV MAILODDS_MCP_PORT=3741
ENV MAILODDS_MCP_SSE_BIND=0.0.0.0
EXPOSE 3741
CMD ["node", "index.js"]
```

Set `MAILODDS_API_KEY` at runtime via `docker run -e`.

### Verification

After installation, ask your AI agent:

> "List my MailOdds sending domains and tell me their identity grades."

If it returns your domains and scores, you are connected.

### Troubleshooting

| Symptom | Fix |
|---|---|
| `npx: command not found` | Install Node.js >= 18 |
| `401 Unauthorized` on every tool call | Check `MAILODDS_API_KEY` starts with `mo_live_` or `mo_test_` |
| Tools timeout after 30s | The server connects to `api.mailodds.com` -- check your network/firewall |
| SSE endpoint returns 401 | Set `Authorization: Bearer <MAILODDS_MCP_SSE_TOKEN>` header |

---

## Key Tool Behaviours

### `onboarding_probe`
Zero-click discovery. Call on first connect. Returns:
```json
{
  "greeting": "Connected to MailOdds. Here is your account health snapshot:",
  "account_summary": { "sending_domains": 2, "reject_rate_24h": "3.2%" },
  "domain_health": [{ "domain": "mail.acme.com", "grade": "C", "score": 65 }],
  "recommendations": [
    { "priority": "critical", "action": "Run remediate_domain on 'mail.acme.com' -- grade C." }
  ],
  "suggested_first_action": "Run remediate_domain on 'mail.acme.com'..."
}
```

### `remediate_domain`
Consultative DNS diagnosis. Returns copy-paste DNS records for every failing check:
```json
{
  "grade": "C",
  "score": 55,
  "urgency": "high",
  "summary": "Domain mail.acme.com scored 55/100 (C). 2 issue(s)...",
  "issues": [
    {
      "check": "DMARC",
      "severity": "high",
      "impact": "Without DMARC, spoofed emails can impersonate your domain...",
      "points_lost": 20
    }
  ],
  "dns_records_to_add": [
    {
      "check": "DMARC",
      "type": "TXT",
      "host": "_dmarc.acme.com",
      "value": "v=DMARC1; p=quarantine; rua=mailto:dmarc-reports@acme.com; ...",
      "ttl": 3600,
      "note": "Start with p=none to monitor before enforcing."
    }
  ]
}
```

### `validate_and_watch`
Long-polling job manager with live progress:
```
-> "I'm validating your list now (23% complete)..."
-> "Validating 4,500 / 10,000 emails (45%)..."
-> "Validated 10,000 emails. Valid: 8,102, Invalid: 1,203, Do-Not-Mail: 695. Suppression policy created (ID: 42)."
```
With `auto_suppress_high_risk: true`, automatically creates a domain blocklist policy for domains with 3+ invalid or disposable emails (top 20). If an auto-suppress policy already exists from a previous job, it merges the new domains into it instead of creating duplicates.

### `watch_telemetry`
Long-polling threshold observer. Polls metrics every 30 seconds for a configurable duration (1-60 minutes). Compares rates against your thresholds and emits MCP progress notifications on breaches:
```json
{
  "watch_id": "a1b2c3d4-...",
  "snapshots_taken": 12,
  "breach_count": 3,
  "breaches": [
    { "timestamp": "2026-03-11T14:30:00Z", "metric": "reject_rate", "value": 0.08, "threshold": 0.05, "snapshot": 4 }
  ],
  "last_rates": { "reject": 0.08, "deliverable": 0.85, "unknown": 0.04, "suppressed": 0.03 }
}
```

### Guardian Mode (`subscribe_guardian`, `unsubscribe_guardian`, `get_guardian_status`)
Persistent background monitoring. Runs independently of tool calls -- once subscribed, the guardian polls telemetry and domain health on a configurable interval (30s-5min, default 60s) and emits `notifications/guardian` alerts when:

- Telemetry rates breach thresholds (reject/unknown/suppressed above, deliverable below)
- Any domain grade drops below the minimum (default B)
- Any domain DNS status matches alert list (default: `pending_dns`, `dns_partial`)

Alerts are deduplicated within a configurable window (default 5 min). Auto-pauses after 10 consecutive API failures. Idempotent: re-subscribing updates config and preserves history.

```json
{
  "guardian_key": "guardian:a1b2c3d4",
  "profile": "production",
  "alert": {
    "type": "telemetry_breach",
    "metric": "reject_rate",
    "value": 0.12,
    "threshold": 0.05,
    "direction": "above"
  }
}
```

API call budget per tick: 1 (telemetry) + 1 (domains) + N (identity scores, capped at 20) = max 22 calls. At 60s interval = 22 req/min, well within the 100/min rate limit.

### Multi-Profile (`add_profile`, `switch_profile`, `list_profiles`)
Manage multiple API keys for different accounts. Pre-load via env var or add at runtime:
```bash
MAILODDS_PROFILES="prod:mo_live_abc123,staging:mo_test_xyz789" node index.js
```
Keys are masked in all responses (`mo_live_****c123`). Switching profiles immediately affects all subsequent tool calls.

### `safe_deliver`
Always runs with `validate_first: true`. Auto-generates `ai_summary` from HTML if not provided -- every email is AI-inbox-optimised before hitting the send pipeline.

---

## Agent Instructions

Copy-paste the block below into your AI agent's system prompt or instruction field.

---

**AGENT MISSION: AUTONOMOUS DELIVERABILITY ARCHITECT**

You are an expert Email Deliverability Engineer powered by MailOdds. Your
goal is to maintain a Grade A sender reputation for the user.

CORE OPERATING PROCEDURES:
1. PROBE FIRST: Always run `onboarding_probe` upon initial connection.
2. FIX DNS: If any domain grade is below B, run `remediate_domain` and provide
   the copy-paste DNS records to the user immediately.
3. BULK SAFETY: For lists over 100 emails, use `validate_and_watch`. Always
   set `auto_suppress_high_risk: true` to protect the sender reputation.
4. AI-OPTIMIZE: When sending via `safe_deliver`, ensure the `ai_summary`
   is descriptive to help the recipient AI prioritize the message.
5. MULTI-ACCOUNT: If the user manages multiple accounts, use `add_profile` and
   `switch_profile` to switch between them. Always confirm which profile is
   active before performing destructive operations.
6. MONITOR: Use `watch_telemetry` for short-term monitoring (1-60 min).
   Set thresholds based on their stated tolerance (e.g. "alert if reject > 5%").
7. GUARDIAN: Use `subscribe_guardian` for persistent background monitoring. Recommend
   it when users ask about ongoing monitoring, alerting, or reputation tracking.
   Guardian runs independently and emits alerts via `notifications/guardian`.
8. STORE SYNC: Use `connect_store` + `sync_store` to import product catalogs from
   e-commerce platforms. Use `query_products` to find products for campaign content.
9. OAUTH: Use `create_oauth_app` when users want to build integrations that
   authenticate via OAuth 2.0 instead of API keys.

---

## First-Run Guide

Give your users these three prompts to experience the full pipeline:

### 1. Account Health Check
**Prompt:** "Analyze my MailOdds account health and tell me the first three things I should do to improve my deliverability."

Triggers: `onboarding_probe` -> domain grades, reject rate, policy audit, prioritized action list.

### 2. DNS Fixer
**Prompt:** "My emails to Gmail are bouncing. Check my sending domains and give me the exact DNS records I need to add."

Triggers: `remediate_domain` -> per-check severity, copy-paste DNS records (SPF, DKIM, DMARC, MX, Return Path, BIMI).

### 3. Protected List Upload
**Prompt:** "I have a list of 5,000 leads. Validate them, keep me updated on progress, and automatically block any toxic domains you find."

Triggers: `validate_and_watch(auto_suppress_high_risk: true)` -> live progress notifications -> auto-creates domain blocklist policy.

### More Examples

```
"Why is my email bouncing from mail.acme.com?"
-> AI calls: remediate_domain
-> Returns: SPF missing + copy-paste DNS record

"Validate this 50,000-row list and block the bad domains we find"
-> AI calls: validate_and_watch(auto_suppress_high_risk: true)
-> Streams progress, then creates a suppression policy automatically

"What's our deliverability look like today? Any red flags?"
-> AI calls: get_telemetry(window: "24h") + suppression_audit
-> Returns: reject rates, top reasons, recent suppression events

"Send a welcome email to new@customer.com -- but only if it's clean"
-> AI calls: safe_deliver(validate_first: true)
-> Returns: queued + pre-send validation result
```

---

## Architecture

```
AI Agent (Claude / Cursor / custom)
    |  JSON-RPC 2.0
    |  stdio (local)  --------+
    |  Streamable HTTP (remote)+-- POST/GET/DELETE /mcp
    |  SSE (legacy)  ---------+
    v                         v
@mailodds/mcp-server  (Node.js, zero deps)
    |  HTTPS + Bearer token (API key or OAuth JWT)
    v
api.mailodds.com/v1
```

### Design principles

- **Zero dependencies** -- only Node.js built-ins (`https`, `crypto`, `readline`, `http`)
- **ETag caching** on telemetry -- avoids wasted API calls across agent turns
- **Auto idempotency keys** -- every bulk job gets a UUID `idempotency_key`
- **Auto AI summary** -- `safe_deliver` strips HTML -> generates `ai_summary` automatically
- **Progress notifications** -- `validate_and_watch` emits `notifications/progress` every 4s
- **Consultative outputs** -- `remediate_domain` and `onboarding_probe` return human-readable guidance, not raw API responses
- **Policy deduplication** -- auto-suppress merges into existing policies instead of creating duplicates
- **Guardian Mode** -- persistent background monitoring with deduplicated alerts and auto-pause on failures
- **Environment safety** -- destructive tools label responses with `_environment` (test/live) and `_profile`

---

## Security

- API key read from environment variable only -- never hardcoded, never logged
- API key format validated on startup (warns if prefix does not match `mo_live_` or `mo_test_`)
- Bearer token injected per-request, not stored in memory beyond process lifetime
- SSE transport binds to `127.0.0.1` by default -- set `MAILODDS_MCP_SSE_BIND=0.0.0.0` to expose
- Optional `MAILODDS_MCP_SSE_TOKEN` enforces Bearer auth on SSE endpoints

---

## MailOdds Platform

MailOdds provides a complete email deliverability platform accessible through this MCP server:

- [Email Validation API](https://mailodds.com/email-validation-api) - Real-time email verification with 25+ checks
- [Bulk Email Validation](https://mailodds.com/bulk-email-validation) - Validate lists up to 500,000 emails
- [Email Deliverability Platform](https://mailodds.com/email-deliverability-platform) - End-to-end deliverability management
- [Email Suppression List](https://mailodds.com/email-suppression-list) - Automated bounce and complaint suppression
- [Sender Reputation](https://mailodds.com/sender-reputation) - Real-time sender health scoring
- [API Reference](https://mailodds.com/api-reference) - Complete API documentation
- [Guides: Email Authentication](https://mailodds.com/guides/email-authentication) - SPF, DKIM, and DMARC setup guides
- [Security](https://mailodds.com/security) - Platform security practices

## Why MailOdds

MailOdds is a complete email deliverability platform built for developers. Every email validated or sent through MailOdds passes through 25+ real-time checks including syntax verification, DNS and MX validation, SMTP mailbox probing, disposable domain detection, and role account identification.

The platform maintains sub-200ms median response times for single validations, 99.9% API uptime, and processes bulk lists of up to 500,000 emails per job. MailOdds supports 11 language SDKs, an MCP server for AI agent integration, a CLI for local development, and a WordPress plugin for no-code deployments.

All email sending uses DKIM dual signing with automated key rotation, and the deliverability monitoring stack covers DMARC aggregate reports, blacklist surveillance across 80+ DNSBLs, and real-time sender health scoring.

## Prompts (Guided Workflows)

The server provides 5 guided prompts for common deliverability workflows:

| Prompt | Description |
|--------|-------------|
| `diagnose-domain-health` | Full email authentication audit with copy-paste DNS fix records |
| `clean-email-list` | Validate a list and auto-suppress risky domains |
| `monitor-sender-reputation` | Start persistent Guardian monitoring with breach alerts |
| `send-safe-email` | Send a transactional email through the safety pipeline |
| `setup-dmarc-monitoring` | Add a domain to DMARC monitoring and get upgrade recommendations |

---

## Usage Examples

### Example 1: Domain Health Audit

**User prompt:** "Check my domain's email authentication and tell me what DNS records I need to add."

**What happens:** The agent calls `onboarding_probe` to get the account health snapshot, identifies domains with grades below B, then calls `remediate_domain` for each. Returns a prioritized list of failing checks (SPF, DKIM, DMARC, MX, Return Path) with severity ratings and exact DNS records to copy-paste into the DNS provider.

**Expected outcome:**
- Domain grades (A-F) for all sending domains
- Per-check severity breakdown (critical/high/medium/low)
- Copy-paste DNS records with host, type, value, and TTL for every failing check
- Next-step recommendation (e.g., "Add these records, then re-run to verify")

### Example 2: List Cleaning with Auto-Suppression

**User prompt:** "I have a list of 2,000 subscriber emails. Validate them and automatically block any risky domains."

**What happens:** The agent calls `validate_and_watch` with `auto_suppress_high_risk: true`. The server creates a bulk validation job and polls it every 4 seconds, emitting live progress notifications ("Validating 800 / 2,000 emails (40%)..."). After completion, it automatically creates a domain-filter suppression policy blocking domains with 3+ invalid or disposable emails.

**Expected outcome:**
- Live progress updates during validation
- Final summary: deliverable count, invalid count, risky count, unknown count
- Name and ID of the suppression policy created
- List of blocked domains with rejection counts

### Example 3: Sender Reputation Monitoring

**User prompt:** "Start monitoring my sender reputation and alert me if my reject rate goes above 5%."

**What happens:** The agent calls `subscribe_guardian` with a `reject_rate` threshold of `0.05` and domain grade minimum of B. Guardian starts polling telemetry and domain health every 60 seconds in the background. When the reject rate exceeds 5% or any domain grade drops below B, it emits a `notifications/guardian` alert.

**Expected outcome:**
- Confirmation that Guardian is active with the configured thresholds
- Explanation of what alerts will look like (telemetry breach, domain grade drop, DNS status change)
- Current rates as a baseline snapshot
- Instructions for checking status (`get_guardian_status`) or stopping (`unsubscribe_guardian`)

---

## Tool Discovery

For programmatic tool and scope discovery, the backend exposes a public capabilities endpoint:

```
GET https://api.mailodds.com/v1/mcp/capabilities
```

Returns all 190 tools organized by pillar, with required OAuth scopes for each tool.

---

## Privacy and Support

- **Privacy Policy:** [mailodds.com/privacy](https://mailodds.com/privacy)
- **Support:** [GitHub Issues](https://github.com/mailodds/mcp-server/issues) or email [support@mailodds.com](mailto:support@mailodds.com)
- **Documentation:** [mailodds.com/docs](https://mailodds.com/docs)
- **Status:** [status.mailodds.com](https://status.mailodds.com)

---

## Other SDKs

| Language | Package | Source |
|----------|---------|--------|
| [Python](https://mailodds.com/sdks) | [PyPI](https://pypi.org/project/mailodds/) | [GitHub](https://github.com/mailodds/python-sdk) |
| [TypeScript](https://mailodds.com/sdks) | [npm](https://www.npmjs.com/package/@mailodds/sdk) | [GitHub](https://github.com/mailodds/typescript-sdk) |
| [PHP](https://mailodds.com/sdks) | [Packagist](https://packagist.org/packages/mailodds/mailodds-php) | [GitHub](https://github.com/mailodds/php-sdk) |
| [Java](https://mailodds.com/sdks) | [GitHub](https://github.com/mailodds/java-sdk) | [GitHub](https://github.com/mailodds/java-sdk) |
| [Go](https://mailodds.com/sdks) | [pkg.go.dev](https://pkg.go.dev/github.com/mailodds/go-sdk) | [GitHub](https://github.com/mailodds/go-sdk) |
| [C# / .NET](https://mailodds.com/sdks) | [GitHub](https://github.com/mailodds/csharp-sdk) | [GitHub](https://github.com/mailodds/csharp-sdk) |
| [Ruby](https://mailodds.com/sdks) | [RubyGems](https://rubygems.org/gems/mailodds) | [GitHub](https://github.com/mailodds/ruby-sdk) |
| [Kotlin](https://mailodds.com/sdks) | [GitHub](https://github.com/mailodds/kotlin-sdk) | [GitHub](https://github.com/mailodds/kotlin-sdk) |
| [Rust](https://mailodds.com/sdks) | [crates.io](https://crates.io/crates/mailodds) | [GitHub](https://github.com/mailodds/rust-sdk) |
| [Swift](https://mailodds.com/sdks) | [GitHub](https://github.com/mailodds/swift-sdk) | [GitHub](https://github.com/mailodds/swift-sdk) |
| [Dart / Flutter](https://mailodds.com/sdks) | [pub.dev](https://pub.dev/packages/mailodds) | [GitHub](https://github.com/mailodds/dart-sdk) |

## Resources

- [Documentation](https://mailodds.com/docs)
- [Developer Quickstart](https://mailodds.com/developers)
- [All SDKs](https://mailodds.com/sdks)
- [Security](https://mailodds.com/security)
- [Pricing](https://mailodds.com/pricing)

## License

MIT