As of 2026-07-13

What is a cold email MCP server? The cold-email MCP server for coding agents

A hosted, streamable-HTTP MCP server exposing 17 curated cold-email infrastructure tools, per-tenant bearer-token scoped, live in test mode now. This page documents the exact tool surface — verified against the live tools/list response, not aspirational.

Live and test-mode The endpoint below is reachable today. It runs against a sandboxed vendor layer only — no real domains, mailboxes, or sends yet. See FAQ for the full early-access disclosure.

What this MCP server does

Most cold-email MCP servers in the wild re-export a vendor's full API surface — a well-known example ships 100+ tools. This one is a curated, high-level facade: 17 intents that hide domain-registrar, mailbox-vendor, and sequencing-engine plumbing behind calls an agent can reason about in one context window. Content generation — the offer, the subject lines, the sequence body — stays your agent's job; this server owns infrastructure provisioning, sequencing, isolation, and compliance guardrails. Five of the 17 (get_dashboard, configure_dashboard, label_thread, list_campaigns, activity) are the same facade the optional human dashboard at /app uses — parity by design, never dashboard-only state. For how that tool count compares to larger vendor-wrapper MCP servers, see Smartlead vs Instantly MCP tool coverage.

How to add it

Streamable HTTP, JSON-RPC 2.0 (initialize, tools/list, tools/call), one config line, no OAuth dance. Get a token first via POST /signup (see the setup guide), then add:

{
  "mcpServers": {
    "agent-cold-email": {
      "url": "https://agent-cold-email-api.yaakovscher.workers.dev/mcp",
      "headers": {
        "Authorization": "Bearer <your-token>"
      }
    }
  }
}

The endpoint resolves your token fresh on every call — there is no session or cache that could leak another tenant's data. The same tool names and same per-tenant auth are also reachable as plain REST (see openapi.yaml) if your agent talks HTTP directly instead of MCP.

The 17 tools — exact schemas

Verified directly against the live tools/list response and openapi.yaml. Two additional helpers described in the design spec (write_sequence, suggest_domains) are not implemented — don't assume they exist.

setup_infrastructure

Buy branded lookalike domains, provision mailboxes, and start the warmup ramp. Returns immediately (async job); poll infrastructure_status for progress.

{
  brand: string (1-200 chars),
  primaryDomain: string (3-253 chars),
  domains: integer (1-20),
  inboxesEach: integer (1-10),
  persona: string (1-200 chars),
  physicalAddress: string (1-500 chars),   // CAN-SPAM footer address
  senderIdentity: string (1-200 chars)     // verified legal sender identity
}
// all 7 fields required

infrastructure_status

Provisioning + warmup progress, per-mailbox health, and send-readiness. No parameters.

launch_campaign

Create and activate a campaign against a lead list. The caller supplies the offer and sequence step content — this platform does not generate outreach copy.

{
  name: string (1-200 chars),
  offer: string (1-2000 chars),
  leads: [ { email: string, firstName: string (1-200 chars), company?: string } ],  // 1-5000 items
  sequence: [ { step: integer (>=1), subject: string (1-300 chars),
                body: string (1-20000 chars), delayDays: integer (0-60) } ],        // 1-10 items
  timezone: string,          // default "UTC"
  sendWindow: { startHour: integer (0-23), endHour: integer (0-23) },  // default 0-23
  stopOnReply: boolean       // default true
}

campaign_results

Sends, replies, bounces, and complaints for one campaign.

{ campaignId: string }

list_campaigns

List every campaign for the tenant with id, name, status, and event counts (sent/reply/bounce/...) — no per-campaign lookup needed. No parameters.

metrics

Account-wide deliverability + warmup health. No parameters.

activity

Unified, chronological activity feed merging campaign events (sent/reply/bounce/...) with deliverability control-loop actions (pause/throttle/...).

{
  limit?: integer (1-200),      // default 50
  cursor?: string,
  kind?: "event" | "deliverability"   // omit for every kind
}

inbox

Unified reply inbox across all mailboxes for the tenant. No parameters.

thread

Full message history for one thread.

{ threadId: string }

reply

Send a reply on an existing thread.

{ threadId: string, body: string (1-20000 chars) }

mark

Mark a thread read, unread, or archived.

{ threadId: string, status: "read" | "unread" | "archived" }

label_thread

Set (or, with label: null, clear) a triage label on an inbox thread — the same labels the dashboard UI shows as chips.

{ threadId: string, label?: string (1-100 chars) | null }   // default null

pause

Pause one campaign.

{ campaignId: string }

pause_all

Pause every campaign for the tenant. No parameters.

account

Usage, billing state, quota, and what the AI deliverability control loop has done (paused/throttled mailboxes, burning domains, auto-replacements, recent actions). No parameters.

get_dashboard

List every saved dashboard view (id, name, isDefault, rev, editedBy) or, with id, fetch one view's full layout + rev. The agent-controlled counterpart to the optional human dashboard at /app.

{ id?: string (1-200 chars) }   // omit to list every view

configure_dashboard

Create, update, promote-to-default, or delete a dashboard saved view. update requires the rev you last read; a stale rev returns a structured conflict (currentRev + currentLayout) so you can rebase and retry.

{
  action: "create" | "update" | "promote" | "delete",
  id?: string,       // required for update/promote/delete
  name?: string (1-200 chars),   // required for create; optional rename on update
  rev?: integer,     // required for update (rev-CAS)
  layout?: { schemaVersion: 1, widgets: [...] },  // required for create/update
  note?: string (0-2000 chars)
}

The no-signup CLI demo

npx agent-cold-email demo mints a demo tenant, provisions sample infrastructure, and runs the accelerated sandbox pipeline end to end (warmup, sends, replies, bounces, stop-on-reply) in one command — no signup or token-wrangling required. The CLI is not yet published to npm — until it is, drive the same 17 tools over the hosted MCP endpoint above or directly over HTTP (quickstart). The npm package name is reserved as the permanent keyword handle; publishing is one of the remaining activation steps (see FAQ).

Auth model

One bearer token per tenant, minted by the unauthenticated POST /signup bootstrap call. Every other tool call requires Authorization: Bearer <token> and resolves server-side to exactly one tenant's isolated state — there is no cross-tenant data access at any layer.

Related