New: the MailCraft MCP server is live — connect your AI agent in one line. Connect your agent →
Start free

AI agents

MCP server

A hosted Model Context Protocol server that gives Claude, Cursor, VS Code and any other MCP client 68 typed tools covering the whole MailCraft API — sending, contacts, campaigns, automations, domains and analytics. Nothing to install.

Connect

The server speaks Streamable HTTP at https://mcp.mailcraft.host and authenticates with the same sk_… API keys as the REST API, sent as a Bearer token. Create a key under Settings → API keys — the dashboard shows this config with your key already filled in. 

claude mcp add --transport http mailcraft https://mcp.mailcraft.host \
  --header "Authorization: Bearer sk_live_••••••••"

Prefer signing in? Clients that support OAuth — like claude.ai custom connectors — only need the URL. They open a MailCraft consent screen where you pick the workspace and what the agent may do, and a key is created for that connection. Revoke it under Settings → API keys to disconnect.

Claude Desktop's config file only launches local processes, so it connects through the mcp-remote bridge (requires Node.js). Keep keys out of files you commit.

Step-by-step guides

Exact config files, paths and checks for each client.

Claude Code

Anthropic’s agentic coding tool for the terminal.

Claude Desktop

The Claude app for macOS and Windows.

Cursor

The AI code editor.

Windsurf

The AI editor with Cascade.

VS Code

Visual Studio Code with Copilot agent mode.

GitHub Copilot

Copilot in your editor and the Copilot coding agent.

Gemini CLI

Google’s open-source AI agent for the terminal.

OpenCode

The open-source AI coding agent.

OpenAI Codex

OpenAI’s coding agent for the terminal and IDE.

Antigravity

Google’s agent-first development platform.

Scopes decide what an agent can do

Every tool except get_workspace needs one API key scope. Tools outside the key's scopes aren't listed, can't be found through search and can't be called — so a send-only key gives an agent exactly the email tools and nothing else. Each tool acts on the one workspace that owns the key.

How agents find tools

To keep your agent's context small, only the most-used tools are listed up front:

get_workspacesend_emaillist_emailsget_emailvalidate_email_addressget_email_metricsupsert_contactlist_templateslist_senders

Everything else is one step away: the agent calls search_tools with a few words ("create campaign", "segment") to get exact names and input schemas, then runs up to ten of them in one execute_tools call. Clients handle this on their own — you just ask for what you want.

Errors

Failures are written for the agent to act on, not retry blindly.

Missing, invalid or revoked key
HTTP 401 with a WWW-Authenticate header — the client asks you to reconnect.
Invalid arguments
A tool error naming each field to fix, worded exactly like the REST API’s validation messages.
Business rules
Plan limits, unverified senders, suppressed recipients and blocked state changes come back as plain-English tool errors.
Unknown or foreign ids
“No contact with that id exists in this workspace” — another workspace’s records look exactly like missing ones.
Rate limits
Tool calls share your plan’s API rate limit; listing tools, initializing and pings are free.

All 68 tools

One tool per REST endpoint, with the same validation and the same response shapes — see the API reference for field-level detail. Tools that send email or can't be undone are marked, and well-behaved agents confirm them with you first.

Workspace

any scope
  • get_workspace

    Describe the MailCraft workspace this connection acts on: its name, plan and limits (null means unlimited), and which scopes the API key holds.

    Always listedRead-only

Emails & metrics

emails:send
  • send_email

    Send one transactional email immediately.

    Always listedSends / calls out
  • list_emails

    List emails sent from the workspace, newest first, with delivery status, opens and clicks.

    Always listedRead-only
  • get_email

    Get one sent email by id: status, recipients, subject, timestamps, opens, clicks and any error.

    Always listedRead-only
  • validate_email_address

    Check whether an address is worth sending to: valid format, a domain that accepts mail (MX record), and not a disposable inbox.

    Always listedRead-only
  • get_email_metrics

    Daily sending metrics — sent, delivered, opened, clicked, bounced, complained — plus totals for the period.

    Always listedRead-only
  • get_reputation

    The workspace's bounce and complaint rates over the last 7 days, and whether they are within safe sending thresholds.

    Read-only

Contacts, lists & segments

