MCP server

The MailMoo MCP (Model Context Protocol) server gives AI assistants such as ChatGPT, Claude, and Cursor a secure, standardised way to work with your workspace from a conversation. Instead of switching between MailMoo and the assistant, you ask it to search leads, read unread replies, or start a campaign, and it talks to MailMoo on your behalf.

What is the MailMoo MCP server?

MCP is an open standard that lets AI clients connect to external services through a single, consistent interface. MailMoo hosts the server for you. It speaks Streamable HTTP, exposes a curated subset of workspace operations as tools, and authenticates either by signing you in or with an API key. Any MCP-compatible client can connect.

Which workspace does it act in?

That depends on how you connected.

Signed in (OAuth). One connection covers every workspace you belong to. The tools take a workspace argument and it is always required, so each request states where it is acting rather than inheriting it from somewhere. You can set a default workspace under Account → AI connections; your assistant is told which one it is and will use it unless you say otherwise, but it still names it on every call, so the conversation always shows where something happened.

Permissions are granted per workspace, so a tool that works in one may be refused in another. Any admin of a workspace can revoke your connection's access to their workspace without affecting the others.

API key. A key belongs to the workspace it was created in and cannot act outside it. The tools take no workspace argument. To work in another workspace, use a key from that workspace.

Endpoint:

https://app.mailmoo.io/api/mcp

What can you do with it?

A connected assistant can interact with the core of that workspace. At a high level, it can:

• Find what needs doing. Rank the inbox by what actually needs attention, or list unread conversations.
• Read the workspace. Look up leads, campaigns, conversations, posts, and remaining daily sending and search allowance.
• Build campaigns. Create a campaign with its senders and sequence, run a campaign's leads again with another sequence, move leads between campaigns, and score leads.
• Act. Update a lead, write notes and tasks, start or pause a campaign, and send a message.

This is a curated set of capabilities focused on the most common workflows, not the entire MailMoo API. The available tools evolve over time, and your assistant discovers the current list automatically once connected. See Available tools below, or the generated tool reference.

Connecting a client

Create an API key first, then point your client at the endpoint with that key as a bearer token. Requests without a valid key are rejected with a 401.

Most clients take a URL and a header. The JSON shape below is the common case. File names and field names differ per client, so the sections that follow spell out Cursor, ChatGPT, Claude, Claude Code, Gemini CLI, and Codex.

{
  "mcpServers": {
    "mailmoo": {
      "url": "https://app.mailmoo.io/api/mcp",
      "headers": {
        "Authorization": "Bearer sk_live_YOUR_KEY"
      }
    }
  }
}

Cursor

Add a global MCP server in Cursor Settings → MCP, or put this in ~/.cursor/mcp.json (every project) or .cursor/mcp.json (this project only):

{
  "mcpServers": {
    "mailmoo": {
      "url": "https://app.mailmoo.io/api/mcp",
      "headers": {
        "Authorization": "Bearer sk_live_YOUR_KEY"
      }
    }
  }
}

Reload MCP servers after saving so the new config is picked up. The Authorization header is sent with every request to MailMoo.

ChatGPT

ChatGPT talks to remote MCP servers as custom connectors.

1. Open Settings → Apps (sometimes labelled Apps & Connectors).

2. Turn on Developer mode if ChatGPT asks for it.

3. Create a custom connector named MailMoo, pointing at:

   https://app.mailmoo.io/api/mcp

4. If the dialog offers a token or API key field, paste sk_live_YOUR_KEY. Leave the transport on Streamable HTTP if asked.

Claude

Claude.ai's Add custom connector dialog lives under Customize → Connectors. It is a form, not a config file.

1. Point the connector at https://app.mailmoo.io/api/mcp.
2. Leave Authentication on OAuth, and leave Transport on Streamable HTTP.
3. Add the connector, then click Connect and sign in to MailMoo.

One connection covers every workspace you belong to, and it acts as you: it can only reach what you can reach, and each workspace's admins control what it may do there. Set a default workspace under Account → AI connections so your assistant knows which one to reach for.

You can also connect with an API key instead, by choosing None under Authentication ("servers that use an API key instead of OAuth") and adding a Request header named authorization with value Bearer sk_live_YOUR_KEY (the scheme and the space are part of the value). That shares one key across everyone with access to the connector rather than signing each person in individually, and it is fixed to one workspace, so prefer signing in unless you specifically want a shared, workspace-pinned connection.

To disconnect everywhere at once, remove the connector in Claude and use Disconnect everywhere under Account → AI connections. A single workspace's admins can also revoke your access to just their workspace, from Settings → Members → Workspace API keys.

Reference: Custom remote MCP connectors

Claude Code CLI

Run:

claude mcp add --transport http mailmoo https://app.mailmoo.io/api/mcp \
  --header "Authorization: Bearer sk_live_YOUR_KEY"

