MCP Server

The @molted/mcp package exposes the Molted Email API as discoverable tools for any runtime that supports the Model Context Protocol. Claude Desktop, Cursor, VS Code Copilot, Windsurf, and any other MCP client can use it to send email, manage threads, classify inbound messages, and more.

Installation

npx -y @molted/mcp

Or install globally:

npm install -g @molted/mcp

Environment variables

Setup

Claude Desktop

Add to your claude_desktop_config.json:

{
  "mcpServers": {
    "molted": {
      "command": "npx",
      "args": ["-y", "@molted/mcp"],
      "env": {
        "MOLTED_API_KEY": "mm_live_..."
      }
    }
  }
}

Cursor

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

{
  "mcpServers": {
    "molted": {
      "command": "npx",
      "args": ["-y", "@molted/mcp"],
      "env": {
        "MOLTED_API_KEY": "mm_live_..."
      }
    }
  }
}

VS Code Copilot

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

{
  "servers": {
    "molted": {
      "type": "stdio",
      "command": "npx",
      "args": ["-y", "@molted/mcp"],
      "env": {
        "MOLTED_API_KEY": "mm_live_..."
      }
    }
  }
}

Windsurf

Add to ~/.codeium/windsurf/mcp_config.json:

{
  "mcpServers": {
    "molted": {
      "command": "npx",
      "args": ["-y", "@molted/mcp"],
      "env": {
        "MOLTED_API_KEY": "mm_live_..."
      }
    }
  }
}

HTTP transport

For cloud agents or server-side use, run in HTTP mode:

MOLTED_API_KEY=mm_live_... molted-mcp --transport http --port 3100

The HTTP transport is stateless -- each request creates a fresh MCP session. This works well for serverless deployments and load-balanced environments.

Tools

The MCP server exposes 44 tools across eight groups (budget, threads, sending, intelligence, governance, analytics, journeys and segments, coordination), plus 8 resources and 5 prompts.

Budget

check_budget

Check remaining send capacity including daily/hourly limits and bounce/complaint budget. Call this before planning a campaign or batch send to verify you have capacity.

Parameters: None

Returns: { daily: { used, remaining }, hourly: { used, remaining }, negativeBudget: { bounces, complaints } }

Inbox and threads

read_inbox

List threads in a mailbox with optional filtering.

Returns: { items: [{ id, contactEmail, subject, status, messageCount, lastMessageAt }], total }

get_thread

Get a full thread with all messages, intent classification, and SLA status.

Returns: { thread: { id, status, contactEmail, ... }, envelopedMessages: [...] }

reply

Reply to a thread. Supports two modes:

• Shorthand: Provide body (plain text) or html -- uses the _default template with an auto-generated dedupe key.
• Template: Provide template_id, payload, and dedupe_key for custom templates.

Returns: { status: "queued" | "sent", requestId }

archive

Archive a resolved thread, moving it out of the active inbox.

Returns: { archived: 1 }

update_thread

Update a thread's status, metadata, or assignment.

Returns: The updated thread object.

approve

Approve a pending send in the approval queue (human-in-the-loop).

Returns: Approval confirmation.

Sending

send_email

Send a policy-checked email. Supports shorthand (body/html) and template modes.

Returns: { status: "queued" | "blocked" | "pending_approval", requestId }

Policy blocks are returned as successful results with the block reason so your agent can reason about alternatives.

draft_email

Draft an email with AI-assisted composition and policy pre-check.

Returns: { draftCandidates: [...], policyPreCheck: { allowed, reason }, contactContext }

dry_run

Simulate a send without dispatching. Preview the policy decision.

Returns: { wouldAllow: boolean, reason?, cooldownExpiresAt?, simulation: true }

batch_send

Send to multiple recipients with per-recipient policy evaluation. Max 500 recipients per batch.

Returns: { batchId, total, queued, blocked, results: [{ recipientEmail, requestId, status, reason? }] }

schedule_followup

Schedule a delayed follow-up email that auto-cancels if the recipient replies.

Returns: { followupId, status, scheduledAt }

Intelligence

classify_inbound

