OneSignal MCP Server lets MCP-compatible AI assistants run OneSignal actions directly — look up a user, check delivery stats, send a test message, or export subscribers — without leaving your editor or AI client.
OneSignal MCP Server is currently in beta. You may see issues, incomplete behavior, or temporary glitches while we continue improving the experience. If you run into problems, contact support@onesignal.com.
What is MCP?
Model Context Protocol (MCP) is an open-source standard for connecting AI applications to external systems. OneSignal MCP Server lets MCP-compatible assistants run OneSignal actions without switching dashboard pages.
Why this matters
You can complete common OneSignal workflows faster with natural-language prompts.
- Run multi-step tasks in one request, like finding a user, checking subscriptions, and sending a test message
- Reduce onboarding friction for teams that are new to the dashboard or REST API
- Manage day-to-day campaign and user operations directly in your editor or AI client
Common use cases
You can ask your AI assistant to:
- Send a message to a specific segment
- Look up a user and list all subscriptions
- Check delivery metrics for a recent message
- Create a segment from audience filters
- Create a user and attach email, SMS, or push subscriptions
- Export subscribers or audience activity to CSV
OneSignal MCP Server currently supports 31 tools across 7 categories.
| Action | Tool |
|---|
| Send a push notification, email, or SMS/RCS | send_message |
| List recent notifications | list_messages |
| View notification details and delivery stats | view_message |
| Action | Tool |
|---|
| Look up a user by alias | view_user |
| Get a user’s identity aliases | get_user_identity |
| Get identity by subscription ID | get_user_identity_by_subscription |
| Create a new user with properties | create_user |
| Update user properties (tags, language, and more) | update_user |
| Add or update identity aliases | create_or_update_alias |
| Add aliases via subscription ID | create_alias_by_subscription |
| Add a push, email, or SMS subscription | create_subscription |
| Update an existing subscription | update_subscription |
| Update a subscription by token | update_subscription_by_token |
| Unsubscribe an email address | unsubscribe_email |
| Transfer a subscription to a different user | transfer_subscription |
| Action | Tool |
|---|
| List templates | list_templates |
| View a template | get_template |
| Create a template | create_template |
| Update a template | update_template |
| Action | Tool |
|---|
| List segments | list_segments |
| View a segment and filters | get_segment |
| Create a segment | create_segment |
| Update a segment | update_segment |
| Action | Tool |
|---|
| Start an iOS Live Activity | start_live_activity |
| Update or end a Live Activity | update_live_activity |
| Action | Tool |
|---|
| Export subscriptions to CSV | export_subscriptions_csv |
| Export notification audience activity to CSV | export_audience_activity_csv |
| Action | Tool |
|---|
| View outcome analytics | view_outcomes |
| Check server health | onesignal_health |
| View server configuration | onesignal_config |
| View a reference overview of all tools | onesignal_reference_overview |
Set up the OneSignal MCP server
You can usually complete setup in about 5 minutes through Smithery.
Prerequisites
You need:
- A OneSignal App ID from Settings > Keys & IDs
- A OneSignal REST API key from Settings > Keys & IDs
- A supported MCP client, such as Claude Desktop, Cursor, ChatGPT, Gemini, or another MCP-compatible client
Key ID is not the same as a REST API key. The REST API key value is shown only once when you create it. If you do not already have the key value saved, create a new API key. We recommend creating a dedicated API key for MCP access.
Open the OneSignal MCP server on Smithery
Select the setup flow for humans
In the right pane, select Humans.
Choose your AI client
Select your client and follow the setup instructions shown in Smithery.
Add your app credentials
Provide your app_id and api_key for the OneSignal app you want to connect.
app_id. If you manage multiple OneSignal apps, create one MCP configuration per app.
Verify the connection
After setup, ask your assistant:
Use the onesignal_health tool to check if the server is connected.
ok, your connection is working.
Troubleshooting
If a request fails unexpectedly, restart the MCP server and start a new chat session first. This resolves most transient connection and session issues.
Safety and guardrails
OneSignal MCP Server includes built-in protections for high-impact actions.
send_message protections
- AI clients treat
send_message as a high-impact action and ask for confirmation before execution
send_message has a lower rate limit (30 requests per minute) than other tools- Targeting is validated before send (single targeting method, capped filters, recipient limits)
- Inputs are validated before execution, including identifiers and contact fields
Additional controls
- Access is controlled per app and can be enabled or disabled by OneSignal
- Per-session rate limits help prevent runaway tool loops
- The MCP server is stateless and does not store customer data
Known limitations
- One MCP configuration supports one OneSignal app (
app_id)
- Sessions expire after inactivity and automatically re-establish on the next request
- During open beta, app access may require enablement before non-utility tools are available
FAQ
What AI clients can I use with OneSignal MCP Server?
You can use Claude Desktop, Cursor, ChatGPT, Gemini, VS Code clients with MCP support, and other MCP-compatible tools available through Smithery.
The MCP server is free. MCP tool calls still count against your normal OneSignal API usage limits, and your AI client may have separate usage costs.
Why does my Key ID not work as api_key?
Key ID is an identifier, not the secret API key value. MCP setup requires the REST API key value that is shown one time when the key is created. If you no longer have that value, create a new API key and use that key value in your MCP configuration.
Can AI send notifications without my approval?
No. send_message is flagged as a high-impact action, and compatible MCP clients ask for confirmation before running it.
Is customer data stored by the MCP server?
No. OneSignal MCP Server is stateless and does not store your customer data.
How do I use MCP with multiple OneSignal apps?
Create one MCP server configuration per app. Each configuration uses its own app_id and api_key. 
