MCP

Point your agent at MailerZ.

Q: Where do I mint a key?

Register or sign in on the desk, then Developer → API Key.

MailerZ MCP is JSON-RPC 2.0 for Cursor, Claude Desktop, and Hermes. Remote clients POST to https://mail.mailerz.net/api/mcp with the same key as send. Desktop apps that only speak stdio run the product npm run mcp proxy. The agent can list mail, send from an owned address, block a sender, and open a support ticket.

Start free — one domain Open Developer

Copy a client config

Placeholder only: mz_live_YOUR_KEY. Never paste a real key into a public repo.

Cursor (HTTP) — Settings → MCP, or .cursor/mcp.json

{
  "mcpServers": {
    "mailerz": {
      "url": "https://mail.mailerz.net/api/mcp",
      "headers": {
        "Authorization": "Bearer mz_live_YOUR_KEY"
      }
    }
  }
}

Hermes (HTTP)

{
  "mcpServers": {
    "mailerz": {
      "transport": "http",
      "url": "https://mail.mailerz.net/api/mcp",
      "headers": {
        "Authorization": "Bearer mz_live_YOUR_KEY"
      }
    }
  }
}

Claude Desktop, Cursor stdio, Hermes, Cline, Continue, Windsurf

{
  "mcpServers": {
    "mailerz": {
      "command": "npx",
      "args": ["tsx", "src/mcp/stdio.ts"],
      "env": {
        "MAILERZ_API_URL": "https://mail.mailerz.net",
        "MAILERZ_API_KEY": "mz_live_YOUR_KEY"
      }
    }
  }
}

Claude Code

claude mcp add mailerz --env MAILERZ_API_URL=https://mail.mailerz.net --env MAILERZ_API_KEY=mz_live_YOUR_KEY -- npx tsx src/mcp/stdio.ts

VS Code Copilot, ChatGPT custom action, LibreChat, Open WebUI, Jan

POST https://mail.mailerz.net/api/mcp
Authorization: Bearer mz_live_YOUR_KEY
Content-Type: application/json

Claude Desktop file: claude_desktop_config.json (macOS: ~/Library/Application Support/Claude/). Run the command from a clone of the product repo, or pass an absolute path to src/mcp/stdio.ts. The stdio process only proxies framed MCP to POST /api/mcp. It does not store mail.

Methods: initialize, tools/list, tools/call. If the client only supports stdio, use the stdio block. Also accepted: X-Api-Key. Aliases: POST /api/v1/mcp and POST /mcp.

Protocol versions: 2024-11-05, 2025-03-26, 2025-06-18. Spec: Model Context Protocol. Hub: Developers. Fields: POST /api/v1/send. Plans: pricing. Controls: security.

Read tools

Tool	Arguments	What it does
`mailerz_health`	none	API, DB, disk, inbound queue
`mailerz_whoami`	none	Key kind, workspace, role, email
`mailerz_docs`	topic: overview \| send \| clients \| tools	Short how-to
`mailerz_send_as_list`	none	Addresses this key may use as From
`mailerz_mailbox_list`	folder inbox\|sent\|held, q, page, pageSize	List stored mail
`mailerz_mailbox_get`	id	One letter (text capped, no raw .eml)
`mailerz_domains_list`	none	Hosted domains (read)
`mailerz_domain_get`	id	One domain + delivery stats
`mailerz_addresses_list`	none	Aliases and destinations
`mailerz_blocks_list`	none	Block Sender list
`mailerz_contacts_list`	q, page, pageSize	Address book
`mailerz_bounces_list`	kind all\|hard\|soft\|feedback, page, pageSize	Bounce / FBL events
`mailerz_entitlements`	none	Plan limits
`mailerz_usage`	none	Outgoing used vs cap
`mailerz_plans_list`	none	Public catalog (read-only)
`mailerz_exposure_list`	page, pageSize, unreadOnly	Leak / first-seen signals

Write tools

Tool	Arguments	What it does
`mailerz_send`	from, to, cc, bcc, replyTo, subject (required), text, html, inReplyTo, references, headers, attachments, idempotencyKey	Same pipeline as POST /api/v1/send
`mailerz_mailbox_mark_read`	id	Mark read
`mailerz_mailbox_delete`	id	Permanently delete stored letter
`mailerz_block_add`	pattern, note	Block email or @domain
`mailerz_block_remove`	id	Remove a block
`mailerz_contact_add`	email, name	Add / restore contact
`mailerz_contact_update`	id, email, name	Edit contact
`mailerz_contact_delete`	id	Soft-delete (harvest will not re-add)
`mailerz_support_create`	subject, body, email, name	Support ticket — no secrets in the body

Resources and prompts

mailerz://docs/overview · mailerz://docs/send · mailerz://docs/clients

send_a_message · triage_inbox · block_a_sender · workspace_status

Honest limits

Access

Free plan cannot send (SEND_AS_LOCKED). Paid send-as required. From must be an enabled alias you own. Catch-all * is not a From. mz_root_ From must be @mailerz.net or @mail.mailerz.net.

Rate

80 sends / hour / workspace and / key. MCP reads 300 / hour / key. Recipients: 20 unique To+Cc+Bcc. Reply-To: 5.

Size

Attachments: 10 files, 7 MB each, 10 MB total. JSON body 12 MB. Subject 900 characters. Idempotency-Key (header or idempotencyKey) replays 24 hours.

Safety

Same outbound scan as SMTP. MAIL_SPAM / MAIL_VIRUS means not sent. Block Sender cannot recall copies already in Gmail. Do not put API keys or passwords in mailerz_support_create or letter bodies. We do not train models on customer mail. We are not SOC 2.

Questions

What is MailerZ MCP?

A JSON-RPC 2.0 server on the MailerZ API. Agents call the same send, mailbox, and block tools the desk uses.

Do I need a special MCP key?

No. Use the Send API key from desk → Developer. mz_live_ for a workspace. mz_root_ is operator-only.

Does this work with Claude / Cursor / Hermes?

Yes. Cursor and Hermes can POST HTTP to /api/mcp. Claude Desktop and other stdio clients use npm run mcp as a proxy.

Can I send on the Free plan?

No. Upgrade so send-as is on, then publish SPF + DKIM.

Do you train on my mail?

No.

Are you an official Anthropic or OpenAI plugin?

No. Any client that speaks MCP JSON-RPC or stdio can connect.

Where do I mint a key?

Mint the key on the desk.

Start free with one domain. After the account exists, open Developer and copy mz_live_.

Start free — one domain Open Developer