PlugPress
Get Started

Mailpuff

Connect an AI Agent to Mailpuff with MCP

Connect Claude, ChatGPT, Claude Code, Cursor or any MCP app to Mailpuff through Saddle or the WordPress MCP Adapter, then check it works. About five minutes.

To connect an AI agent to Mailpuff, install an MCP server plugin on your WordPress site, copy its address from Mailpuff → Settings → MCP & API, and add that address to your AI app. Saddle and the WordPress MCP Adapter both work. Once connected, Claude, ChatGPT, Claude Code, Cursor or any MCP app can write, test, schedule and report on your campaigns. Setup takes about five minutes.

What do I need before I start?

  • WordPress 7.0 or later and PHP 8.0 or later. The Abilities API that Mailpuff’s tools use is part of WordPress core.
  • Mailpuff, active. Nothing else in Mailpuff has to be set up first. An agent can connect PostShiba and add subscribers for you.
  • An administrator account. Every Mailpuff tool needs the manage_options capability, so the agent signs in as an administrator.
  • An AI app that supports MCP over HTTP. For example Claude, ChatGPT, Claude Code, Codex, Cursor or VS Code.
  • One MCP server plugin: Saddle or the MCP Adapter. Both are free on WordPress.org.

Should I use Saddle or the MCP Adapter?

Use Saddle if you want to approve sends and deletions before they happen and keep a log of what the agent did. Use the MCP Adapter if you already run it or want the WordPress project’s own server with nothing on top. Mailpuff’s own send switch protects your list either way.

Saddle MCP Adapter
Sign-in Guided setup for each AI app A WordPress application password
How tools appear One MCP tool per Mailpuff tool, named saddle-mailpuff-* Three general tools that find and run mailpuff/* abilities
Access levels per app Yes No, the account’s full rights
Approve before a send or delete Yes, a preview and a confirm step No
Switch single tools off Yes No
Activity log Yes No
“AI agents can send campaigns” switch Applies Applies

When Saddle is active, Mailpuff offers its tools only through Saddle, so every call passes Saddle’s checks. The MCP Adapter’s default server then doesn’t list them.

How do I connect through Saddle?

  1. Install and activate Saddle from Plugins → Add New.
  2. Open Mailpuff → Settings → MCP & API. The AI agents (MCP) row should say Ready with the number of tools, and show the server URL. It looks like https://your-site.com/wp-json/saddle/v1/mcp.
  3. Follow the link to Saddle’s MCP page, pick your AI app, and paste the setup Saddle generates into it. The Saddle MCP setup guide has the steps for each app.
  4. Ask the agent: “Give me a Mailpuff overview.” It should call saddle-mailpuff-get-overview and tell you what is still open in your setup.

Saddle lists Mailpuff’s tools as saddle-mailpuff-list-campaigns, saddle-mailpuff-create-campaign and so on. You control them on Saddle’s permissions screen, as described in Saddle permissions and access levels.

How do I connect through the MCP Adapter?

  1. Install and activate the MCP Adapter plugin.
  2. Open Mailpuff → Settings → MCP & API and copy the server URL. It looks like https://your-site.com/wp-json/mcp/mcp-adapter-default-server.
  3. Create an application password under Users → Profile → Application Passwords. Name it after the AI app and copy it. WordPress shows it only once.
  4. Add the server to your AI app with HTTP Basic authentication: your WordPress username and the application password.

In Claude Code, for example, encode the username and password, then add the server:

printf 'your-username:abcd efgh ijkl mnop qrst uvwx' | base64

claude mcp add --transport http mailpuff 
  https://your-site.com/wp-json/mcp/mcp-adapter-default-server 
  --header "Authorization: Basic PASTE_THE_RESULT_HERE"

WordPress offers application passwords only over HTTPS, except on a local development site. See the WordPress REST API authentication docs for details.

How does an agent call Mailpuff through the MCP Adapter?

The adapter’s default server offers three tools. mcp-adapter-discover-abilities lists every tool on the site. mcp-adapter-get-ability-info returns one tool’s input schema. mcp-adapter-execute-ability runs it. To list draft campaigns, the agent sends:

{
  "ability_name": "mailpuff/list-campaigns",
  "parameters": { "status": "draft", "limit": 10 }
}

The discover call gives the agent the names it needs, and get-ability-info gives it the inputs. The MCP Adapter repository documents the server in full.

How do I check the connection works?

Open Mailpuff → Settings → MCP & API. The status on the AI agents row tells you where things stand:

Status What it means
Ready · 40 tools Connected, with sending to your list allowed
Ready · 38 tools Connected. Sending and scheduling stay off until you allow them
No tools offered The server is up but lists no Mailpuff tools
No MCP server Neither Saddle nor the MCP Adapter is active
Not available Saddle is active but its MCP route is missing. Check Saddle’s MCP page

Then ask your agent for an overview. When the first tool call lands, Mailpuff’s Home page stops showing the “connect an agent” step.

Why does my agent see 38 tools instead of 40?

Two tools, send-campaign and schedule-campaign, exist only while AI agents can send campaigns is on. The switch is off by default, and only you can turn it on, in Mailpuff → Settings → MCP & API. Until then, an agent can write and test campaigns but can’t mail your list. AI agent permissions and safe sending explains what else the switch controls.

What should I ask the agent first?

  • “Give me a Mailpuff overview and tell me what’s left to set up.”
  • “Connect PostShiba. I’ll paste the API key and Team ID.”
  • “Import these customers and tag them Customers. They ticked the newsletter box at checkout.”
  • “Write a newsletter about our spring sale and send me a test.”
  • “Is anything stopping us from sending? Fix what you can.”
  • “How did last Tuesday’s email do?”

FAQ

The settings page says “No MCP server”. What now?

Install and activate Saddle or the MCP Adapter, then reload the page. Mailpuff looks for one of the two and shows its address.

The status says “No tools offered”.

The server answers but lists no Mailpuff tools. Check that your WordPress version includes the Abilities API and that no custom code returns false from the mailpuff_ability_mcp_public filter.

My AI app gets a 401 error.

The sign-in was refused. With the MCP Adapter, check the username and application password and make sure the account is an administrator. Some hosts strip the Authorization header. With Saddle, follow Saddle troubleshooting.

Can an Editor account connect?

It can connect, but Mailpuff’s tools refuse it. Every tool needs the manage_options capability, which only administrators have.

Can I connect more than one AI app?

Yes. With Saddle, each app gets its own connection and access level. With the MCP Adapter, give each app its own application password so you can revoke one without the others.