Skip to content
Scalekit Docs
Talk to an Engineer Dashboard

Connect AI agents to the OneSignal MCP server

Vendor MCP
Open markdown

The OneSignal MCP connector routes your AI agent's tool calls to OneSignal's own MCP server through Scalekit. Each user signs in to OneSignal once, and Scalekit stores and refreshes their tokens, so your agent never handles credentials. It comes with 54 tools.

Tools
54
What they doRead · write · destructive
29 · 10 · 1529 read10 write15 destructive
Users sign in with
OAuth app
Your own OneSignal MCP server app

Setup

  1. Install the SDK

    Terminal window
    npm install @scalekit-sdk/node dotenv
  2. Set your credentials

    Add your Scalekit credentials to your .env file. Find values in app.scalekit.com > Developers > API Credentials.

    .env
    SCALEKIT_ENVIRONMENT_URL=<your-environment-url>
    SCALEKIT_CLIENT_ID=<your-client-id>
    SCALEKIT_CLIENT_SECRET=<your-client-secret>
  3. Create the OneSignal MCP connection

    In AgentKit > Connections, create an OneSignal MCP connection and copy its redirect URI. The name you give it is the connection_name your code passes. See Configure connections.

  4. Register an OAuth app

    OneSignal MCP server connections use your own OAuth app. Register one with OneSignal MCP server and add the redirect URI you copied.

    Then enter the app's Client ID and Client Secret on the OneSignal MCP connection.

  5. Authorize a user and make your first call

    quickstart.mts
    import { ScalekitClient } from '@scalekit-sdk/node'
    import 'dotenv/config'
    import { createInterface } from 'node:readline/promises'
    const scalekit = new ScalekitClient(
    process.env.SCALEKIT_ENVIRONMENT_URL,
    process.env.SCALEKIT_CLIENT_ID,
    process.env.SCALEKIT_CLIENT_SECRET,
    )
    const actions = scalekit.actions
    const connector = 'onesignalmcp'
    const identifier = 'user_123'
    // Generate an authorization link for the user
    const { link } = await actions.getAuthorizationLink({ connectionName: connector, identifier })
    console.log('Authorize OneSignal MCP:', link)
    const rl = createInterface({ input: process.stdin, output: process.stdout })
    await rl.question('Press Enter after authorizing...')
    rl.close()
    // Make your first call
    const result = await actions.executeTool({
    connector,
    identifier,
    toolName: 'onesignalmcp_list_apps',
    toolInput: {},
    })
    console.log(result)
    Terminal window
    npx tsx quickstart.mts

    Each user signs in once. See Authorize a user for the full flow and statuses.

Tools