Classify an inbound email's intent.

Returns: { intent, confidence, suggestedAction, flags?, safetyVerdict? }

Intent categories: interested, objection, not_now, support, billing, legal, security, out_of_office.

next_best_action

Get a recommendation for what to do next with a contact based on timeline, fatigue, and intent signals.

Returns: { recommendation, reasoning, contactSummary: { email, lastSendAt, isSuppressed } }

Recommendations: reply, wait, nudge, stop, escalate.

get_context

Get full contact timeline including sends, replies, journeys, engagement history, and suppression status.

Returns: { timeline: { sends, journeyRuns, inboundMessages }, suppressionStatus, activeIncidents, lastClassification }

batch_classify

Classify multiple inbound emails in one call.

Returns: { results: [{ intent, confidence, suggestedAction }] } in the same order as inputs.

batch_next_action

Get next-best-action recommendations for multiple contacts.

Returns: { results: [{ contactEmail, recommendation, reasoning }] }

Governance and outcomes

add_suppression

Suppress a contact or domain so no further emails are sent to them. Provide either recipient_email (email-level) or domain (domain-level).

Returns: The created suppression record.

check_suppression

Check if an email address or domain is currently suppressed. Call this before sending to verify the recipient is not on a suppression list.

Returns: Suppression records if found, empty array if not suppressed.

remove_suppression

Remove a suppression so the contact or domain can receive emails again.

Returns: { deleted: true }

check_consent

Check consent status for a contact (GDPR/CCPA compliance).

Returns: { hasConsent: boolean, basis: string }

record_consent

Record consent for GDPR/CCPA compliance.

Returns: The consent record.

record_outcome

Record a business outcome (conversion, revenue, engagement) linked to email touches. Molted automatically attributes the outcome to recent email interactions.

Returns: The ingested outcome record with attribution data.

outcome_dashboard

Get a revenue attribution summary showing how email campaigns contributed to business outcomes.

Parameters: None

Returns: { totalRevenue, conversions, topCampaigns }

journey_impact

Analyze which journeys had the most impact on business outcomes.

Returns: Journeys ranked by outcome contribution.

Analytics

fatigue_score

Get the fatigue score (0-100) for a contact. Measures how "tired" a recipient is of your emails based on send frequency, bounces, complaints, reply rate, and days since last engagement.

Returns: { contactEmail, fatigueScore, factors: { sendFrequency, bounceCount, complaintCount, replyRate, daysSinceLastEngagement }, recommendation }

Thresholds: Above 70 = stop sending. Above 40 = reduce frequency. Below 40 = safe.

send_velocity

Get your recent send volume and velocity trends. Use this to detect if you are ramping up too fast.

Parameters: None

Returns: { lastHour, last24Hours, last7Days, hourlyTrend: [{ hour, count }] }

deliverability

Get email deliverability metrics: delivery rate, bounce rate, and complaint rate.

Returns: { period, totalSent, delivered, bounced, complained, deliveryRate, bounceRate, complaintRate }

check_reputation

Check the reputation status of a specific mailbox.

Returns: { id, mailbox_id, bounce_rate, complaint_rate, total_sends, total_bounces, total_complaints, status, last_calculated_at }

Status values: healthy, warning, paused. A paused mailbox blocks all sends until reputation recovers.

Journeys and segments

create_journey

Create a multi-step email journey (onboarding, nurture, re-engagement). Journeys start in "draft" status.

Returns: { id }

activate_journey

Activate a draft journey or change its status.

Returns: { updated: true }

trigger_journey

Enroll a contact into a journey by ingesting a trigger event. The event is processed asynchronously.

Returns: { eventId }

journey_status

Check a journey's configuration, status, and steps.

Returns: { id, name, status, trigger_event, trigger_conditions, steps: [{ id, step_order, step_type, config }] }

add_journey_step

Append or replace a step in an existing journey. Call repeatedly after create_journey to build a sequence, then activate_journey.

config per step_type:

• send: { templateId, mailboxId?, payload?, dedupeKeyPrefix?, sendReason? }
• delay: { delayMinutes } (the worker only reads this spelling — not minutes or delayMs)
• branch: { conditions: [{ field, operator, value, nextStepOrder }], defaultNextStepOrder? }
• end: {}