Then open a Claude Code session and type /mcp to confirm the server is connected.

Reference: Claude Code MCP

Gemini CLI

Run:

gemini mcp add --scope user --transport http \
  --header "Authorization: Bearer sk_live_YOUR_KEY" \
  mailmoo https://app.mailmoo.io/api/mcp

Reference: Gemini CLI MCP servers

Codex CLI

Codex reads the key from an environment variable rather than embedding it in the command:

export MAILMOO_API_KEY=sk_live_YOUR_KEY
codex mcp add mailmoo --url https://app.mailmoo.io/api/mcp \
  --bearer-token-env-var MAILMOO_API_KEY

Available tools

Tools are named mailmoo_* so they stay distinguishable when your assistant has several servers connected. Each answers a whole question rather than exposing a single endpoint, so a task usually takes one call where it would otherwise take three.

They fall into five groups:

• Finding what needs doing. mailmoo_triage_list is the one to start with: it ranks by what actually needs attention, leads waiting on a reply first. mailmoo_inbox_list_unread is the plainer "what came in" view.
• Reading. Leads, CRM people and companies, campaigns, conversations, posts, and remaining daily sending and search allowance (mailmoo_social_get_limits), each returning the whole picture in one call rather than a handful of pieces to assemble.
• Prospecting. mailmoo_prospects_search previews new people who are not in the workspace yet (free, no contact details), from a plain description or a people-search URL you paste. mailmoo_prospects_add_to_campaign imports that audience into a campaign and spends workspace credits.
• Building campaigns. mailmoo_campaign_create, mailmoo_campaign_rerun, mailmoo_campaign_replace_sequence, mailmoo_campaign_update_senders, mailmoo_leads_enroll, mailmoo_leads_bulk_update, mailmoo_campaign_score_leads and mailmoo_senders_list. See Building campaigns.
• Acting. Updating a lead, writing notes and tasks, starting or pausing a campaign, and sending a message.

Tools that act as one of your connected accounts take a senderProfileId. That is the ID of a sender profile you have already set up in MailMoo, and the server verifies it belongs to your workspace before doing anything. Call mailmoo_social_get_limits to list them.

Permissions decide what a key can reach

Each tool needs the permissions its underlying operations need, so a key that cannot move leads between stages simply cannot use that part of mailmoo_lead_update. Where a tool gathers several things at once, a missing permission removes that piece and says so in the response rather than failing the whole call, so a key with partial access still gets a useful answer.

When a tool refuses

Errors are written to be acted on. Ask for a pipeline stage that does not exist and the response names the ones that do:

No pipeline stage called "Qualified Lead". This workspace has:
New, Qualified, In sequence, In conversation, Meeting booked,
Discovery, Proposal, Won, Lost, On hold.

Unexpected failures stay deliberately vague, because a database error is no use to an assistant and may say more than it should. Anything specific you see is something the server chose to tell you, and usually something you can fix.

Reads and writes

Most of the tools only read. Several change something in your workspace (including mailmoo_prospects_add_to_campaign and mailmoo_campaign_score_leads, which spend credits), and two reach a real person and cannot be undone: mailmoo_inbox_send_message, and mailmoo_campaign_set_state when it starts a campaign.

The campaign building tools that change several things at once take a confirm argument. Called without it they change nothing and return what they would do: the counts, the senders kept and dropped, the credit cost. Your assistant shows you that and calls again with confirm: true once you agree.

Every tool is annotated so your client knows which is which. Well-behaved hosts use those annotations to decide how loudly to confirm with you, and most prompt before any tool call by default.

Some reads cost you something

Most tools are free to call: they read data MailMoo already holds. Reading who engaged with a post is different. It reaches out to the social network on your behalf, and it spends part of the connected account's daily search allowance, which does not refill until the next day.

mailmoo_social_get_post is annotated as not read-only for that reason, even though it changes nothing in your workspace. The annotation is what your client uses to decide whether to run something without asking, and spending a budget that runs out is a decision worth putting in front of you.

The tool returns only the post unless you ask for more. Naming commenters or reactors fetches the people behind those, one allowance charge each. Prefer commenters: someone who wrote a reply showed more intent than someone who tapped a reaction, so the same allowance buys better leads. Check remaining first with mailmoo_social_get_limits. Those people are not added to a campaign.

Limits still apply

Connecting over MCP does not lift any of the protections that apply in the app. Daily limits on your connected accounts are enforced exactly as they are everywhere else, and an assistant cannot ask MailMoo to ignore them. This is deliberate: those caps are what keep a connected account in good standing, and an agent working in a loop is precisely the situation they exist for.

mailmoo_social_get_limits reports remaining daily sending allowance and daily search allowance before you spend either. If a tool call fails because a limit is reached, that is the system working. Wait for the limit to reset rather than retrying.

