Ongage MCP Server (Beta)
- 1 MCP
- 1.1 Ongage MCP Server
- 1.1.1 What You'll Learn
- 1.1.2 What is MCP?
- 1.1.3 Configure Your MCP Client
- 1.1.4 Available Tools
- 1.1.4.1 Analytics
- 1.1.4.2 Email Creation
- 1.1.4.3 SMS
- 1.1.4.4 Campaign Management
- 1.1.4.5 Segmentation
- 1.1.4.6 Contacts
- 1.1.4.7 Import & Export
- 1.1.4.8 Suppression
- 1.1.4.9 Automation
- 1.1.4.10 Events
- 1.1.4.11 Contacts Activity Reports
- 1.1.4.12 Fields & Reference Data
- 1.1.4.13 Account & Setup
- 1.1.5 Example Prompts
- 1.1.5.1 Analytics & Insights
- 1.1.5.2 Create & Schedule Campaigns
- 1.1.5.3 Cross-Capability Workflows
- 1.1.5.4 Account & Setup
- 1.1.6 Troubleshooting
- 1.1.7 Security Best Practices
- 1.1.8 Support
- 1.1 Ongage MCP Server
MCP
Ongage MCP Server
Run your email marketing by just asking.
The Ongage MCP Server connects your Ongage account directly to AI assistants like Claude, Cursor, and VS Code. You can build an email, line up the right segment and schedule the campaign in one conversation, without clicking through screens. Pull performance insights in plain English, clean up your lists, import contacts, and launch automations, all from a single chat.
With 80+ tools covering campaigns, contacts, segments, automation, and analytics, your AI assistant becomes a hands-on member of your marketing team. You stay in control: you can review every action before it changes anything in your account.
What You'll Learn
This guide walks you through connecting your AI client to the Ongage MCP Server, whether you use the one-click Claude connector or a manual setup with your API key.
MCP Endpoint: https://api.ongage.com/mcp
What is MCP?
MCP (Model Context Protocol) is an open standard that lets AI assistants connect securely to the tools and data you already use. When you connect the Ongage MCP Server to an AI client, the assistant can read your account data and carry out tasks on your behalf, using your existing Ongage permissions.
Your AI assistant can help with:
Analytics – Query campaign, workflow, and Event performance metrics using natural language
Email Creation – Create and manage email templates, start from Ongage's public templates, and manage your image library
SMS – Create and manage SMS messages
Campaign Management – Create, schedule, test, pause, and manage email and SMS campaigns
Segmentation – Build, update, and recount audience segments
Contact Management – Look up, add, update, search, and change the status of contacts
Import & Export – Bulk import contacts and export segment or campaign audiences to CSV
Suppression – Manage suppression lists to keep addresses and domains from being mailed
Automation – Build, publish, and analyze automation workflows
Events – View recurring, trigger-based Event campaigns
Contacts Activity Reports – Generate per-contact activity reports and turn them into segments
Lists & Fields – Create and manage mailing lists and custom contact fields
See Available Tools for the full list.
Configure Your MCP Client
To communicate with the Ongage MCP server, each MCP client needs specific configuration. Choose the setup method that fits your use case.
Option A — Claude Connector (Recommended)
The fastest way to get started. No API key or Node.js installation required. Works with both http://Claude.ai (web) and Claude Desktop on Pro, Team, and Enterprise plans.
💡 This is the recommended method for most users. You'll be up and running in under a minute.
Step 1: Admin Adds the Connector
An organization admin or user with access goes to Settings → Connectors and adds Ongage from the available integrations.
As noted above the MCP Endpoint is: https://api.ongage.com/mcp
Step 2: Users Click "Connect"
Once the admin (or user) has added Ongage, everyone in the organization can go to Settings → Connectors and click "Connect" next to Ongage.
Step 3: Authorize Access
You'll be redirected to Ongage to authorize access. Click Allow.
That's it! Go back to Claude and try asking: "Get my Ongage account info"
✅ Verify: You should see the Ongage tools available in Claude's tool list. Try "Show my campaign analytics for the last 7 days" to confirm everything is working.
Option B — Manual Setup with API Key
Use this method for Cursor, VS Code, or if you prefer to connect with your own API key (e.g., personal accounts without an organization).
Prerequisites
An active Ongage account
An Ongage API key (obtain from your Ongage account settings)
A compatible MCP client (Claude Desktop, Cursor, VS Code, etc.)
Node.js (v18 or later) installed on your machine
⚠️ Node.js is required for the manual method. The
npxcommand (bundled with Node.js) runs a lightweight bridge to the MCP server.
Installing Node.js
macOS
Option A — Official installer: Go to https://nodejs.org and download the macOS installer (LTS recommended). Run the .pkg file and follow the prompts.
Option B — Homebrew:
brew install nodeWindows
Option A — Official installer: Go to https://nodejs.org and download the Windows installer (LTS recommended). Run the .msi file and follow the prompts. Make sure the "Add to PATH" option is checked during installation. Restart any open terminals after installing.
Option B — winget:
winget install OpenJS.NodeJS.LTSVerify Installation
Open a terminal (or Command Prompt on Windows) and run:
node -v
npm -vBoth commands should return version numbers. If not, restart your terminal and try again.
Claude Desktop
Download Claude Desktop.
Open Claude Desktop. Navigate to Settings > Developer > Edit Config and add the following configuration:
{
"mcpServers": {
"ongage": {
"command": "npx",
"args": [
"-y",
"mcp-remote",
"https://api.ongage.com/mcp",
"--header",
"X-Api-Key:${API_KEY}"
],
"env": {
"API_KEY": "YOUR_ONGAGE_API_KEY"
}
}
}
}Replace
YOUR_ONGAGE_API_KEYwith your actual Ongage API key.Save the configuration, terminate all Claude processes, and relaunch Claude to apply the new settings.
Verify the connection by asking a test question like "Get my Ongage account info."
Cursor
Download Cursor.
Open Cursor. Navigate to Settings > Cursor Settings > MCP > New MCP Server and add the following:
{
"mcpServers": {
"ongage": {
"command": "npx",
"args": [
"-y",
"mcp-remote",
"https://api.ongage.com/mcp",
"--header",
"X-Api-Key:${API_KEY}"
],
"env": {
"API_KEY": "YOUR_ONGAGE_API_KEY"
}
}
}
}Replace
YOUR_ONGAGE_API_KEYwith your actual Ongage API key.Save your changes, restart Cursor, and verify the connection.
VS Code
Download VS Code.
Open VS Code. Open MCP User Configuration (Ctrl + Shift + P >
MCP: Open User Configuration) and add the following:
{
"servers": {
"ongage": {
"command": "npx",
"args": [
"-y",
"mcp-remote",
"https://api.ongage.com/mcp",
"--header",
"X-Api-Key:${API_KEY}"
],
"env": {
"API_KEY": "YOUR_ONGAGE_API_KEY"
}
}
}
}Replace
YOUR_ONGAGE_API_KEYwith your actual Ongage API key.Save your changes. From the command palette (Ctrl+Shift+P on Windows or Cmd+Shift+P on Mac), search for
MCP: List Servers, then select ongage > Start Server.
Available Tools
The Ongage MCP server provides the following tools organized by category.
Analytics
Tool | Description |
|---|---|
| Query campaign performance metrics (opens, clicks, bounces, CTR, complaints, and more) using natural language. Covers all campaigns including automations. Defaults to last 7 days if no timeframe is given. |
| Get detailed analytics for automation workflows within a specified date range. Defaults to last 2 weeks if dates are not provided. |
| Get Event performance analytics (sends, opens, clicks, bounces, complaints, unsubscribes, CTR, uCTR, post-back clicks). Group by event, trigger, message, or day. Uses the account timezone by default so numbers match the Ongage UI. Defaults to the last 30 days. |
Email Creation
Tool | Description |
|---|---|
| Create a new email message (template) with HTML content, subject line, name, and optional pre-header, sender details (From Name, From address, Reply-to), and tags. Can start from one of Ongage's public templates (see |
| Update an existing email's name, subject line, HTML content, pre-header, sender details, and/or tags. |
| Retrieve a specific email by ID, including its full HTML content for preview. |
| List email messages and templates for a given mailing list, with search by name, pagination, and sorting. |
| Copy an email message (template) to one or more other lists. With multiple targets, it reports which lists succeeded and which failed. |
| Delete one or more email or SMS messages. Messages used as a list's welcome email/SMS or in an active automation are protected and won't be deleted; the result lists any that were skipped and why. |
| List email tags for a list (global tags are always included). Use it to find a tag's ID before tagging an email. |
| Create a new email tag, scoped to a list or global. Returns the tag ID for use with |
| Browse Ongage's public email templates by category (welcome, newsletter, announcements, events, transactional). |
| Get a public template's details, and optionally its full HTML. Use it with |
| List the images in your account's image library and their folders, each with a public URL ready to use in email HTML. |
| Upload an image to the image library from a public URL (JPG, PNG, or GIF, up to 1 MB). Returns a ready-to-use public URL. Requires a verified image host in your Ongage settings. |
SMS
Tool | Description |
|---|---|
| Create an SMS message on a list, with personalization support. Requires an active SMS connection and an SMS field set on the list (see |
| Get an SMS message's text, details, and the campaigns that use it. |
| List the SMS messages of a list, newest first, with search by name. |
| Update an SMS message's name, text, description, or country prefix. |
Campaign Management
Tool | Description |
|---|---|
| Create a new email campaign by specifying the email, target segment, ESP connection, and optional excluded segments. Provide a send time to schedule it; otherwise it is saved as a draft. |
| Get full details for a specific campaign, including schedule, segments, email message, distribution, and status. |
| Browse campaigns, newest first, with filters for list, name/ID search, status, campaign type, schedule date range, and test campaigns. |
| Edit a draft or scheduled campaign: name, message, segments, exclusions, ESP connection, or send time. Setting a send time schedules (or reschedules) the campaign. |
| Move a scheduled campaign back to draft so it won't send until it's scheduled again. |
| Pause, resume, or stop a campaign that is currently sending. Stopping ends the send, so use pause if you may want to continue. |
| Copy a campaign into a new draft, optionally with a different message or segments. Split and test campaigns can't be duplicated. |
| Permanently delete a campaign that isn't currently sending. Its email and segments are kept. |
| List the campaigns that are valid for a specific input (report filter, segment rule, workflow trigger/criteria, or workflow send node), matching what the Ongage UI picker offers for that input. |
| Send an email or SMS to up to 50 test addresses before the real send. Creates a one-off campaign flagged as a test, which sends immediately. |
| Send a transactional email to one or more recipients. |
Segmentation
Tool | Description |
|---|---|
| List all segments for a mailing list, including their JSON criteria and rules configuration. |
| Get detailed information for a specific segment, including its full filter criteria and rules. |
| Create a new segment from field-based and behavioral rules (sent, opened, clicked, complained, unsubscribed, bounced), with support for AND/OR grouping and date ranges. |
| Update a segment's name, description, favorite flag, and/or criteria. New criteria replace all existing rules. |
| Create a segment from a Contacts Activity report's filter conditions, the same as the UI's "Create Segment" button. The segment stays live and matches future contacts. |
| Recalculate how many contacts currently match up to 20 segments (the UI's Recount action). Not needed before sending, since campaigns evaluate segments at send time. |
| Delete a segment. It checks where the segment is used first, won't delete one used by active events or campaigns being sent, and asks for confirmation when scheduled or draft campaigns would be affected. |
Contacts
Tool | Description |
|---|---|
| Look up a single contact by email: field values, contact ID, status, and status dates. |
| Add a contact or update an existing one's fields, or do so for up to 500 contacts at once. Reports per-email results and failure reasons. |
| Change a contact's email address while keeping its ID, fields, and history. |
| Unsubscribe, resubscribe, or mark as bounce, complaint, or soft bounce up to 500 contacts by email, or remove them. Remove permanently deletes the contacts. |
| Permanently delete up to 500 contacts and their data. Cannot be undone; to stop mailing while keeping history, unsubscribe instead. |
| Search a list's contacts in the Contact Manager by segment, field values, contact status, or campaign activity. Returns the count and matching rows. Each search is saved in the Contact Manager. |
| List saved Contact Manager searches for a list, with ID, title, status, filters, and dates. |
| Get a search's status and results: total count, up to 500 rows per call, and a CSV download link for larger results. |
Import & Export
Tool | Description |
|---|---|
| Import contacts into a list from inline rows, CSV text, or a public file URL (CSV/TXT or ZIP). Supports column mapping, overwriting existing contacts, and bulk unsubscribe/resubscribe/remove. Also works on suppression lists, to bulk-add or bulk-remove addresses. Runs in the background. |
| Check an import's status and counters (success, failed, duplicate, existing, invalid, incomplete), and view the failed rows for a category. |
| Abort an import that is queued or running. Contacts already imported are kept, unless your account has import revert enabled. |
| Export the contacts of one or more segments or campaign audiences to CSV, with a choice of fields, statuses, and date format. Runs in the background. |
| Check an export's status and, once it's complete, get its download link. The file is a password-protected ZIP using the export password from your Account settings, and the link expires after about 5 minutes. |
Suppression
Tool | Description |
|---|---|
| Add up to 99 email addresses to a suppression list per call. Wildcards such as |
| Remove up to 99 addresses or wildcard entries from a suppression list per call so they can be mailed again. For larger volumes, use |
Automation
Tool | Description |
|---|---|
| List automation workflows with filtering by name, status, list, and trigger type, plus sorting and pagination. Can include deleted workflows. |
| Get detailed workflow configuration including triggers, actions, and conditions. |
| Create a new automation workflow, empty or with a full node graph. Created as a draft by default. |
| Rename a workflow, change its status, and/or replace its node graph. The node list fully replaces the existing one, so omitted nodes are deleted. |
| Publish/resume ( |
| Duplicate a workflow. The copy is always created as a draft, named "Copy of <original name>" by default. |
| Delete a workflow. This is a soft delete and can be undone with |
| Restore a deleted workflow that was in draft or archived status. |
| Get the complete reference for the workflow JSON format: node types, triggers, exit conditions, criteria, connections, status rules, and working examples. |
| Look up the browser, OS, and country values used in workflow behavioral criteria. |
Events
Tool | Description |
|---|---|
| List Events (trigger-based campaigns that send on a recurring schedule, such as daily, weekly, or monthly) for a list, filterable by name and active status. |
| Get full details for an Event, including its triggers, recurrence and schedule, included/excluded segments, distribution, and time-to-send settings. |
Contacts Activity Reports
Tool | Description |
|---|---|
| Create a Contacts Activity report showing per-contact sends, opens, clicks, and status dates for contacts matching your filters within a date range. Reports generate in the background. |
| Check a report's status and, once it's complete, get CSV download links (summary and detailed). Links expire after about 5 minutes; call again for fresh ones. |
| Read up to 500 rows of a completed report directly in the conversation, with sorting, without downloading the CSV. Best for smaller reports. |
| List existing Contacts Activity reports for a list, with ID, title, status, row count, dates, and filters. |
| Star or unstar a report. Favorite is the only property of an existing report that can be changed. |
| Delete a report. There is no restore option, so this should be treated as permanent. |
| Get the reference for building reports: filter formats and operators, selectable columns, date-range rules, and examples. |
Fields & Reference Data
Tool | Description |
|---|---|
| List the contact fields defined on a list (e.g. first_name, is_vip), with the field IDs needed for segment rules. |
| Create a custom contact field on a list (string, long/huge string, numeric, email, or date). The field's system name is permanent. |
| Change a field's title, date format, default value, mandatory flag, or position. The name and type can't be changed. |
| Delete a custom field and its data. It checks where the field is used first, won't delete one used by segments, automations, or events, and asks for confirmation when scheduled campaigns would be unscheduled. |
| List Ongage system fields ( |
Account & Setup
Tool | Description |
|---|---|
| Get account details including default list ID, total contacts count, users count, and lists count. |
| List all mailing lists in the account (use this to get list IDs required by other tools). |
| Create a sending list or a suppression list. Suppression lists can apply globally, to specific campaigns, or to specific lists, with optional hashing and an expiration date. The list description is limited to 50 characters. |
| Rename, describe, archive, or restore a list; set its welcome email or SMS field; or change a suppression list's scope and expiry. |
| List all ESP connections (vendors) with their IDs, titles, and ESP names. |
Example Prompts
Here are some examples showing how you can combine multiple capabilities in a single prompt.
Analytics & Insights
"Show me opens, clicks, and bounce rates for all campaigns sent in the last 30 days, and highlight any campaign with a CTR below 1%."
"Compare my automation workflow performance against my regular campaigns for the past month — which channel drives more engagement?"
"What are my top 3 segments by open rate this quarter?"
Create & Schedule Campaigns
"Create a new email with the subject 'Summer Flash Sale — 48 Hours Only!', use a clean promotional layout with a hero image placeholder and a CTA button, then schedule it to my 'Active Subscribers' segment for next Monday at 9 AM EST using my default ESP connection."
"Duplicate the HTML from my 'Spring Newsletter' email, update the subject to 'Fall Update' and replace any mention of spring with fall, then save it as a new email."
Cross-Capability Workflows
"Pull last month's campaign analytics, find the campaign with the highest click-through rate, then show me which segment and email template it used — I want to replicate that setup for a new campaign next week."
"List all my automation workflows, show me the analytics for any workflow with 'welcome' in the name over the past 60 days, and summarize how each one is performing."
"Show me the criteria for my 'High Value Customers' segment, then check what campaigns were sent to that segment in the last 30 days and how they performed."
Account & Setup
"Get my account info and list all my ESP connections and mailing lists."
Troubleshooting
Node.js / npx not found (manual setup only)
Make sure Node.js is installed by running
node -vin your terminal.On Windows, ensure Node.js was added to your system PATH during installation. You may need to restart your terminal or PC after installing.
If you installed Node.js while your MCP client was open, fully quit and relaunch the client.
MCP client can't find Ongage tools
Connector setup: Verify you completed the authorization step and that "Ongage" appears in your Connectors list.
Manual setup: Verify your API key is correct and has the necessary permissions. Ensure the configuration file is saved correctly.
Restart your MCP client application completely.
Getting inaccurate or inconsistent responses
Start a new chat to reset the conversation context.
Be specific in your queries by providing relevant details (date ranges, list names, etc.).
If asking about analytics, specify the time period you're interested in.
Connection errors
Verify your internet connection.
Ensure your API key hasn't expired or been revoked.
Check that
https://api.ongage.com/mcpis accessible from your network.
Security Best Practices
Never share your API key – Treat it like a password.
Use environment variables – Avoid hardcoding API keys in configuration files that might be shared or version-controlled.
Rotate keys periodically – Generate new API keys regularly and revoke old ones.
Review tool actions – Always review what the AI is doing before confirming actions that modify your data.
Support
If you encounter issues or have questions about the Ongage MCP server:
Contact Ongage Support through your account dashboard
Visit the Ongage Help Center
Reach out to your account manager