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 with an API key. Any MCP-compatible client can connect.

The server only ever acts inside the workspace the key was created in. To work in a different 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.
• 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, and its Authentication section defaults to OAuth. MailMoo authenticates with an API key, so pick the option meant for that case:

1. Point the connector at https://app.mailmoo.io/api/mcp.
2. Under Authentication, choose None ("servers that use an API key instead of OAuth").
3. Under Request headers, add a header named authorization with value Bearer sk_live_YOUR_KEY. The scheme and the space are part of the value; Claude sends it exactly as entered.
4. Leave Transport on Streamable HTTP.

This shares one key across everyone with access to the connector rather than signing each person in individually. Give it a key scoped for that purpose (see Good practice below) rather than reusing a personal one.

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

Fifteen tools, all 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 three 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, 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.
• 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. Three change something in your workspace, and two reach a real person and cannot be undone: mailmoo_inbox_send_message, and mailmoo_campaign_set_state when it starts a campaign.

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 enriching leads

MCP can look up leads already in the workspace (mailmoo_leads_search and mailmoo_lead_get_context). Omit campaignId to search the CRM; pass it to list or search one campaign's leads. Search matches a people-search box (name, email, company, phone, LinkedIn 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. It does not find new people, and it does not enrich them.

MCP can 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.

MCP cannot import new leads into a campaign and cannot run enrichment. That stays in the app, because import spends the connected account's daily search budget and enrichment spends workspace credits asynchronously.

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 work with leads already in the workspace and to reach out as part of a wider workflow, and use the agent when you want to import, enrich, build, launch, and adjust campaigns inside MailMoo itself.