OneSignal

OneSignal

This connector works with one OneSignal app (push notifications, email, SMS and in-app messaging) through the OneSignal REST API with an App API key: the app, its messages and delivery results, outcomes, segments, users and templates; it can send push, email and SMS, cancel scheduled messages, create segments and update user tags.

Setup (about 3 minutes)

1. In OneSignal open the app, then Settings, Keys & IDs. Copy the App ID (a UUID) into ONESIGNAL_APP_ID.
2. On the same page click Add Key (App API keys), give it a name and create it. The value starts with os_v2_app_ and is shown only once: paste it into ONESIGNAL_APP_API_KEY. The key works only for this app; for another app, install the connector again with that app's ID and key.
3. Install. The connector sends the key as Authorization: Key <key>.

The key acts for the whole app, not for one person: whoever uses this connector sees its users and can send to its audience if the send tools are on. Share the MCP server only with people allowed to do that.

How to work

1. Check the setup: onesignal_view_app (name, subscription counts).
2. Results: onesignal_list_messages, onesignal_view_message (with outcomes on request), onesignal_view_outcomes for app-wide clicks, confirmed deliveries, sessions and custom outcomes, and onesignal_export_message_history for a CSV of who received or clicked a message (POST, but only reads).
3. Audience: onesignal_list_segments and onesignal_view_user (by external_id or another alias).
4. Content: onesignal_list_templates and onesignal_view_template.
5. Sending: onesignal_send_push, onesignal_send_email and onesignal_send_sms send real messages. Target segments by name (included_segments, e.g. "Subscribed Users") or users by alias (include_aliases with target_channel). Show the content, the audience and the time first and call only after the user confirms; for a segment or more than one recipient wait for an explicit "yes, send". Use send_after to schedule and onesignal_cancel_message to stop a scheduled message.
6. Other writes, each only after the user confirms: onesignal_create_segment and onesignal_update_user (tags, language, timezone, country).
7. onesignal_delete_user deletes a user for good and is installed switched off; an administrator turns it on deliberately.

A send answers with the message id; an empty id means nobody matched the targeting (the errors list says why, for example "All included players are not subscribed").

Common errors

• 401 "Access denied": the key is wrong, deleted or rotated, or belongs to another app than ONESIGNAL_APP_ID.
• 400 "Failed to parse app_id": the App ID is not a valid UUID; copy it from Keys & IDs.
• 400 on a send: content or targeting is invalid, e.g. no English content, or segments combined with aliases.
• 403: the key is restricted (IP allowlist) or the plan does not include the feature.
• 429: OneSignal's rate limit is reached; wait and retry.

Out of scope here: organization-level endpoints (all apps, creating apps, API key management, audit logs), subscriptions and aliases management, Live Activities, inbox messages, journeys, CSV exports of all subscriptions and custom events.