Prerequisites
- A OneSignal account with access to the OneSignal apps you want to manage.
- Permission to approve OneSignal access through OAuth, the browser-based sign-in OneSignal uses.
- An AI tool that supports remote MCP servers over HTTP with OAuth.
Connection details
Every AI tool connects to the same hosted endpoint:Set up your AI tool
Cursor
Install OneSignal from the Cursor Marketplace.1
Open the OneSignal plugin
Go to OneSignal in the Cursor Marketplace, or search for OneSignal in Cursor’s marketplace.
2
Install the plugin
Click Add to Cursor. Cursor installs the OneSignal plugin, including the MCP server.
3
Sign in to OneSignal
Open Settings > MCP & Integrations and click Authenticate next to OneSignal. Sign in in your browser and click Agree & Allow Access.
4
Use OneSignal in Agent chat
Start a new Agent chat and ask OneSignal to run a read-only check, such as listing your OneSignal apps.
mcp.json:
Claude Code
1
Add the OneSignal MCP server
Run the following command in your terminal:
2
Authenticate from inside Claude Code
Start
claude, then type /mcp to open the MCP panel. Select onesignal, then choose Authenticate to open the OneSignal sign-in page in your browser.3
Approve access
Sign in and click Agree & Allow Access. Return to Claude Code. The server status changes to connected.
claude mcp list, or /mcp inside Claude Code, to see the tool count.
Claude custom connector
Use a custom connector only when you can’t install OneSignal from the Claude directory. Remote MCP servers cannot be added throughclaude_desktop_config.json, which is only for local stdio servers.
1
Add a custom connector
Go to Customize > Connectors and click Add custom connector.
2
Enter the server details
Set Name to
OneSignal and Remote MCP server URL to https://api.onesignal.com/mcp/oauth. Leave OAuth Client ID and OAuth Client Secret under Advanced settings blank.3
Sign in to OneSignal
Click Add, then complete the OneSignal sign-in in your browser and click Agree & Allow Access.
Codex CLI
1
Open the plugin browser
Run
codex, then enter /plugins.2
Install OneSignal
Find OneSignal, open it, and install it.
3
Start a new session and sign in
Start a new session. When Codex asks you to authenticate, sign in to OneSignal in your browser and click Agree & Allow Access.
GitHub Copilot in VS Code
Add OneSignal to.vscode/mcp.json in your workspace to share it with your team, or run MCP: Open User Configuration from the Command Palette to install it for your user profile:
Other AI tools and agents
Addhttps://api.onesignal.com/mcp/oauth in your AI tool’s remote MCP server settings. The first time the AI tool calls a OneSignal tool, it opens the OneSignal sign-in page in your browser. Sign in and click Agree & Allow Access. Your AI tool lists the OneSignal tools once the connection succeeds.
Verify the connection
Start a new chat or session and send:onesignal_health. It responds before AI tool access is turned on, so a healthy result doesn’t confirm that the other tools work.
Troubleshooting
- Re-authenticate. Reconnect OneSignal from your AI tool’s MCP or connector settings, then start a new session.
-
Check the server URL. The URL must be exactly
https://api.onesignal.com/mcp/oauth, with no extra path or trailing characters. - Clear OAuth client fields. If your AI tool has OAuth client ID or secret fields, leave them blank.
- Check AI tool access. If a tool returns “tool access is not enabled for this application”: OneSignal hasn’t turned on AI tool access for your OneSignal login yet. Contact OneSignal support.
- Restart your AI tool and start a new session. This resolves most transient connection issues.
Tools
Explore the tools below. Tool discovery depends on MCP enablement for your OneSignal app or account. Each operation also checks your OneSignal app permissions.Apps (2 tools)
Journeys (9 tools)
Manage Journeys with MCP
Structure tool requests, retrieve schemas, and apply Journey changes safely.
Messaging (3 tools)
To start or update a Live Activity, see Live Activities below.
Users and subscriptions (12 tools)
Templates (4 tools)
Segments (4 tools)
Live Activities (2 tools)
Exports (2 tools)
Custom events (2 tools)
Email deliverability (4 tools)
Email warmup (5 tools)
Analytics and utility (4 tools)
Safety and guardrails
- OneSignal marks
send_messageas a high-impact tool, so AI tools that honor tool annotations may ask for confirmation before running it. send_messagevalidates targeting before sending: only one targeting method per request, and filters are capped.- OneSignal validates inputs before execution, including identifiers, email addresses, and phone numbers.
- For Journey concurrency requirements, lifecycle controls, and recovery after uncertain writes, see the Journey request guide.
- OneSignal turns AI tool access on or off for each OneSignal login.
- The MCP server does not store your customer data (subscribers, messages, exports).
Limits and usage
Connecting OneSignal is free. Each action counts toward your normal OneSignal API usage limits. Your AI provider’s plan may have its own costs.- Tool calls are rate limited to prevent runaway tool loops.
- A connection follows the signed-in user’s permissions and can access every OneSignal app that user can manage.
- OneSignal may need to turn on AI tool access for your login before tools other than the utility tools work.
FAQ
Do I need a REST API key?
No. Every connection uses OneSignal OAuth. You sign in through your browser and approve access, so there is no API key to copy, store, or rotate.How do I work with more than one OneSignal app?
One connection covers every app your OneSignal account can manage. Calllist_apps to find app IDs. You don’t need a separate configuration per app.
Can I connect an AI tool that only supports local stdio servers?
No. The OneSignal MCP server is a remote server over HTTP. Your AI tool must support remote MCP servers with OAuth.How do I revoke access for an AI tool?
Go to Settings > Account settings > Connected apps in OneSignal and revoke the connection. Revoking it doesn’t affect your teammates’ connections.Related pages
Use OneSignal in Claude and ChatGPT
Install OneSignal from the Claude or ChatGPT directory.
Manage Journeys with MCP
Create drafts, update Journey steps, and manage Journey state from your MCP client.
REST API overview
Reference for the endpoints the OneSignal MCP server calls.
Create message API
Endpoint reference behind
send_message.AI data practices
How OneSignal handles data for AI features and connected AI tools.