> ## 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 (Beta)

> OneSignal MCP Server connects AI assistants to your OneSignal app so you can manage users, segments, templates, messaging, and exports with natural-language prompts.

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.

<Warning>
  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`.
</Warning>

## What is MCP?

[Model Context Protocol (MCP)](https://modelcontextprotocol.io/docs/getting-started/intro) 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.

## What can I do with this?

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

## Set up the OneSignal MCP server

You can usually complete setup in about 5 minutes.

### Prerequisites

You need:

* A OneSignal App ID from **Settings > Keys & IDs**, or from the URL when you're logged into the OneSignal dashboard
* A OneSignal REST API key from **Settings > Keys & IDs**
* A supported MCP client (see options below)

<Warning>
  `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.
</Warning>

### Connection details

Every client connects to the same server URL:

```text theme={null}
https://server.smithery.ai/onesignal/onesignal
```

After you add the server in your client, the first connection attempt opens a hosted **Connect OneSignal** page in your browser where you enter your **App ID** and **REST API key**. Your credentials are stored with the connection and reused on subsequent requests, so you only do this once per client.

Each MCP server configuration is scoped to one `app_id`. If you manage multiple OneSignal apps, create one MCP configuration per app.

### Configure your AI client

Pick the tab that matches the type of client you use, then follow the steps for your specific app.

<Tabs>
  <Tab title="Chatbots (Claude)">
    #### Claude (Claude Desktop and Claude.ai)

    Add the OneSignal MCP server through Claude's **Connectors** UI. Remote MCP servers cannot be added through `claude_desktop_config.json` — that file is only for local stdio servers.

    <Steps>
      <Step title="Open Connectors settings">
        In Claude Desktop, open **Settings > Connectors**. On claude.ai, open **Settings > Connectors** in the web app.
      </Step>

      <Step title="Add a custom connector">
        Click **Add custom connector** and provide:

        * **Name:** `OneSignal`
        * **Remote MCP server URL:** `https://server.smithery.ai/onesignal/onesignal`

        Then click **Add** (or **Connect**).
      </Step>

      <Step title="Enter your OneSignal credentials">
        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.
      </Step>

      <Step title="Use OneSignal in a new chat">
        Enable the OneSignal connector in any new chat. Claude lists the connector's tools when the connection succeeds.
      </Step>
    </Steps>
  </Tab>

  <Tab title="Coding tools (Claude Code, Codex, Copilot, Cursor)">
    #### Claude Code

    <Steps>
      <Step title="Add the OneSignal MCP server">
        Run the following command in your terminal:

        ```bash theme={null}
        claude mcp add --transport http onesignal https://server.smithery.ai/onesignal/onesignal
        ```
      </Step>

      <Step title="Authenticate from inside Claude Code">
        Start `claude`, then type `/mcp` to open the MCP panel. Select **onesignal**, then choose **Authenticate** to open the **Connect OneSignal** page in your browser.
      </Step>

      <Step title="Enter your OneSignal credentials">
        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**.
      </Step>
    </Steps>

    Verify with `claude mcp list` or run `/mcp` inside Claude Code to view the tool count.

    #### Codex CLI

    <Steps>
      <Step title="Add OneSignal to your Codex config">
        Open `~/.codex/config.toml` (create the file if it does not exist) and add:

        ```toml theme={null}
        [mcp_servers.onesignal]
        url = "https://server.smithery.ai/onesignal/onesignal"
        enabled = true
        ```
      </Step>

      <Step title="Authenticate with OneSignal">
        Run the following command in your terminal:

        ```bash theme={null}
        codex mcp login onesignal
        ```

        Codex opens the **Connect OneSignal** page in your browser. Enter your **App ID** and **API Key**, then click **Connect**.
      </Step>
    </Steps>

    Restart Codex and the OneSignal tools become available in your next session.

    #### GitHub Copilot (VS Code)

    <Steps>
      <Step title="Add OneSignal to your VS Code MCP config">
        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"
            }
          }
        }
        ```
      </Step>

      <Step title="Authenticate when prompted">
        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**.
      </Step>
    </Steps>

    #### Cursor

    <Steps>
      <Step title="Add OneSignal to your Cursor MCP config">
        Use `~/.cursor/mcp.json` to enable OneSignal across all projects, or `.cursor/mcp.json` inside a project to share with your team:

        ```json theme={null}
        {
          "mcpServers": {
            "onesignal": {
              "url": "https://server.smithery.ai/onesignal/onesignal"
            }
          }
        }
        ```
      </Step>

      <Step title="Authenticate from Cursor settings">
        Restart Cursor and open **Settings > MCP & Integrations**. Click **Authenticate** (or **Needs login**) next to the OneSignal server to open the **Connect OneSignal** page in your browser. Enter your **App ID** and **API Key**, then click **Connect**.
      </Step>
    </Steps>
  </Tab>
</Tabs>

### Verify the connection

After setup, start a new chat and ask your assistant:

```text theme={null}
Use the onesignal_health tool to check if the server is connected.
```

If the tool returns `ok`, your connection is working.

### Troubleshooting

If a request fails unexpectedly, try the following in order:

* Confirm the API key value you provided on the **Connect OneSignal** page is the secret value shown when you created the key — not the `Key ID`.
* Re-check that the server URL is exactly `https://server.smithery.ai/onesignal/onesignal` with no extra paths or trailing characters.
* Re-authenticate the server from your client's MCP panel (`/mcp` in Claude Code, **Settings > MCP & Integrations** in Cursor, **MCP** view in VS Code, or `codex mcp login onesignal` for Codex).
* Restart the MCP client and start a new chat session. This resolves most transient connection and session issues.

## MCP tool capabilities

OneSignal MCP Server currently supports 31 tools across 7 categories.

### 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` |

### 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

* 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, Claude.ai, Claude Code, OpenAI Codex, GitHub Copilot in VS Code, Cursor, and any other MCP-compatible client that supports remote Streamable HTTP servers.

### 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. 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`.