Ongage MCP Server (Beta)

Ongage MCP Server (Beta)

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

image-20260224-122228.png

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.

image-20260224-122252.png

Step 3: Authorize Access

You'll be redirected to Ongage to authorize access. Click Allow.

image-20260224-122259.png

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 npx command (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 node

Windows

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.LTS

Verify Installation

Open a terminal (or Command Prompt on Windows) and run:

node -v npm -v

Both commands should return version numbers. If not, restart your terminal and try again.


Claude Desktop

  1. Download Claude Desktop.

  2. 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" } } } }
  1. Replace YOUR_ONGAGE_API_KEY with your actual Ongage API key.

  2. Save the configuration, terminate all Claude processes, and relaunch Claude to apply the new settings.

  3. Verify the connection by asking a test question like "Get my Ongage account info."

Cursor

  1. Download Cursor.

  2. 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" } } } }
  1. Replace YOUR_ONGAGE_API_KEY with your actual Ongage API key.

  2. Save your changes, restart Cursor, and verify the connection.

VS Code

  1. Download VS Code.

  2. 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" } } } }
  1. Replace YOUR_ONGAGE_API_KEY with your actual Ongage API key.

  2. 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

Tool

Description

ask_analytics

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_workflow_analytics

Get detailed analytics for automation workflows within a specified date range. Defaults to last 2 weeks if dates are not provided.

get_event_analytics

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

Tool

Description

create_email

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 list_templates).

edit_email

Update an existing email's name, subject line, HTML content, pre-header, sender details, and/or tags.

get_email

Retrieve a specific email by ID, including its full HTML content for preview.

list_emails

List email messages and templates for a given mailing list, with search by name, pagination, and sorting.

copy_email

Copy an email message (template) to one or more other lists. With multiple targets, it reports which lists succeeded and which failed.

delete_email

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

List email tags for a list (global tags are always included). Use it to find a tag's ID before tagging an email.

create_email_tag

Create a new email tag, scoped to a list or global. Returns the tag ID for use with create_email / edit_email.

list_templates

Browse Ongage's public email templates by category (welcome, newsletter, announcements, events, transactional).

get_template

Get a public template's details, and optionally its full HTML. Use it with create_email to start a new email from the template.

list_images

List the images in your account's image library and their folders, each with a public URL ready to use in email HTML.

upload_image

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

Tool

Description

create_sms

Create an SMS message on a list, with personalization support. Requires an active SMS connection and an SMS field set on the list (see update_list). Send it with create_campaign using an SMS connection.

get_sms

Get an SMS message's text, details, and the campaigns that use it.

list_sms

List the SMS messages of a list, newest first, with search by name.

update_sms

Update an SMS message's name, text, description, or country prefix.

Campaign Management

Tool

Description

Tool

Description

create_campaign

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_campaign

Get full details for a specific campaign, including schedule, segments, email message, distribution, and status.

list_campaigns

Browse campaigns, newest first, with filters for list, name/ID search, status, campaign type, schedule date range, and test campaigns.

update_campaign

Edit a draft or scheduled campaign: name, message, segments, exclusions, ESP connection, or send time. Setting a send time schedules (or reschedules) the campaign.

unschedule_campaign

Move a scheduled campaign back to draft so it won't send until it's scheduled again.

control_campaign

Pause, resume, or stop a campaign that is currently sending. Stopping ends the send, so use pause if you may want to continue.

duplicate_campaign

Copy a campaign into a new draft, optionally with a different message or segments. Split and test campaigns can't be duplicated.

delete_campaign

Permanently delete a campaign that isn't currently sending. Its email and segments are kept.

list_campaign_options

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_test_email

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_transactional

Send a transactional email to one or more recipients.

Segmentation

Tool

Description

Tool

Description

list_segments

List all segments for a mailing list, including their JSON criteria and rules configuration.

get_segment

Get detailed information for a specific segment, including its full filter criteria and rules.

create_segment

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_segment

Update a segment's name, description, favorite flag, and/or criteria. New criteria replace all existing rules.

create_segment_from_report

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.

recount_segment

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_segment

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