Pass the exact name to execute_tool
Try in PlaygroundRequest a tool
  • onesignalmcp_check_send_volumeCheck whether an email send needs IP or domain warmup, given the sender domain and an estimated recipient count.Read-only

    Check Send Volume

    Check whether an email send needs IP or domain warmup, given the sender domain and an estimated recipient count. Nothing is saved. Mainly a step in the email drafting flow rather than something users ask for directly: call it whenever the draft is email, before recommending a send or a schedule. It also answers the same question after the fact, when diagnosing a send that went badly. Pass the recipient count that send actually reached and the domain it went out on, and the advice tells you whether it was large enough relative to the domain's history to have needed a ramp. It takes a recipient count and a domain, no draft required. The email_deliverability skill owns that flow. Returns advice (none, recommended, required, or unspecified), factors explaining the verdict (exceeds_volume_threshold, exceeds_peak_30_day_recommendation), and baseline sending history for the domain (peak_daily_volume_30d, peak_date, contributing_app_count, where the app count covers every app sending on that domain). Preserve the returned advice in the final user-facing summary, including after adding a ramp to an existing draft. If advice is required, explicitly say warmup is required or necessary; saying only that the ramp matters or describing the risks is not enough. If advice is recommended, present it as a recommendation instead. The recommended schedule name describes the stages, not the strength of this verdict. For a small enough send the check short-circuits to advice: none with a zeroed baseline, without consulting sending history. The threshold is decided by the API, so do not guess at it or quote a number. In that case say the send is too small to need warmup, and do not present the zeroed baseline as the domain's real sending history. If the API returns HTTP 400 with Something went wrong, do not retry the identical request. Check get_email_domains for the selected domain. Only call it deactivated when that state is explicitly returned; otherwise report that the check failed and the warmup verdict and baseline are unavailable. Do not infer no sending history from this error or from empty provider reports. A successful recommended_warm_up_schedule response is an app-based proposal, not a replacement domain-volume verdict.

    Inputs

    app_idstringrequired
    OneSignal App ID.
    estimated_recipientsintegerrequired
    Estimated number of recipients for the send. Required.
    sender_domainstringrequired
    The actual sending domain, for example mail.example.com. Use a domain explicitly identified by the user and confirmed in get_email_domains, or the app's configured sending domain when available. A registered domain alone is not proof it is the default sender. If the sender is ambiguous, ask which domain. Do not infer it from a from address or silently substitute another domain. Check get_email_domains first: only state 2 (active) or 4 (manually_verified) is eligible for the domain-history lookup. State 1 (unverified) needs DNS verification; explain this prerequisite instead of running the check. State 3 (inactive) is deactivated. Do not treat a successful tiny-send check as proof of domain verification, because it skips the history lookup.
  • onesignalmcp_get_active_warm_up_schedulesList the email warmup ramps that are in flight for this app right now: which campaigns are ramping, and the app's combined day-by-day schedule with the planned quota and how much has actually gone out.Read-only

    Get Active Warm Up Schedules

    List the email warmup ramps that are in flight for this app right now: which campaigns are ramping, and the app's combined day-by-day schedule with the planned quota and how much has actually gone out. Nothing is saved. Returns notifications, one entry per running warmup campaign with its id and title, and total_schedule, an ordered list of days with start, quota (recipients planned for that day across every running ramp) and acked (how many actually went out). An empty notifications list means no ramp is running. Two uses. Before proposing a new ramp, call this to see whether one is already running, because recommended_warm_up_schedule pushes a new schedule out past any warmup already in flight and the user should be told why their ramp starts later than they asked for. When diagnosing deliverability, call this to find out whether the window being judged overlaps a live ramp: a ramp holds sending volume down deliberately, so low send counts and thin per-provider samples during one are expected and are not evidence of a delivery problem. App-scoped and live-only. It covers every running warmup on this app and says nothing about ramps that have finished, been canceled, or are still sitting on a draft. Neither notifications nor total_schedule carries a sending domain, and the quota and acked totals are summed across every running ramp, so on an app that sends from more than one domain a live ramp here may belong to a different domain than the one being asked about. Do not attribute one domain's numbers to a ramp without saying the ramp is app-wide. For those, read kind and email_warm_up on get_notification for the specific campaign. Within a day that is still under way acked lags quota, so acked below quota is not on its own a sign the ramp is failing.

    Inputs

    app_idstringrequired
    OneSignal App ID.
  • onesignalmcp_get_app_channel_availabilityGet enabled push, email, SMS, and In-App Messaging channels for an app.Read-only

    Get App Channel Availability

    Get enabled push, email, SMS, and In-App Messaging channels for an app. Returns only channel availability, not credentials or platform configuration.

    Inputs

    app_idstringrequired
    OneSignal app ID (UUID).
  • onesignalmcp_get_app_push_platformsRead which push platforms a OneSignal app already has credentials for.Read-only

    Get App Push Platforms

    Read which push platforms a OneSignal app already has credentials for. Use it during SDK setup before `provision_app_credentials`, and to check an iOS project's Bundle ID against the stored one. Returns only the non-secret presence fields of the app object: `apns_env` (set when an APNs credential is stored), `apns_key_id` and `apns_team_id` (set for a `.p8` key, empty for a `.p12` certificate), `apns_bundle_id` (the Bundle ID the stored APNs credential serves), `fcm_sender_id` (set when FCM is configured), `chrome_web_origin` (set when web push is configured), `safari_site_origin` (set when Safari web push has its own certificate), and `channels.push.platforms` (the server's list of configured push platforms). Credential contents are never returned. Upstream errors (401, 403, 404) pass through unchanged.

    Inputs

    app_idstringrequired
    The OneSignal app to read (UUID).
  • onesignalmcp_get_custom_eventsList the custom event definitions indexed for a OneSignal app, including each event's properties, sources, most recent occurrence, usage locations (segment/journey), storage and total counts, and retention duration.Read-only

    Get Custom Events

    List the custom event definitions indexed for a OneSignal app, including each event's properties, sources, most recent occurrence, usage locations (segment/journey), storage and total counts, and retention duration. Requires OAuth authentication.

    Inputs

    app_idstringrequired
    OneSignal app ID.
  • onesignalmcp_get_email_domainsGet email domain DNS verification status for the current app.Read-only

    Get Email Domains

    Get email domain DNS verification status for the current app. Returns all registered email domains, each with a state and with its DNS records (SPF, DKIM, DMARC, MX, tracking CNAME). DNS records. Every record carries a status: 3 (or "passed") means verified/passing; anything else (or "failed") is not. Use these to check whether a domain's DNS is set up correctly before suggesting DNS setup steps. Domain state. Separate from the records, each domain has a state field. It is either numeric (1 unverified, 2 active, 3 deactivated, 4 manually verified) or a string, where "inactive" means deactivated. Never name a deactivated domain (state 3 or "inactive") when listing or suggesting domains, even if all of its DNS records pass, and do not offer to reactivate it. The only exception: when a send or check_send_volume has already failed on that exact domain, say plainly that it is deactivated, because that explains the failure. This domain state is NOT the same field as email_platform_state from get_email_setup_status, where "3" means active (a healthy, fully configured sender); do not carry these semantics across. An empty result here does not mean the sender is deactivated: a sender configured directly with a third-party provider (e.g. Mailgun) can return no domains. If get_email_setup_status is available, read email_platform_state on its own terms rather than applying the deactivated domain state. History interpretation. Domain state describes current verification, not whether this domain sent mail previously. An unverified domain does not prove zero historical sends or a zero sending baseline. When reporting or history is unavailable for this state, say that history cannot be retrieved until the domain is active; never say there is no sending history, that this is its first send, or that an empty report proves nothing was sent.

    Inputs

    app_idstringrequired
    OneSignal App ID.
  • onesignalmcp_get_email_reputationRetrieve the app's overall (app-wide) email reputation summary: aggregate bounce rate and spam complaint rate across all sending, returned for the last 24 hours, 7 days, and 30 days.Read-only

    Get Email Reputation

    Retrieve the app's overall (app-wide) email reputation summary: aggregate bounce rate and spam complaint rate across all sending, returned for the last 24 hours, 7 days, and 30 days. These are the same app-wide rates OneSignal's abuse-prevention system tracks to automatically warn or disable an app that has a high bounce or spam-complaint rate, so this is the right tool when the user asks about their sending or account health, whether they are at risk of being flagged, blocked, or disabled, or their standing with OneSignal. This is app-wide (all sending domains combined), not per-domain or per-provider. For per-domain or per-provider deliverability and reputation (e.g. how a domain is doing at Gmail, Apple, or Outlook), use get_provider_metrics instead, and do not combine the two; their numbers will not reconcile. Each rate is computed only over mail sent in its own window and the response has no counts, so the 24-hour rate can rest on a handful of sends on a quiet day and you cannot see how many. Say its volume is unknown, give the 7- and 30-day rates with it, and do not set the 24-hour figure beside per-provider counts. If the user quotes a rate these figures do not show, say they do not match and do not guess why (a spike that settled, a stale screen). Abuse prevention judges the trailing 30 days (or the time since email was last disabled, if shorter), not the 24-hour or 7-day windows. It warns at a complaint rate of 0.03% to 0.08% or a bounce rate of 2% to 5%, and disables email sending above 0.08% complaints or 5% bounces, but only with at least 10 complaints or 250 bounces, which this response cannot show. These are far stricter than the per-provider bands in get_provider_metrics, so a complaint rate those bands call Okay can still draw a warning. These thresholds apply only to the app-wide rates here; never measure a per-provider or per-domain rate against them. This is a summary, not a diagnosis: it tells you the rates are bad, never why. When the user wants the cause — mail going to spam, blocks, throttling, bounces, complaints, a drop in delivery — load the email_deliverability skill before going further. It owns choosing the scope, and the domain warmup check that decides whether suppressed volume is a ramp working or a real delivery problem.

    Inputs

    app_idstringrequired
    OneSignal App ID.
  • onesignalmcp_get_journeyGet the complete public Journey graph and current concurrency key for an app and Journey.Read-only

    Get Journey

    Get the complete public Journey graph and current concurrency key for an app and Journey.

    Inputs

    app_idstringrequired
    OneSignal app ID (UUID).
    journey_idstringrequired
    Journey ID (UUID).