contacts:manage
  • upsert_contact

    Create a contact, or update the existing one with the same email.

    Always listedWrites
  • list_contacts

    List the workspace's contacts, newest first, with subscription status and custom properties.

    Read-only
  • get_contact

    Get one contact with their subscription status and custom properties.

    Read-only
  • delete_contact

    Delete a contact from the workspace, removing them from all lists and automations.

    Destructive
  • unsubscribe_contact

    Unsubscribe a contact and suppress their address, so no campaign or automation emails them again.

    Writes
  • list_contact_lists

    List the lists a contact belongs to.

    Read-only
  • add_contact_to_lists

    Add a contact to one or more lists.

    Writes
  • remove_contact_from_list

    Remove a contact from one list.

    Writes
  • list_properties

    List the workspace's custom contact properties (key, label, type).

    Read-only
  • create_property

    Register a typed custom contact property (e.g.

    Writes
  • delete_property

    Permanently remove a custom contact property definition.

    Destructive
  • list_lists

    List the workspace's contact lists (static lists, and dynamic lists backed by a segment).

    Read-only
  • get_list

    Get one contact list.

    Read-only
  • create_list

    Create a contact list, optionally with its properties.

    Writes
  • set_list_properties

    Choose the properties a list shows and collects, in order.

    Writes
  • list_list_contacts

    List the contacts on a list with their property values.

    Read-only
  • add_contact_to_list

    Add or update a contact on a list, with property values.

    Writes
  • delete_list

    Permanently delete a contact list.

    Destructive
  • list_segments

    List the workspace's segments — saved contact filters — with how many contacts each matches.

    Read-only
  • get_segment

    Get one segment, including its filter conditions and matching contact count.

    Read-only
  • create_segment

    Save a contact filter as a segment and count how many contacts match.

    Writes
  • delete_segment

    Permanently delete a segment.

    Destructive

Templates

templates:manage
  • list_templates

    List the workspace's email templates.

    Always listedRead-only
  • get_template

    Get one template with its subject, HTML and text bodies and variables.

    Read-only
  • create_template

    Create an email template.

    Writes
  • update_template

    Update a template.

    Writes
  • delete_template

    Permanently delete a template.

    Destructive
  • list_template_folders

    List the workspace's template folders.

    Read-only
  • create_template_folder

    Create a folder to organise templates.

    Writes
  • delete_template_folder

    Delete a template folder.

    Destructive

Campaigns

campaigns:manage
  • list_campaigns

    List the workspace's campaigns with their status and send stats.

    Read-only
  • get_campaign

    Get one campaign: audience, template, sender, status and delivery stats.

    Read-only
  • create_campaign

    Create a draft campaign: one template sent from one sender to either a list or a segment (not both).

    Writes
  • send_campaign

    Send a draft campaign to its whole audience right now.

    Sends / calls out
  • delete_campaign

    Permanently delete a campaign and its send history.

    Destructive

Automations

automations:manage
  • list_automations

    List the workspace's automations with their status (draft, active, paused) and trigger.

    Read-only
  • get_automation

    Get one automation with its trigger, ordered steps, and how many contacts are active, waiting, completed, exited or failed.

    Read-only
  • create_automation

    Create a draft automation — a trigger plus a sequence of steps — in one call.

    Writes
  • update_automation

    Rename an automation or change its trigger.

    Writes
  • set_automation_steps

    Replace an automation's entire step sequence (pass every step, in order — omitted steps are removed).

    Writes
  • activate_automation

    Turn an automation on.

    Sends / calls out
  • pause_automation

    Pause an active automation.

    Writes
  • delete_automation

    Permanently delete an automation.

    Destructive
  • list_automation_enrollments

    List the contacts that have gone through an automation, newest first, with where each one is and why any exited or failed.

    Read-only
  • enroll_contact

    Start an existing contact on an active manual- or api-triggered automation, by contact id or email.

    Sends / calls out
  • remove_automation_contacts

    Take every contact that is partway through an automation out of it; they get no further steps.

    Destructive

Domains

domains:manage
  • list_domains

    List the workspace's sending domains with their verification status and the DNS records each one needs.

    Read-only
  • get_domain

    Get one sending domain, including the DKIM/SPF DNS records to publish and whether it is verified.

    Read-only
  • create_domain

    Register a domain to send from.

    Sends / calls out
  • verify_domain

    Re-check a domain's DNS records now and update its verification status.

    Sends / calls out
  • delete_domain

    Permanently remove a sending domain.

    Destructive

Senders

senders:manage
  • list_senders

    List the workspace's sender addresses.

    Always listedRead-only
  • get_sender

    Get one sender address and whether it is verified.

    Read-only
  • create_sender

    Add a sender address on one of the workspace's domains (the address must be on that exact domain).

    Writes
  • delete_sender

    Permanently remove a sender address.

    Destructive

Suppressions

suppressions:manage
  • list_suppressions

    List addresses that will never be sent to — hard bounces, spam complaints, unsubscribes and manual blocks — newest first.

    Read-only
  • add_suppression

    Block an address from receiving any email from this workspace.

    Writes
  • remove_suppression

    Take an address off the suppression list so it can receive email again.

    Destructive

Webhooks

webhooks:manage
  • list_webhooks

    List the workspace's webhook endpoints and the events each one receives.

    Read-only
  • create_webhook

    Register an endpoint that receives signed POST requests when email or contact events happen (delivered, bounced, opened, contact created, …).

    Writes
  • delete_webhook

    Permanently remove a webhook endpoint; it stops receiving events immediately.

    Destructive