# Novu

> Route Novu tasks to the right skill or MCP server. Use whenever the user mentions Novu, notifications, workflows, subscribers, inbox, @novu/api, @novu/framework, @novu/nextjs, @novu/react, triggering notifications, notification preferences, managed agents, or debugging delivery failures. Load this skill first for any Novu-related task in Cursor.

- Skill: `novuhq/novu` (Agent Skill)
- Install (CLI): `npx skillmds@latest add novuhq/novu`
- Raw SKILL.md: https://api.skillmd.com/api/skills/novuhq/novu/raw
- Safety review: pending
- Works with: Claude Code, Claude.ai, OpenAI Codex
- Category: Web & Frontend
- Author: novuhq (https://skillmd.com/u/novuhq)
- Updated: 2026-09-17
- Page: https://skillmd.com/skills/novuhq/novu

---


# Novu

The Novu Cursor plugin bundles **two MCP servers** and **eight implementation skills**. Pick the right tool for each task — MCP for live account operations, skills for code in the user's repo, Docs MCP for how-to questions.

## MCP vs Skills vs Docs

| Task type | Tool | Examples |
| --- | --- | --- |
| Live account operations | **Novu Account MCP** (`novu`) | List workflows, trigger a workflow, find subscribers, debug failed notifications, manage integrations |
| Documentation / how-to | **Novu Docs MCP** (`novu-docs`) | "How do digest steps work?", "What is payloadSchema?", provider setup guides |
| Code in the user's repo | **Novu skill** (see routing table) | Add inbox to Next.js, write trigger code with `@novu/api`, define workflows with `@novu/framework` |

**Before account operations:** call `whoami` on the Novu Account MCP to verify OAuth and region.

**Production data:** OAuth sessions default to Development. Call `get_environments` and pass the Production `_id` as `environmentId` on tool calls when the user asks about Production.

**EU region:** If the user is on `eu.dashboard.novu.co`, they must use `https://eu.mcp.novu.co/` instead of the US endpoint. Document this in README; the plugin ships US by default.

## Skill Routing

Read the matching skill's `SKILL.md` when the task is about implementing Novu in code:

| User intent | Skill |
| --- | --- |
| Send/trigger notifications (single, bulk, broadcast, topic) | `novu-trigger-notification` |
| Create, update, delete subscribers or topics | `novu-manage-subscribers` |
| Add bell icon, Inbox, notification feed to a web app | `novu-inbox-integration` |
| Subscriber opt-out, workflow preferences, Preferences UI | `novu-manage-preferences` |
| Design a new workflow (channels, severity, digest, templates) | `novu-design-workflow` |
| Author step content in Dashboard (subject, body, conditions) | `novu-dashboard-workflows` (+ MCP `get_workflow` for live definition) |
| Code-first workflows with `@novu/framework` | `novu-framework-integration` |
| Create a Novu managed agent and connect Slack/email/Telegram | `novu-connect-agent` |

## Common Combinations

- **Full notification system:** `novu-trigger-notification` + `novu-manage-subscribers`
- **In-app notifications:** `novu-trigger-notification` + `novu-inbox-integration`
- **Dashboard authoring:** `novu-design-workflow` + `novu-dashboard-workflows`
- **Code-first workflows:** `novu-framework-integration` + `novu-trigger-notification`
- **Complete stack:** all eight skills

## SDK Quick Reference

| Package | Side | Purpose |
| --- | --- | --- |
| `@novu/api` | Server | Trigger notifications, manage subscribers/topics/workflows via REST |
| `@novu/framework` | Server | Define workflows in code; Bridge Endpoint for Novu Cloud execution |
| `@novu/react` | Client | React Inbox, Notifications, Preferences, Bell |
| `@novu/nextjs` | Client | Next.js-optimized Inbox integration |
| `@novu/js` | Client | Vanilla JavaScript client for non-React apps |

## Top Traps

1. **`@novu/api` is server-only.** Never put `NOVU_SECRET_KEY` in client code or `NEXT_PUBLIC_*` env vars.
2. **Inbox uses `NOVU_APPLICATION_IDENTIFIER`** (or `NEXT_PUBLIC_NOVU_APP_ID`), not the secret key.
3. **HMAC `subscriberHash` is required in production** for inbox — generate server-side with `createHmac("sha256", NOVU_SECRET_KEY).update(subscriberId).digest("hex")`.
4. **`workflowId` is the identifier**, not the display name shown in the Dashboard.
5. **MCP OAuth defaults to Development.** Pass `environmentId` for Production operations.
6. **Implement in the existing codebase** — do not create standalone documentation files unless the user asks.
7. **Do not mix MCP and skills for the same action.** Use MCP to operate the account; use skills to write integration code.

## Environment Variables

| Variable | Used by | Purpose |
| --- | --- | --- |
| `NOVU_SECRET_KEY` | Server skills (`trigger`, `subscribers`, `preferences`, `framework`, `dashboard-workflows`) | API key from [dashboard.novu.co/api-keys](https://dashboard.novu.co/api-keys) |
| `NOVU_APPLICATION_IDENTIFIER` / `NEXT_PUBLIC_NOVU_APP_ID` | `novu-inbox-integration` | Client-side application identifier from Dashboard integration settings |

`novu-design-workflow` requires no env vars. `novu-connect-agent` uses keyless mode by default or dashboard OAuth.

## Account MCP Tools (quick reference)

| Category | Tools |
| --- | --- |
| Auth | `whoami` |
| Environments | `get_environments` |
| Subscribers | `create_subscriber`, `get_subscriber`, `update_subscriber`, `delete_subscriber`, `find_subscribers` |
| Preferences | `get_subscriber_preferences`, `update_subscriber_preferences` |
| Workflows | `create_workflow`, `get_workflow`, `get_workflows`, `update_workflow`, `delete_workflow`, `trigger_workflow`, `bulk_trigger_workflow`, `cancel_triggered_event` |
| Notifications | `get_notification`, `get_notifications` |
| Integrations | `get_integrations`, `get_active_integrations`, `delete_integration`, `set_primary_integration` |

Every tool accepts an optional `environmentId` parameter.

## Voice

Get to the right tool quickly. Do not restate the user's goal. When both MCP and a skill could apply, prefer MCP for read/debug/trigger on the live account and skills for writing code in the repo.