Tool

Description

get_contact

Look up a single contact by email: field values, contact ID, status, and status dates.

upsert_contact

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_contact_email

Change a contact's email address while keeping its ID, fields, and history.

change_contact_status

Unsubscribe, resubscribe, or mark as bounce, complaint, or soft bounce up to 500 contacts by email, or remove them. Remove permanently deletes the contacts.

delete_contact

Permanently delete up to 500 contacts and their data. Cannot be undone; to stop mailing while keeping history, unsubscribe instead.

search_contacts

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_contact_searches

List saved Contact Manager searches for a list, with ID, title, status, filters, and dates.

get_contact_search_results

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

Tool

Description

import_contacts

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.

get_import

Check an import's status and counters (success, failed, duplicate, existing, invalid, incomplete), and view the failed rows for a category.

abort_import

Abort an import that is queued or running. Contacts already imported are kept, unless your account has import revert enabled.

export_contacts

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.

get_export

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

Tool

Description

add_to_suppression

Add up to 99 email addresses to a suppression list per call. Wildcards such as *@domain.com suppress a whole domain. For larger volumes, use import_contacts.

remove_from_suppression

Remove up to 99 addresses or wildcard entries from a suppression list per call so they can be mailed again. For larger volumes, use import_contacts with the remove action.

Automation

Tool

Description

Tool

Description

list_workflows

List automation workflows with filtering by name, status, list, and trigger type, plus sorting and pagination. Can include deleted workflows.

get_workflow

Get detailed workflow configuration including triggers, actions, and conditions.

create_workflow

Create a new automation workflow, empty or with a full node graph. Created as a draft by default.

update_workflow

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.

update_workflow_status

Publish/resume (live), pause (freeze), or archive (end) a workflow. Publishing validates that the workflow is complete. Archiving is permanent: an ended workflow can only be renamed or deleted.

duplicate_workflow

Duplicate a workflow. The copy is always created as a draft, named "Copy of <original name>" by default.

delete_workflow

Delete a workflow. This is a soft delete and can be undone with restore_workflow. Only draft or archived workflows can be deleted.

restore_workflow

Restore a deleted workflow that was in draft or archived status.

get_workflow_schema

Get the complete reference for the workflow JSON format: node types, triggers, exit conditions, criteria, connections, status rules, and working examples.

list_behavioral_options

Look up the browser, OS, and country values used in workflow behavioral criteria.

Events

Tool

Description

Tool

Description

list_events

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_event

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

Tool

Description

create_contact_activity_report

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.

get_contact_activity_report

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.

get_contact_activity_rows

Read up to 500 rows of a completed report directly in the conversation, with sorting, without downloading the CSV. Best for smaller reports.

list_contact_activity_reports

List existing Contacts Activity reports for a list, with ID, title, status, row count, dates, and filters.

set_contact_activity_report_favorite

Star or unstar a report. Favorite is the only property of an existing report that can be changed.

delete_contact_activity_report

Delete a report. There is no restore option, so this should be treated as permanent.

get_contact_activity_schema

Get the reference for building reports: filter formats and operators, selectable columns, date-range rules, and examples.

Fields & Reference Data

Tool

Description

Tool

Description

list_fields

List the contact fields defined on a list (e.g. first_name, is_vip), with the field IDs needed for segment rules.

create_field

Create a custom contact field on a list (string, long/huge string, numeric, email, or date). The field's system name is permanent.

update_field

Change a field's title, date format, default value, mandatory flag, or position. The name and type can't be changed.

delete_field

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_system_fields

List Ongage system fields (ocx_*), with IDs, types, and allowed values for enum fields. The available set depends on the account and on usage (segments, workflows, webhooks, contact updates).

Account & Setup

Tool

Description

Tool

Description

get_account_info

Get account details including default list ID, total contacts count, users count, and lists count.

list_lists

List all mailing lists in the account (use this to get list IDs required by other tools).

create_list

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.

update_list

Rename, describe, archive, or restore a list; set its welcome email or SMS field; or change a suppression list's scope and expiry.

list_connections

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 -v in 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/mcp is 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