# MCP Server

Let AI agents (Claude, Cursor, any MCP client) run your entire Native Notify account — send and schedule push notifications, manage apps and subscribers, and read analytics with one access token.

Native Notify ships a hosted **[MCP](https://modelcontextprotocol.io) server** so AI agents can do everything for you: send and schedule push notifications, manage apps and subscribers, inspect inboxes, and read analytics — through one access token instead of dashboard clicks.

**MCP server URL:** `https://app.nativenotify.com/mcp`

## Get an access token

1. Log in to the [dashboard](https://dashboard.nativenotify.com) and click **MCP** in the header (or open [dashboard.nativenotify.com/mcp](https://dashboard.nativenotify.com/mcp)).
2. Choose an expiration (30 days, 90 days, 1 year, or never — we recommend a finite expiry; the dashboard warns you before creating a token that never expires) and click **Create access token**.
3. A window opens showing the new token — **copy it now: that window is the only time it will ever be shown.** Only a hash is stored, so it can never be displayed again. Save it in a safe location (a password manager is ideal).
4. While the window is open, give the token a **name** — e.g. *"Claude Desktop"*, *"Cursor"*, *"Production agent"* — and press **Save**. If you skip it, the token is named **"Native Notify Access Token"**.

The token list shows each token's **name** and its short prefix (e.g. `nnmcp_1741b5…` — the prefix is a non-secret identification hint) so you can tell rows apart even after the full value is gone. You can create **as many tokens as you like** — for example, one per agent or per machine — and **revoke** any of them from the same page; a revoked token stops working within about a minute. Treat every token like a password: anyone holding it can act on your account until you revoke it. Forgot a token's value? It can't be recovered — just create a new one and revoke the old.

## Connect an MCP client

### Claude Code

```bash
claude mcp add --transport http native-notify https://app.nativenotify.com/mcp \
  --header "Authorization: Bearer nnmcp_YOUR_TOKEN"
```

### Claude Desktop, Cursor, Windsurf, other clients (HTTP)

```json
{
  "mcpServers": {
    "native-notify": {
      "type": "http",
      "url": "https://app.nativenotify.com/mcp",
      "headers": {
        "Authorization": "Bearer nnmcp_YOUR_TOKEN"
      }
    }
  }
}
```

### Clients that only accept a URL

Append the token as a query parameter:

```
https://app.nativenotify.com/mcp?token=nnmcp_YOUR_TOKEN
```

Treat that URL as a secret — it contains the token.

### Local (stdio) mode

Prefer a local process? Install the same server as a package:

```bash
npx -y native-notify-mcp
```

```json
{
  "mcpServers": {
    "native-notify": {
      "command": "npx",
      "args": ["-y", "native-notify-mcp"],
      "env": { "NATIVE_NOTIFY_MCP_TOKEN": "nnmcp_YOUR_TOKEN" }
    }
  }
}
```

## What your agent can do

| Area                     | Tools                                                                                                                                                                                                        |
| ------------------------ | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------ |
| Account & apps           | `get_account`, `list_apps`, `get_app`, `create_app`, `rename_app`, `set_website_to_app_url`, `update_app_settings`, `delete_app`                                                                             |
| Sending (live)           | `send_push_notification` (mass), `send_notification_to_subscriber`, `send_notification_to_subscribers`, `send_notification_to_topic_group`, `send_notification_to_followers`                                 |
| Scheduling               | `schedule_notification` (a local date + time converted to the server's timezone fields), `list_scheduled_notifications` — scheduled and sent one-offs with their sent/read state                             |
| AI Push                  | `list_ai_pushes`, `schedule_ai_push`, `update_ai_push`, `delete_ai_push`                                                                                                                                     |
| Inbox                    | `list_inbox_notifications`, `list_subscriber_inbox`, `delete_inbox_notification`, `delete_subscriber_inbox_notification`                                                                                     |
| Subscribers              | `list_subscribers`, `get_subscriber`, `delete_subscriber`                                                                                                                                                    |
| Topic groups & followers | `list_topic_groups`, `get_topic_group`, `get_follow_master`                                                                                                                                                  |
| Analytics                | `get_analytics_summary`, `get_active_users`, `get_views`, `get_screen_usage`, `get_retention`, `get_best_send_times`, `get_notification_delivery_stats`, `get_notification_failures`, `export_analytics_csv` |
| Docs                     | `search_docs`, `read_doc` — always-current pages served live from this site                                                                                                                                  |

Once connected, you can simply ask:

- *"Send a push to my app reminding users about tomorrow's event."*
- *"How many people opened last week's notification? Which screens do users open most?"*
- *"Schedule a reminder for every Friday at 9am."*

## Good to know

- **App-scoped tools take an app id or name** — `list_apps` and `get_account` return both.
- **Verify the connection** — ask your agent to run `get_account` or `list_apps`; if it answers with your real account data, you're set up correctly.
- **Sends are live and cannot be recalled.** Agents are instructed to confirm title, body, and audience with you first.
- **4 KiB limit** — the whole Expo message must stay under 4 KiB.
- **Expired or revoked tokens** — clients receive a clear 401 error pointing back to the dashboard's MCP page; create a new token there and update the client. Revoking takes effect within about a minute.
- **Tokens are shown once** — the dashboard can never re-display a token value (only a hash is stored). Save each token when you create it; to rotate a compromised token, create a new one and revoke the old.
- **The docs are served live** through `search_docs` / `read_doc`, so your agent always reads the current API — not a stale memory of it.
- **Scoping** — the token acts like a logged-in dashboard session for your account only. It cannot read or change MCP tokens (only the dashboard can).