MailOdds MCP Server

"The Autonomous Deliverability Architect"

Plug MailOdds into any AI agent (Claude, Cursor, Windsurf, custom) and let it autonomously manage the full Trust Cycle -- auditing DNS, enforcing validation policies, executing safe transactional sends, and syncing e-commerce product catalogs -- without writing a single line of integration code.

Tools (95 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)

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 or sse | | MAILODDS_MCP_PORT | No | 3741 | Port for SSE transport | | MAILODDS_MCP_SSE_BIND | No | 127.0.0.1 | Bind address for SSE transport | | MAILODDS_MCP_SSE_TOKEN | No | -- | Bearer token to protect SSE endpoints | | 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 (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:

{
  "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:

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

Claude Code

claude mcp add mailodds -- npx -y @mailodds/mcp-server
claude mcp env set mailodds MAILODDS_API_KEY your_key_here

SSE (web agents / hosted deployment)

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

To expose SSE beyond localhost, set MAILODDS_MCP_SSE_BIND=0.0.0.0 and protect with a token:

MAILODDS_MCP_SSE_BIND=0.0.0.0 \
MAILODDS_MCP_SSE_TOKEN=your_secret_token \
MAILODDS_MCP_TRANSPORT=sse \
MAILODDS_API_KEY=your_key_here \
node index.js

Docker

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

Set MAILODDS_API_KEY and MAILODDS_MCP_SSE_TOKEN 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:

{
  "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:

{
  "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:[email protected]; ...",
      "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:

{
  "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.

{
  "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:

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 [email protected] -- 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  ----------------+
    |  SSE  ------------------+
    v                         v
@mailodds/mcp-server  (Node.js, zero deps)
    |  HTTPS + Bearer token
    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

License

MIT