> ## Documentation Index
> Fetch the complete documentation index at: https://documentation.onesignal.com/llms.txt
> Use this file to discover all available pages before exploring further.
# OneSignal MCP Server
> Connect MCP-compatible AI clients to OneSignal so you can manage users, segments, templates, messaging, and exports with natural-language prompts.
OneSignal MCP Server lets MCP-compatible AI clients run OneSignal actions directly. Look up a user, check delivery stats, send a test message, or export subscribers without leaving your AI client.
## What is MCP?
[Model Context Protocol (MCP)](https://modelcontextprotocol.io/docs/getting-started/intro) is an open standard, originally created by Anthropic, for connecting AI applications to external systems. It is now supported by major AI clients including Claude, Cursor, GitHub Copilot, ChatGPT, and OpenAI Codex. OneSignal MCP Server lets any of these clients run OneSignal actions without switching dashboard pages.
## Why use OneSignal MCP Server
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 AI client
## Common use cases
You can ask your AI client 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
* List apps you can access, or look up custom event definitions
* Export subscribers or audience activity to CSV
## Set up OneSignal MCP Server
You can usually complete setup in about 5 minutes. Every supported client connects to the same URL and authenticates with your OneSignal account via OAuth.
OneSignal is listed in the [Claude connectors directory](https://claude.ai/directory), the [Cursor Marketplace](https://cursor.com/marketplace/onesignal), and the OpenAI / ChatGPT plugins marketplace. In those clients you install OneSignal from the client's own directory or marketplace, and sign-in starts automatically — there is no server URL to paste. Other MCP-compatible clients can connect using the same OneSignal sign-in flow.
### Connection details
All MCP clients connect to OneSignal's hosted MCP endpoint:
```text theme={null}
https://api.onesignal.com/mcp/oauth
```
### Supported clients
| Client | Recommended setup |
| - | - |
| Cursor | Official [Cursor Marketplace](https://cursor.com/marketplace/onesignal) plugin |
| ChatGPT / Codex | Official OpenAI / ChatGPT plugins marketplace listing |
| Claude (Desktop, claude.ai, mobile) | Official listing in the [Claude connectors directory](https://claude.ai/directory) |
| Claude Code | `claude mcp add` with the OneSignal MCP URL |
| Any other MCP client (GitHub Copilot, Windsurf, custom clients) | Add the OneSignal MCP URL in your client's remote MCP config |
### Prerequisites
* A OneSignal account with access to the apps you want to manage
* Permission to authorize OneSignal through the browser-based OAuth flow
* An AI client that either:
* Installs OneSignal from the Claude connectors directory, the Cursor Marketplace, or the OpenAI plugin directory, or
* Supports remote MCP servers with OneSignal sign-in
### Configure your AI client
Pick the section for your AI client and follow the steps.
#### Cursor
Install OneSignal from the official Cursor Marketplace. This is the recommended path for Cursor.
Go to the [OneSignal Cursor Marketplace page](https://cursor.com/marketplace/onesignal), or search for **OneSignal** in Cursor's marketplace / plugin browser.
Click **Add to Cursor** (or install from Cursor's Customize / marketplace UI). Cursor installs the OneSignal plugin, including the hosted MCP server.
Open **Settings > MCP & Integrations**. Click **Authenticate** (or **Needs login**) next to the OneSignal server. Cursor opens OneSignal's OAuth page in your browser — sign in and approve access.
Start a new Agent chat and ask OneSignal to run a read-only check, such as `onesignal_health` or listing your apps.
Manual `mcp.json` setup is not required when you install from the marketplace. If you prefer to configure it by hand, point Cursor at `https://api.onesignal.com/mcp/oauth`.
#### ChatGPT and Codex (OpenAI)
Install OneSignal from the official OpenAI / ChatGPT plugins marketplace. This is the recommended path for ChatGPT and Codex.
In ChatGPT, open **Plugins** (or **Work → Plugins** in the ChatGPT desktop app / Codex surfaces). You can also browse [chatgpt.com/plugins](https://chatgpt.com/plugins).
Search for **OneSignal** and install the official OneSignal plugin.
When prompted to connect or authenticate, complete OneSignal's OAuth consent in the browser. Sign in and approve access.
Start a new chat, invoke OneSignal (for example with `@OneSignal`), and try a read-only prompt such as checking server health or listing apps you can access.
For Codex CLI or the IDE extension, install the same official OneSignal plugin from the OpenAI plugin directory, then authenticate when prompted.
#### Claude (Claude Desktop, claude.ai, and mobile)
Install OneSignal from the [Claude connectors directory](https://claude.ai/directory). This is the recommended path for Claude, and it requires no server URL or OAuth credentials.
In Claude, click the **+** button in the lower left of the chat, then click **+** next to **Connectors**. You can also open **Settings > Connectors** in Claude Desktop or on claude.ai, or browse [claude.ai/directory](https://claude.ai/directory).
Search for **OneSignal**, then click **Connect**. The directory listing supplies the MCP server URL and OAuth client identity for you.
Claude opens OneSignal's sign-in page in your browser. Sign in and approve access for Claude. You do not enter an App ID or REST API key.
Enable the OneSignal connector in any new chat. Claude lists the connector's tools when the connection succeeds.
If you added OneSignal as a custom connector before it was listed in the directory, remove that connector and reconnect from the directory.
Use this only if you cannot install from the directory. Remote MCP servers cannot be added through `claude_desktop_config.json`, which is only for local stdio servers.
1. Open **Settings > Connectors** and click **Add custom connector**.
2. Provide:
* **Name:** `OneSignal`
* **Remote MCP server URL:** `https://api.onesignal.com/mcp/oauth`
3. Leave **OAuth Client ID** and **OAuth Client Secret** under **Advanced settings** blank. OneSignal registers your client automatically, so filling these fields causes the connection to fail.
4. Click **Add** (or **Connect**), then complete the OneSignal sign-in and consent flow in your browser.
#### Claude Code
Run the following command in your terminal:
```bash theme={null}
claude mcp add --transport http onesignal https://api.onesignal.com/mcp/oauth
```
Start `claude`, then type `/mcp` to open the MCP panel. Select **onesignal**, then choose **Authenticate** to open OneSignal's sign-in page in your browser.
Sign in and approve access. Return to Claude Code and the server status changes to **connected**.
Verify with `claude mcp list` or run `/mcp` inside Claude Code to view the tool count.
#### Any other MCP client
Clients without an official OneSignal listing can connect if they support remote MCP servers and OneSignal sign-in.
Use your client's remote MCP server settings and add `https://api.onesignal.com/mcp/oauth`. For GitHub Copilot in VS Code, use `.vscode/mcp.json` in your workspace to share with your team, or run **MCP: Open User Configuration** from the Command Palette to install for your user profile:
```json theme={null}
{
"servers": {
"onesignal": {
"type": "http",
"url": "https://api.onesignal.com/mcp/oauth"
}
}
}
```
The first time the OneSignal tools are needed, your client prompts you to authenticate and opens OneSignal's sign-in page in your browser. Sign in and approve access.
Your client should list the OneSignal tools once the connection succeeds. Try a read-only prompt such as `onesignal_health`.
Leave OAuth client ID and secret fields blank unless your client's OneSignal integration specifically provides values for them. The Claude connectors directory, Cursor Marketplace, and OpenAI listings handle this for you.
### Verify the connection
After setup, start a new chat and ask your AI client:
```text theme={null}
Use the onesignal_health tool to check if the server is connected.
```
If the response indicates the server is healthy, your connection is working. You can also ask the client to list the apps your account can access.
### Manage and revoke access
Every AI client you connect appears under **Settings > Account settings > Connected apps**, or at [dashboard.onesignal.com/settings/connected-apps](https://dashboard.onesignal.com/settings/connected-apps). From there you can:
* Review which AI clients have access and when they were authorized
* Revoke a client's access at any time, which revokes the tokens granted to that client
Connections follow the permissions of the OneSignal user who authorized them. Revoking access does not affect other members of your organization. For details on how OneSignal handles data in AI features, see [AI data practices](./ai-data-practices).
### Troubleshooting
If a request fails unexpectedly, try the following in order:
* **Re-authenticate.** Open your client's plugin or MCP settings and reconnect OneSignal, then start a new chat.
* **Check the server URL.** Confirm it is exactly `https://api.onesignal.com/mcp/oauth` with no extra paths or trailing characters.
* **Confirm app access.** Make sure the signed-in OneSignal account can access the app you're asking about.
* **Restart the AI client** and start a new chat session. This resolves most transient connection and session issues.
## MCP tool capabilities
OneSignal MCP Server currently supports 43 tools across 11 categories.
### Apps (1 tool)
| Action | Tool |
| - | - |
| List apps accessible to the authenticated user | `list_apps` |
### Messaging (3 tools)
| Action | Tool |
| - | - |
| Send a push notification, email, or SMS | `send_message` |
| List recent notifications | `list_messages` |
| View notification details and delivery stats | `view_message` |
To start or update a Live Activity, see [Live Activities](#live-activities-2-tools) below.
### Users and subscriptions (12 tools)
| 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` |
### Templates (4 tools)
| Action | Tool |
| - | - |
| List templates | `list_templates` |
| View a template | `get_template` |
| Create a template | `create_template` |
| Update a template | `update_template` |
### Segments (4 tools)
| Action | Tool |
| - | - |
| List segments | `list_segments` |
| View a segment and filters | `get_segment` |
| Create a segment | `create_segment` |
| Update a segment | `update_segment` |
### Live Activities (2 tools)
| Action | Tool |
| - | - |
| Start an iOS Live Activity | `start_live_activity` |
| Update or end a Live Activity | `update_live_activity` |
### Exports (2 tools)
| Action | Tool |
| - | - |
| Export subscriptions to CSV | `export_subscriptions_csv` |
| Export notification audience activity to CSV | `export_audience_activity_csv` |
### Custom events (2 tools)
| Action | Tool |
| - | - |
| Create custom events for users | `create_custom_events` |
| List indexed custom event definitions | `get_custom_events` |
### Email deliverability (4 tools)
| Action | Tool |
| - | - |
| Check email domain DNS verification status (SPF, DKIM, DMARC) | `get_email_domains` |
| View app-wide bounce and spam complaint rates | `get_email_reputation` |
| Get per-inbox-provider deliverability metrics for a domain | `get_provider_metrics` |
| Get a time series of provider deliverability metrics | `get_provider_metrics_timeseries` |
### Email warmup (5 tools)
| Action | Tool |
| - | - |
| Check whether a send needs IP or domain warmup | `check_send_volume` |
| Estimate recipient count from segments and filters | `estimate_recipient_count` |
| Get a recommended staged warmup schedule | `recommended_warm_up_schedule` |
| Apply a warmup schedule to a draft campaign | `apply_warm_up_schedule` |
| List warmup schedules currently in flight | `get_active_warm_up_schedules` |
### Analytics and utility (4 tools)
| 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` |
## Safety and guardrails
OneSignal MCP Server includes built-in protections for high-impact actions.
### `send_message` protections
* `send_message` is marked as a high-impact action, so compatible AI clients may ask for confirmation before running it
* Targeting is validated before send (only one targeting method at a time, and filters are capped)
* Inputs are validated before execution, including identifiers and contact fields such as email addresses and phone numbers
### Additional controls
* Access is controlled per app and can be enabled or disabled by OneSignal
* Tool calls are rate limited to help prevent runaway tool loops
* The MCP server does not store your customer data (subscribers, messages, exports)
* You can revoke any connected AI client from **Settings > Account settings > Connected apps**
## Known limitations
* Your connection follows the signed-in user's account permissions and can access multiple apps
* During open beta, app access may require enablement before non-utility tools are available
* Clients that only support local `stdio` MCP servers cannot connect
## FAQ
### What AI clients can I use with OneSignal MCP Server?
Any MCP-compatible client that supports remote servers and OneSignal sign-in can connect. OneSignal is listed in the [Claude connectors directory](https://claude.ai/directory), the [Cursor Marketplace](https://cursor.com/marketplace/onesignal), and the OpenAI / ChatGPT plugins marketplace; other compatible clients connect directly with the MCP URL.
### Do I need a REST API key?
No. All supported connections use OneSignal OAuth. You sign in through your browser and approve access — there is no API key to copy, store, or rotate in your AI client config.
### Does OneSignal MCP Server cost extra?
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.
### Can AI send notifications without my approval?
`send_message` is marked as a high-impact action, and compatible AI clients may ask for confirmation before running it. Always review send requests before approving them in your AI client.
### Is customer data stored by the MCP server?
No. OneSignal MCP Server does not store your customer data (subscribers, messages, or exports). Your connection is an OAuth grant tied to your OneSignal account, which you can revoke at any time from **Settings > Account settings > Connected apps**.
### How do I use MCP with multiple OneSignal apps?
One connection can access the apps your OneSignal account is allowed to manage. Use `list_apps` when you need to discover app IDs. You do not need a separate configuration per app.
## Related pages
Reference for the underlying endpoints OneSignal MCP Server calls.
Endpoint reference for `send_message` and other messaging tools.
How OneSignal handles data for AI features and Customer AI Agent connections.
This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.