Returns: { id, step_order, step_type, config }

update_journey_step

Update an existing step. All fields are optional — supply only what you want to change.

Returns: updated step.

create_segment

Define an audience segment with AND/OR filter criteria on contact fields, metadata, and behavioral data.

Filter types: contact_field, metadata, account_field, firmographic, behavioral Operators: eq, neq, gt, gte, lt, lte, contains, not_contains, in, not_in, exists, not_exists, between

Returns: { id, name, filter_group, status }

compute_segment

Queue an asynchronous recomputation of segment membership for all contacts.

Returns: { queued: true, segmentId }

check_membership

Check if a specific contact is a member of a segment. Evaluates live against current data.

Returns: { isMember: boolean, evaluatedLive: true }

Coordination

Multi-agent coordination tools that prevent simultaneous messaging and enable consensus decisions. Agents must register before using leases, heartbeats, or consensus.

register_agent

Register this agent with the coordination system. If an agent with the same name already exists, its heartbeat is refreshed.

Returns: { id, agentName, agentRole, lastHeartbeat, registeredAt }

heartbeat

Signal liveness to the coordination system. Agents that stop sending heartbeats have their leases auto-expired. Call periodically (every 1-2 minutes) while holding leases.

Returns: { ok: true }

acquire_lease

Claim exclusive access to a contact. Prevents other agents from messaging the same contact simultaneously. If another agent already holds the lease, returns a conflict response with the current lease holder details.

Returns: { id, agentId, contactEmail, intent, expiresAt } on success, or { conflict: true, leaseHolder: { agentId, agentName } } if already held.

release_lease

Release a contact lease when done. Frees the contact for other agents to claim.

Returns: { released: true }

list_leases

List all active contact leases in the tenant. Shows which agents hold leases on which contacts, with expiry times.

Parameters: None

Returns: Array of { id, agentId, contactEmail, intent, expiresAt }

create_consensus

Propose a high-risk action for multi-agent consensus. Other agents can vote to approve or reject. Resolved automatically when a majority of active agents have voted.

Returns: { id, status, action, contactEmail, reason, timeoutAt }

get_consensus

Get the current state of a consensus request including votes cast and status.

Returns: { id, status, action, contactEmail, reason, timeoutAt }

Status values: pending, approved, rejected, expired.

vote

Cast a vote on a multi-agent consensus request. Each agent can only vote once per request.

Returns: { id, vote, consensusStatus }

Resources

Resources provide read-only context that agents can pull into their working memory without calling tools. Access them via resources/list and resources/read in any MCP client.

Resources return JSON data from the Molted API. Template URIs ({id} parameters) auto-populate from the list callback, so MCP clients that support resource templates will show available mailboxes and templates as completions.

Prompts

Prompts are pre-built multi-step workflows that agents can invoke. Each prompt returns a message sequence that guides the agent through chaining multiple tools together.

draft-followup

Given a thread, draft an appropriate follow-up email. Reads the thread, checks budget, and composes a reply matching the conversation tone.

triage-inbox

Process unread threads: classify intent, recommend action, and auto-archive resolved/spam/OOO threads.

pre-send-check

Before sending an email, verify it is safe: check suppression status, consent, and remaining budget. Returns a GO / NO-GO recommendation.

investigate-bounce

Investigate why an email bounced and recommend corrective action. Automatically suppresses hard bounces.

campaign-readiness

Check if conditions are right to send a campaign to a segment: budget capacity, template readiness, domain health, and negative-signal budget.

Error handling

The MCP server maps API responses to structured tool results:

Policy blocks (e.g., suppressed contact, rate limit exceeded) are returned as successful results with the block reason. This lets your agent reason about why the send was blocked and decide on alternatives rather than treating it as an error.

Scoped keys

API keys can be scoped to specific mailboxes. When using a scoped key, all tools automatically operate within that mailbox's context. This is useful for multi-tenant setups where each agent should only access its own mailbox. See Authentication for details on key scoping.