> ## 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.
This page is about OneSignal MCP Server, which exposes OneSignal to *external* AI clients. It is not the same as the *MCP connections* feature inside the OneSignal AI Agent, which lets the AI Agent consume *external* MCP servers. See [AI data practices](./ai-data-practices#mcp-connections) for that feature.
## 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.
How you connect depends on your AI client:
| Client | Recommended setup | Authentication |
| -------------------------------------- | ------------------------------------------------------------------------------------------------ | ---------------------------------- |
| Cursor | Official [Cursor Marketplace](https://cursor.com/marketplace/onesignal) plugin | OneSignal OAuth (no API key paste) |
| ChatGPT / Codex | Official OpenAI / ChatGPT plugins marketplace listing | OneSignal OAuth (no API key paste) |
| Claude Desktop, Claude.ai, Claude Code | [Smithery](https://smithery.ai)-hosted MCP URL (Claude official registry listing is in progress) | App ID + REST API key |
| GitHub Copilot and other MCP clients | Smithery-hosted MCP URL | App ID + REST API key |
### Prerequisites
**For Cursor and ChatGPT / Codex (marketplace plugins):**
* A OneSignal account with access to the apps you want to manage
* Permission to authorize OneSignal through the browser-based OAuth flow
You do not need to paste a OneSignal REST API key into these clients.
**For Claude, GitHub Copilot, and other Smithery-connected clients:**
* A OneSignal App ID from [Settings > Keys & IDs](./keys-and-ids#app-id), or from the URL when you're logged into the OneSignal dashboard
* A OneSignal REST API key from [Settings > Keys & IDs](./keys-and-ids#app-api-key) (not the Key ID)
* A supported AI client (see options below)
### Connection details
#### Marketplace plugins (Cursor and OpenAI)
Official Cursor and OpenAI marketplace plugins connect to OneSignal's hosted OAuth MCP endpoint:
```text theme={null}
https://mcp.onesignal.com/mcp/oauth
```
When you install the plugin, your client opens OneSignal's browser authorization flow. Sign in and approve access. The connection uses your OneSignal account permissions — you do not paste an App ID or REST API key.
#### Smithery (Claude and other clients)
Claude and other MCP clients that are not yet on an official marketplace connect through [Smithery](https://smithery.ai):
```text theme={null}
https://server.smithery.ai/onesignal/onesignal
```
After you add the server, the first connection opens a hosted **Connect OneSignal** page where you enter your **App ID** and **API key**. Your credentials are stored on the Smithery-hosted bridge so the connection stays authenticated. They are not stored on OneSignal MCP Server itself, and no customer data (subscribers, messages, exports) is persisted server-side.
Each Smithery MCP configuration is scoped to one `app_id`. If you manage multiple OneSignal apps with Smithery, create one MCP configuration per app. Marketplace OAuth connections can work across apps your account can access (for example with `list_apps`).
### 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. Prefer the marketplace plugin over adding the Smithery URL by hand.
#### 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. You do not paste an App ID or REST API key.
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. Prefer the marketplace plugin over adding a manual Smithery MCP URL.
#### Claude (Claude Desktop and Claude.ai)
OneSignal is working toward listing in Claude's official MCP registry. Until that listing is available, add OneSignal through Claude's **Connectors** UI with the Smithery-hosted URL. Remote MCP servers cannot be added through `claude_desktop_config.json`, which is only for local stdio servers.
In Claude Desktop, open **Settings > Connectors**. On claude.ai, open **Settings > Connectors** in the web app.
Click **Add custom connector** and provide:
* **Name:** `OneSignal`
* **Remote MCP server URL:** `https://server.smithery.ai/onesignal/onesignal`
Leave **OAuth Client ID** and **OAuth Client Secret** under **Advanced settings** blank. OneSignal MCP Server handles authentication through the **Connect OneSignal** page in the next step, so filling these fields causes the connection to fail with `invalid_client`.
Then click **Add** (or **Connect**).
A **Connect OneSignal** dialog opens. Enter your:
* **App ID:** your OneSignal App ID
* **API key:** your OneSignal REST API key
Click **Connect** to finish the setup.
Enable the OneSignal connector in any new chat. Claude lists the connector's tools when the connection succeeds.
#### Claude Code
Until Claude's official registry listing is available, connect Claude Code through Smithery.
Run the following command in your terminal:
```bash theme={null}
claude mcp add --transport http onesignal https://server.smithery.ai/onesignal/onesignal
```
Start `claude`, then type `/mcp` to open the MCP panel. Select **onesignal**, then choose **Authenticate** to open the **Connect OneSignal** page in your browser.
On the **Connect OneSignal** page, enter your **App ID** and **API key**, then click **Connect**. 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.
#### GitHub Copilot (VS Code)
Use the Smithery-hosted URL for GitHub Copilot and other clients without an official OneSignal marketplace listing.
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://server.smithery.ai/onesignal/onesignal"
}
}
}
```
Open Copilot Chat in **Agent mode**. The first time the OneSignal tools are needed, VS Code prompts you to authenticate and opens the **Connect OneSignal** page in your browser. Enter your **App ID** and **API key**, then click **Connect**.
### 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. On marketplace OAuth connections, you can also ask the client to list the apps your account can access.
### Troubleshooting
If a request fails unexpectedly, try the following in order:
* **Marketplace plugins (Cursor / ChatGPT / Codex):** Re-authenticate from the client's plugin or MCP settings, confirm your OneSignal account can access the target app, then start a new chat.
* **Smithery clients:** Re-check that the server URL is exactly `https://server.smithery.ai/onesignal/onesignal` with no extra paths or trailing characters, then re-authenticate from your client's MCP panel (`/mcp` in Claude Code, **MCP** view in VS Code).
* Restart the AI client and start a new chat session. This resolves most transient connection and session issues.
#### `invalid_client` error in Claude
If Claude returns `{"error":"invalid_client","error_description":"Invalid client_id"}` when you connect, the custom connector was created with values in **OAuth Client ID** or **OAuth Client Secret**. OneSignal MCP Server does not use those fields. Disconnecting is not enough. You must remove the connector entirely and recreate it:
1. In Claude, open **Settings > Connectors**, find the OneSignal connector, and click **Remove** (not just **Disconnect**).
2. Click **Add custom connector** again and enter only the **Name** and **Remote MCP server URL**. Leave **OAuth Client ID** and **OAuth Client Secret** blank.
3. Click **Add**, then complete the **Connect OneSignal** page with your **App ID** and **API key**.
## MCP tool capabilities
OneSignal MCP Server currently supports 34 tools across 9 categories.
### Apps (1 tool)
| Action | Tool |
| ---------------------------------------------------- | ----------- |
| List apps accessible to the authenticated OAuth user | `list_apps` |
`list_apps` requires an OAuth connection (for example Cursor or ChatGPT / Codex marketplace plugins).
### Messaging (3 tools)
| 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` |
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` |
`get_custom_events` requires an OAuth connection (for example Cursor or ChatGPT / Codex marketplace plugins).
### 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
* Compatible 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 your customer data (subscribers, messages, exports)
## Known limitations
* Smithery configurations support one OneSignal app (`app_id`) per MCP server entry
* Marketplace OAuth connections follow the signed-in user's account permissions and can access multiple apps
* 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
* Some tools (`list_apps`, `get_custom_events`) require OAuth and are not available on API-key / Smithery connections
## FAQ
### What AI clients can I use with OneSignal MCP Server?
You can use Cursor, ChatGPT, OpenAI Codex, Claude Desktop, Claude.ai, Claude Code, GitHub Copilot in VS Code, and any other MCP-compatible client that supports remote Streamable HTTP servers. Prefer the official marketplace plugins for Cursor and OpenAI clients.
### 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.
### Why does my `Key ID` not work as `api_key`?
`Key ID` is an identifier, not the secret API key value. Smithery 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](./keys-and-ids#app-api-key) and use that key value in your MCP configuration. Cursor and ChatGPT / Codex marketplace plugins use OAuth instead and do not need a REST API key.
### Can AI send notifications without my approval?
No. `send_message` is flagged as a high-impact action, and compatible AI 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. For Smithery connections, your App ID and API key are stored on the Smithery-hosted bridge so the connection stays authenticated; they are not stored on OneSignal MCP Server itself. Marketplace plugins authenticate with OneSignal OAuth and do not store your REST API key in the MCP client config.
### How do I use MCP with multiple OneSignal apps?
* **Marketplace OAuth (Cursor, ChatGPT / Codex):** One connection can access the apps your OneSignal account is allowed to manage. Use `list_apps` when you need to discover app IDs.
* **Smithery:** Create one MCP server configuration per app. Each configuration uses its own `app_id` and `api_key`.
## Related pages
Find your App ID and API key values, and learn how to rotate them safely.
Reference for the underlying endpoints OneSignal MCP Server calls.
Endpoint reference for `send_message` and other messaging tools.
How OneSignal handles data inside AI features, including MCP connections.