Source: https://www.pushengage.com/api/ai-agents

# Build with AI Agents

PushEngage ships two official tools for AI agents, one for **operating your account** and one for **integrating our SDK into your app**:

-   **[MCP Server](#mcp-server)**: a [Model Context Protocol](https://modelcontextprotocol.io/) server that connects assistants such as Claude Desktop, Claude Code, and Cursor to your PushEngage account. Send and schedule notifications, run A/B tests, build audiences, inspect analytics, and manage site settings just by asking.
-   **[Agent Skills](#agent-skills)**: a skill pack that teaches AI coding agents to integrate and debug the PushEngage Mobile SDK across **iOS, Android, Flutter, and React Native** apps.

They work great together: install the Agent Skills plugin in Claude Code and the MCP server is configured for you automatically.

## MCP Server

The [`@pushengage/mcp`](https://github.com/awesomemotive/pushengage-mcp) server lets you manage your PushEngage account from any MCP-capable assistant, in plain language. Once connected, just describe what you want:

-   _"Send a notification titled 'Sale ends tonight', message 'Last call, 50% off', linking to [https://example.com/sale."](https://example.com/sale.%22)_
-   _"Schedule that for 9 AM in each subscriber's local timezone."_
-   _"Run an A/B test of two headlines and auto-roll-out the winner by click rate."_
-   _"Create a segment for visitors of /pricing."_
-   _"How many subscribers do I have, and what was my click rate over the last 30 days?"_
-   _"Set my default notification expiry to 7 days."_

### Requirements

-   A [PushEngage](https://www.pushengage.com/) account (free or paid) with at least one site.
-   Node.js 18 or newer (the assistant runs the server via `npx`).
-   An MCP-capable client such as Claude Desktop, Claude Code, Cursor, or any other client that speaks MCP over stdio.

### Install

The easiest path is the one-click MCP Bundle:

1.  Download the latest `pushengage-mcp-<version>.mcpb` file from the [GitHub releases page](https://github.com/awesomemotive/pushengage-mcp/releases/latest).
2.  Open it with Claude Desktop (double-click it, or drag it onto the window) and click **Install**.

Prefer manual config? Edit `~/Library/Application Support/Claude/claude_desktop_config.json` (macOS) or the equivalent on your platform, then restart Claude Desktop:

```json
{
  "mcpServers": {
    "pushengage": {
      "command": "npx",
      "args": ["-y", "@pushengage/mcp"]
    }
  }
}
```

Run this in your terminal:

```bash
claude mcp add pushengage -- npx -y @pushengage/mcp
```

Or install the [PushEngage Agent Skills plugin](#agent-skills), which configures the MCP server for you automatically.

One-click install:

[Add to Cursor](https://cursor.com/install-mcp?name=pushengage&config=eyJjb21tYW5kIjoibnB4IiwiYXJncyI6WyIteSIsIkBwdXNoZW5nYWdlL21jcCJdfQ%3D%3D)

Or edit `~/.cursor/mcp.json` (or open the command palette → **Cursor Settings** → **MCP** → **Add new global MCP server**):

```json
{
  "mcpServers": {
    "pushengage": {
      "command": "npx",
      "args": ["-y", "@pushengage/mcp"]
    }
  }
}
```

Run this in your terminal:

```bash
codex mcp add pushengage -- npx -y @pushengage/mcp
```

Or add it to `~/.codex/config.toml`:

```toml
[mcp_servers.pushengage]
command = "npx"
args = ["-y", "@pushengage/mcp"]
```

One-click install:

[Install in VS Code](https://vscode.dev/redirect/mcp/install?name=pushengage&config=%7B%22command%22%3A%22npx%22%2C%22args%22%3A%5B%22-y%22%2C%22%40pushengage%2Fmcp%22%5D%7D)

Or run **MCP: Add Server** from the command palette, or add this to `.vscode/mcp.json` in your workspace:

```json
{
  "servers": {
    "pushengage": {
      "type": "stdio",
      "command": "npx",
      "args": ["-y", "@pushengage/mcp"]
    }
  }
}
```

Add this to `~/.gemini/settings.json`:

```json
{
  "mcpServers": {
    "pushengage": {
      "command": "npx",
      "args": ["-y", "@pushengage/mcp"]
    }
  }
}
```

Add this to `~/.codeium/windsurf/mcp_config.json`:

```json
{
  "mcpServers": {
    "pushengage": {
      "command": "npx",
      "args": ["-y", "@pushengage/mcp"]
    }
  }
}
```

Navigate to **Settings** → **AI** → **MCP Servers**, click **\+ Add**, and paste:

```json
{
  "pushengage": {
    "command": "npx",
    "args": ["-y", "@pushengage/mcp"]
  }
}
```

Add this to `opencode.json`:

```json
{
  "$schema": "https://opencode.ai/config.json",
  "mcp": {
    "pushengage": {
      "type": "local",
      "command": ["npx", "-y", "@pushengage/mcp"],
      "enabled": true
    }
  }
}
```

Open **Settings** → **Connections** → **MCP Servers**, click **Add a custom MCP**, and paste:

```json
{
  "mcpServers": {
    "pushengage": {
      "command": "npx",
      "args": ["-y", "@pushengage/mcp"]
    }
  }
}
```

Any client that speaks MCP over stdio works. Configure it to run:

```bash
npx -y @pushengage/mcp
```

### First run: logging in

Authentication is browser-based, so your credentials never touch the assistant.

1.  Ask: **"Log me into PushEngage."** The server opens a browser tab to the PushEngage authorize page.
2.  Click **Authorize**. The tab confirms success and an access token is saved locally with `0600` permissions.
3.  Ask: **"Show my PushEngage sites,"** then **"Use site 12345"** to pick the site to work with. The selection is remembered across restarts.

### Available tools

The server exposes tools across the whole platform:

| Area | What you can do |
| --- | --- |
| Authentication & sites | Log in and out, list your sites, select the site to work with. |
| Sending notifications | List, send, and schedule notifications: one-shot, per-subscriber timezone, recurring, and A/B tests. |
| Audiences | Create and list segments, audience groups, and custom subscriber attributes. |
| Campaigns & automations | Inspect drip autoresponders, triggered campaigns, RSS auto push, and workflows, with analytics. |
| Analytics | Lifetime totals and per-day/week/month timeseries for subscribers, sends, views, clicks, and CTR. |
| Site settings | Site details, campaign defaults, and service worker settings. |

For the full tool reference, configuration options, and troubleshooting, see the [pushengage-mcp README](https://github.com/awesomemotive/pushengage-mcp#readme).

## Agent Skills

[PushEngage Agent Skills](https://github.com/awesomemotive/pushengage-skills) help an AI coding agent integrate and debug the PushEngage push-notification SDK in your app. The skills follow two open standards: the [Agent Skills (`SKILL.md`) standard](https://agentskills.io/specification) and the [Agent Plugins format](https://agent-plugins.org/), so they work with any agent that supports either one, including Claude Code, Cursor, Codex, Copilot, Windsurf, VS Code, and others.

The pack contains six skills:

| Skill | Purpose |
| --- | --- |
| `pushengage` | Entry skill that detects your platform and routes to the right one. |
| `pushengage-ios` | iOS integration and debugging. |
| `pushengage-android` | Android integration and debugging. |
| `pushengage-flutter` | Flutter integration and debugging. |
| `pushengage-react-native` | React Native integration and debugging. |
| `pushengage-debug` | Shared diagnostic skill for broken integrations. |

### Install

Install as a plugin:

```text
/plugin marketplace add awesomemotive/pushengage-skills
/plugin install pushengage
```

Installing the plugin also configures the official [MCP server](#mcp-server), so the agent can operate your PushEngage account too.

Works with Cursor, Codex, Copilot, Windsurf, and other SKILL.md-compatible agents via [skills.sh](https://skills.sh):

```bash
npx skills add awesomemotive/pushengage-skills
```

The repository conforms to the open [Agent Plugins format](https://agent-plugins.org/) (`plugin.json` manifest, `skills/` directory, and `mcp.json`), so any client on the [compatible clients list](https://agent-plugins.org/compatible-clients) can load it as a plugin. That currently includes VS Code, Cursor, GitHub Copilot, ChatGPT & Codex, Kiro, Hermes Agent, OpenClaw, Grok Bot, and NanoClaw.

The Agent Plugins specification leaves installation up to each client, so use your client's own plugin-install mechanism and point it at the `awesomemotive/pushengage-skills` repository. Clients that support the plugin's `mcp.json` also get the official [MCP server](#mcp-server) configured automatically.

The skills live under `skills/` in the [pushengage-skills repository](https://github.com/awesomemotive/pushengage-skills). Copy the skill folders into your agent's skills directory, or point your agent at the repository. Each skill activates automatically based on the project type it detects.

### Usage

After installing, just talk to your agent:

-   _"Help me integrate PushEngage into this app."_ runs the full integration flow.
-   _"PushEngage notifications aren't arriving on my iPhone."_ runs the diagnostic flow.
-   _"Audit my PushEngage setup."_ runs the static audit.

The plugin detects your platform automatically and hands off to the matching integration or debug skill. Prefer to follow the steps yourself? Head to the [Mobile SDK docs](/api/mobile-sdk).

## Docs for Your Agent

This documentation is built to be read by AI agents as well as humans:

-   Every page has a markdown version. Append `.md` to any page URL (for example, [/api/ai-agents.md](https://www.pushengage.com/api/ai-agents.md)), or use the **Copy as markdown** button at the top of each page.
-   [llms.txt](https://www.pushengage.com/api/llms.txt) is an index of every page with links to the markdown versions.
-   [llms-full.txt](https://www.pushengage.com/api/llms-full.txt) contains the entire documentation in a single file, ready to drop into an agent's context.

To onboard an agent, paste a prompt like this:

```text
Read https://www.pushengage.com/api/ai-agents.md and set up the PushEngage
MCP server and Agent Skills in this project.
```

## Resources

-   [pushengage-mcp on GitHub](https://github.com/awesomemotive/pushengage-mcp): source, full tool reference, and troubleshooting.
-   [`@pushengage/mcp` on npm](https://www.npmjs.com/package/@pushengage/mcp): the MCP server package.
-   [pushengage-skills on GitHub](https://github.com/awesomemotive/pushengage-skills): the Agent Skills marketplace and plugin.