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 25 tools across five groups, 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.

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.