MailX MCP Integration Guide

Connect AI agents to email deliverability tools via MCP

MCP Endpoint

https://themailx.com/mcp

POST JSON-RPC 2.0 | No auth required Discovery JSON →

Integrations

Claude Code (CLI & IDE) Claude.ai & Claude Desktop Cursor Windsurf VS Code (GitHub Copilot) Zed OpenAI Agents SDK Direct API (any agent or framework)

Available Tools

Tool	Description
spf_check	Check if a domain has a valid SPF (Sender Policy Framework) DNS record. SPF specifies which mail servers are authorized to send email on behalf of a domain.
dkim_check	Check if a domain has a valid DKIM (DomainKeys Identified Mail) DNS record for a given selector. DKIM allows the receiver to verify that an email was sent by the domain owner.
dmarc_check	Check if a domain has a valid DMARC (Domain-based Message Authentication, Reporting & Conformance) DNS record. DMARC tells receiving servers what to do with emails that fail SPF or DKIM checks.
bimi_check	Check if a domain has a valid BIMI (Brand Indicators for Message Identification) DNS record. BIMI allows brands to display their logo next to authenticated emails in supporting email clients.
dmarc_generate	Generate a DMARC DNS record for a domain. Returns the record name, value, and type ready to be added to DNS.
spf_generate	Generate an SPF DNS record for a domain based on the email provider being used. Returns the record name, value, and type ready to be added to DNS.
smtp_check	Test an SMTP server connection by attempting to connect and authenticate. If from_email and to_email are provided, the tool may attempt to send a test email. Only provide these fields if you are authorized to send from the account and intentionally want to test full sending capability.
imap_check	Test an IMAP server connection by attempting to connect and authenticate. Use this to verify email receiving configuration.
smtp_finder	Look up SMTP server settings (host, port, encryption) for a given email provider. Use this to find the correct SMTP configuration for services like Gmail, Outlook, SendGrid, etc.
imap_finder	Look up IMAP server settings (host, port, encryption) for a given email provider. Use this to find the correct IMAP configuration for services like Gmail, Outlook, Yahoo, etc.
blacklist_check	Check if a domain or IP address is listed in popular email blacklists (DNSBLs). Being blacklisted can severely impact email deliverability.
bimi_host	Host and serve your BIMI SVG file for email authentication
mx_lookup	Look up MX (Mail Exchanger) records for a domain. Returns the mail servers and their priorities.
txt_lookup	Look up all TXT records for a domain. TXT records contain SPF policies, domain verification tokens, DKIM keys, and other metadata.
cname_lookup	Look up CNAME (Canonical Name) records for a domain. Shows where a hostname aliases to.
ptr_lookup	Reverse DNS lookup. Find the hostname associated with an IP address. A valid PTR record is important for email sending reputation.
dns_lookup	Look up all DNS records for a domain in one query. Returns A, AAAA, CNAME, MX, NS, TXT, and SOA records.

Claude Code (CLI & IDE extensions)

Add a .mcp.json file to your project root:

{
  "mcpServers": {
    "mailx": {
      "type": "http",
      "url": "https://themailx.com/mcp"
    }
  }
}

Start a new Claude Code session. When prompted, approve the mailx MCP server. Then ask:

"Audit the email deliverability for example.com"

CLI alternative: Run claude mcp add --transport http mailx https://themailx.com/mcp

Claude.ai & Claude Desktop

Both Claude.ai (web) and Claude Desktop use the same Custom Connectors system. Available on Pro, Max, Team, and Enterprise plans.

Install

Go to Settings → Connectors, click Add custom connector, paste the URL below, and click Add. No authentication needed.

https://themailx.com/mcp

Team / Enterprise: an admin enables it once under Settings → Connectors. Members then connect from their own Settings → Connectors.

Using it

Enable MailX from the chat input's tools menu, then ask about email deliverability.

Cursor

Add to .cursor/mcp.json in your project:

{
  "mcpServers": {
    "mailx": {
      "url": "https://themailx.com/mcp"
    }
  }
}

Restart Cursor. The tools are available in Composer and Agent mode.

Windsurf

Edit ~/.codeium/windsurf/mcp_config.json:

{
  "mcpServers": {
    "mailx": {
      "serverUrl": "https://themailx.com/mcp"
    }
  }
}

