OneSignal MCP Server

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.

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 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, 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 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
Export subscribers or audience activity to CSV

Set up 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 (not the Key ID)
A supported AI client (see options below)

Connection details

Every client connects to the same server URL:

https://server.smithery.ai/onesignal/onesignal

OneSignal MCP Server is hosted on Smithery, an MCP hosting provider. 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 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 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 section for your AI client and follow the steps.

Claude (Claude Desktop and Claude.ai)

Add OneSignal MCP Server through Claude’s Connectors UI. Remote MCP servers cannot be added through claude_desktop_config.json, which is only for local stdio servers.

Open Connectors settings

In Claude Desktop, open Settings > Connectors. On claude.ai, open Settings > Connectors in the web app.

Add a custom connector

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).

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.

Use OneSignal in a new chat

Enable the OneSignal connector in any new chat. Claude lists the connector’s tools when the connection succeeds.

Claude Code

Add OneSignal MCP Server

Run the following command in your terminal:

claude mcp add --transport http onesignal https://server.smithery.ai/onesignal/onesignal

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.

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.

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

Codex CLI

Add OneSignal to your Codex config

Open ~/.codex/config.toml (create the file if it does not exist) and add:

[mcp_servers.onesignal]
url = "https://server.smithery.ai/onesignal/onesignal"
enabled = true

Authenticate with OneSignal

Run the following command in your terminal:

codex mcp login onesignal

Codex opens the Connect OneSignal page in your browser. Enter your App ID and API key, then click Connect.

Restart Codex

Restart Codex so it loads the new MCP server. The OneSignal tools become available in your next session.

GitHub Copilot (VS Code)

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:

{
  "servers": {
    "onesignal": {
      "type": "http",
      "url": "https://server.smithery.ai/onesignal/onesignal"
    }
  }
}

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.

Cursor

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:

{
  "mcpServers": {
    "onesignal": {
      "url": "https://server.smithery.ai/onesignal/onesignal"
    }
  }
}

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.

Verify the connection

After setup, start a new chat and ask your AI client:

Use the onesignal_health tool to check if the server is connected.

If the response indicates the server is healthy, your connection is working.

Troubleshooting

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

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

In Claude, open Settings > Connectors, find the OneSignal connector, and click Remove (not just Disconnect).
Click Add custom connector again and enter only the Name and Remote MCP server URL. Leave OAuth Client ID and OAuth Client Secret blank.
Click Add, then complete the Connect OneSignal page with your App ID and API key.

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

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

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

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.

Keys and IDs

Find your App ID and API key values, and learn how to rotate them safely.

REST API overview

Reference for the underlying endpoints OneSignal MCP Server calls.

Create message API

Endpoint reference for send_message and other messaging tools.

AI data practices

How OneSignal handles data inside AI features, including MCP connections.

​What is MCP?

​Why use OneSignal MCP Server

​Common use cases

​Set up OneSignal MCP Server

​Prerequisites

​Connection details

​Configure your AI client

​Claude (Claude Desktop and Claude.ai)

​Claude Code

​Codex CLI

​GitHub Copilot (VS Code)

​Cursor

​Verify the connection

​Troubleshooting

​invalid_client error in Claude

​MCP tool capabilities

​Messaging (3 tools)

​Users and subscriptions (12 tools)

​Templates (4 tools)

​Segments (4 tools)

​Live Activities (2 tools)

​Exports (2 tools)

​Analytics and utility (4 tools)

​Safety and guardrails

​send_message protections

​Additional controls

​Known limitations

​FAQ

​What AI clients can I use with OneSignal MCP Server?

​Does OneSignal MCP Server cost extra?

​Why does my Key ID not work as api_key?

​Can AI send notifications without my approval?

​Is customer data stored by the MCP server?

​How do I use MCP with multiple OneSignal apps?

​Related pages

Keys and IDs

REST API overview

Create message API

AI data practices

What is MCP?

Why use OneSignal MCP Server

Common use cases

Set up OneSignal MCP Server

Prerequisites

Connection details

Configure your AI client

Claude (Claude Desktop and Claude.ai)

Claude Code

Codex CLI

GitHub Copilot (VS Code)

Cursor

Verify the connection

Troubleshooting

`invalid_client` error in Claude

MCP tool capabilities

Messaging (3 tools)

Users and subscriptions (12 tools)

Templates (4 tools)

Segments (4 tools)

Live Activities (2 tools)

Exports (2 tools)

Analytics and utility (4 tools)

Safety and guardrails

`send_message` protections

Additional controls

Known limitations

FAQ

What AI clients can I use with OneSignal MCP Server?

Does OneSignal MCP Server cost extra?

Why does my `Key ID` not work as `api_key`?

Can AI send notifications without my approval?

Is customer data stored by the MCP server?

How do I use MCP with multiple OneSignal apps?

Related pages