Finding and importing leads

MCP can look up leads already in the workspace (mailmoo_leads_search and mailmoo_lead_get_context), and CRM people/companies (mailmoo_person_search, mailmoo_company_search). Omit campaignId on leads_search to search the CRM; pass it to list or search one campaign's leads. Search matches a people-search box (name, email, company, phone, profile URL) and returns those identity fields plus Oracle score, lead-fit score, sequence status, and the assigned sender (leadSequence.sdrProfile) by default; pass includeVariables when you need every custom column.

To find new people who are not in the workspace yet, use mailmoo_prospects_search. Prefer a plain query (regions expand; business models map to the closest real industry). The free preview returns a searchId, appliedFilters, matchCount for that preview page (not a market total), and a sample with names/titles/companies, with no contact details or profile URLs. A people-search URL pasted as the query runs as it is. Company-shaped audiences may run as companies_then_people (companies first, then people there); check appliedFilters.intent.

Import with mailmoo_prospects_add_to_campaign, passing that searchId so the same search resumes. That step spends workspace credits per person (search + profile enrichment + fit scoring) and cannot be undone. Always preview first and start with a small maxLeads.

MCP can also source people from a post (mailmoo_social_get_post), which spends the account's daily search allowance. Check remaining first with mailmoo_social_get_limits. Those people are not added to a campaign over MCP.

Lead Fit and Oracle scoring for leads already in a campaign runs with mailmoo_campaign_score_leads. Other standalone enrichment jobs stay in the app.

Building campaigns

When your assistant connects, the server gives it a short guide to building campaigns, so you can ask in plain words ("make a campaign for Finnish SaaS founders and CEOs", "run Q3 Finland again with the sequence from Retouch") rather than walking it through each step.

A campaign is three things: its senders, its sequence, and its leads. The tools build them in that order and leave the campaign switched off.

• mailmoo_campaign_create creates a campaign with its senders and a sequence. The sequence is copied from another campaign (steps, messages, branches and sending schedule), built from a template with messages written from your workspace's company and ideal customer context, or left empty. Templates are named the way they are in the app: Basic Outreach, Basic Outreach w/ ICP filter, Basic Outreach w/ InMail fallback, and Advanced Multi-Touch Outreach.
• Leads come from wherever you say: people already in the workspace with mailmoo_leads_enroll (from a campaign, a filtered part of one, or the CRM), or new people with mailmoo_prospects_search then mailmoo_prospects_add_to_campaign. A file is uploaded in the campaign's Leads tab. If you have not said where the leads come from, the assistant asks.
• mailmoo_campaign_rerun runs a campaign's leads again in a new campaign, optionally with another campaign's sequence. In one call it copies the sequence and schedule, brings the leads and their columns across, keeps each lead on the sender they already had where that sender can still send, and stops the leads' sequences still running in the old campaign. A sender with no connected account, or a disconnected one, is dropped and their leads are handed to the remaining senders.
• mailmoo_campaign_replace_sequence swaps an existing campaign's sequence for another campaign's. The campaign must be paused.
• mailmoo_campaign_update_senders adds senders to an existing campaign, removes some, or both in one call (a swap). Removing a sender unassigns the leads they held so the remaining senders pick them up; leads already in conversation with that sender stay unassigned until you move them with mailmoo_leads_bulk_update. A campaign always keeps at least one sender. It works while the campaign is running, and previews the change first.
• mailmoo_leads_bulk_update pauses or resumes outreach, moves leads to a pipeline stage, or puts them on another sender, for up to 5,000 leads at once.
• mailmoo_campaign_score_leads runs Lead Fit and the Oracle reply score for the leads not scored yet. Lead Fit costs credits per lead; leads that already have it are only Oracle-scored, at no cost. Scores arrive in the background over a few minutes.
• mailmoo_senders_list lists your sender profiles and whether each can still send.

None of these start a campaign. Starting one is mailmoo_campaign_set_state, under its own permission, after you say so.

Good practice

• Give the assistant its own key, named for that purpose, so you can revoke it without touching your other integrations.
• Start with the read tools. Let the assistant research and draft before you let it send anything.
• Read what it drafted. The sequence got you the reply; a message the assistant sends is still from you.

What the MailMoo Agent can do as well

The tools above are what an outside assistant can reach. The assistant built into MailMoo, MailMoo Agent, works with a much wider set of capabilities, because it runs inside the app with your own session rather than through an API key.

The agent can do everything the MCP tools do, plus:

It also has capabilities that only make sense inside the product, and which no external client could use:

So the rule of thumb is: use MCP when you want your own assistant to build and rerun campaigns, work with leads already in the workspace, preview and import new audiences, and reach out as part of a wider workflow; use the in-app agent when you also want step-by-step sequence editing, navigation, and product help inside MailMoo itself.