Note: Windsurf uses serverUrl for HTTP servers (not url), and there's no type field — HTTP is implied by the serverUrl field.

Restart Windsurf. The tools become available in Cascade.

VS Code (GitHub Copilot)

Add to .vscode/mcp.json in your workspace:

{
  "servers": {
    "mailx": {
      "type": "http",
      "url": "https://themailx.com/mcp"
    }
  }
}

Note: VS Code uses "servers" as the top-level key (not "mcpServers" like other clients).

You can also run MCP: Add Server from the Command Palette to add it through the UI. The tools are available in Copilot Chat agent mode.

Zed

Add to your Zed settings.json (open via cmd+, on macOS):

{
  "context_servers": {
    "mailx": {
      "url": "https://themailx.com/mcp"
    }
  }
}

Note: Zed uses "context_servers" as the top-level key. You can also click Add Custom Server in the Agent Panel settings to configure through the UI.

The tools become available in Zed's Agent Panel.

OpenAI Agents SDK

The OpenAI Agents SDK supports MCP via the Streamable HTTP transport:

from agents.mcp import MCPServerStreamableHttp
from agents import Agent

async with MCPServerStreamableHttp(
    name="mailx",
    params={
        "url": "https://themailx.com/mcp",
    },
) as mailx:
    agent = Agent(
        name="Email Deliverability Expert",
        instructions="Use the mailx tools to check email deliverability.",
        mcp_servers=[mailx],
    )
    # Use the agent...

Direct API (any agent or framework)

All tools are also available as standalone HTTP endpoints — no MCP protocol needed. Use these from any language, framework, or script.

POST https://themailx.com/api/v1/{tool-endpoint}
Content-Type: application/json

Example: Check SPF

curl -X POST https://themailx.com/api/v1/spf-check \
  -H "Content-Type: application/json" \
  -d '{"domain_name": "google.com"}'

Example: Generate DMARC record

curl -X POST https://themailx.com/api/v1/dmarc-generate \
  -H "Content-Type: application/json" \
  -d '{
    "domain_name": "example.com",
    "email": "dmarc@example.com",
    "dmarc_policy": "quarantine"
  }'

Using MCP protocol directly

For frameworks that speak MCP natively (LangChain, CrewAI, Anthropic Agent SDK, etc.), POST JSON-RPC 2.0 messages to the MCP endpoint:

# List available tools
curl -X POST https://themailx.com/mcp \
  -H "Content-Type: application/json" \
  -d '{
    "jsonrpc": "2.0",
    "method": "tools/list",
    "id": 1
  }'

# Call a tool
curl -X POST https://themailx.com/mcp \
  -H "Content-Type: application/json" \
  -d '{
    "jsonrpc": "2.0",
    "method": "tools/call",
    "id": 2,
    "params": {
      "name": "spf_check",
      "arguments": { "domain_name": "example.com" }
    }
  }'

Agent Skill

MailX also publishes an Agent Skill — a markdown file that teaches AI agents how and when to use these tools. The Agent Skills format is an open standard adopted by both Anthropic and OpenAI (Codex CLI, ChatGPT). Three ways to install it:

1. Claude Code (recommended)

If you use Claude Code, install via the plugin marketplace:

/plugin marketplace add Mailwarm/mailx-skills
/plugin install email-deliverability@mailx-skills

2. Claude.ai (web)

Download SKILL.md, go to Settings → Skills on Claude.ai, upload the file, and enable it.

3. Claude API

For apps calling the Claude API programmatically, upload the skill and reference it by skill_id:

curl -X POST https://api.anthropic.com/v1/skills \
  -H "x-api-key: $ANTHROPIC_API_KEY" \
  -H "anthropic-beta: skills-2025-10-02" \
  -F "display_title=Email Deliverability" \
  -F "files[]=@SKILL.md"

Discovery

Agents and clients can auto-discover the MCP server and skill via these endpoints:

Endpoint	Purpose
/.well-known/mcp.json	MCP server metadata and tool list
/.well-known/mcp/server-card.json	Smithery-compatible server card (tools, resources, prompts, config schema)
/.well-known/skills.json	Agent Skills index
/.claude-plugin/marketplace.json	Claude Code marketplace catalog
/skills/email-deliverability/SKILL.md	Live SKILL.md (always current)
/llms.txt	Plain-text description for LLM agents
/mcp/docs	This integration guide