Novu MCP Server

The Novu MCP Server exposes Novu’s notification infrastructure as tools that AI assistants can discover and use in real time. Connect your AI tool to manage subscribers, workflows, integrations, and delivery activity from natural-language prompts.

Novu also hosts a separate documentation MCP server at docs.novu.co/mcp that lets AI tools search and read this documentation site. The Novu MCP Server described on this page manages your Novu account — triggers, workflows, subscribers, and more.

About the Novu MCP server

The Model Context Protocol (MCP) is an open standard for connecting AI applications to external services. Once connected, you can prompt your AI assistant to:

Trigger workflows for specific subscribers
Search and inspect subscriber data
Update subscriber notification preferences
Debug failed notifications and delivery issues
Analyze notification activity and logs
Create and manage workflows

Some AI tools support both MCP and Agent Skills. MCP gives your assistant live access to your Novu account, while skills instruct agents how to use Novu APIs and SDKs effectively. They’re complementary — connect the MCP server for account operations and install skills for implementation guidance.

Prerequisites

A Novu Cloud account (to sign in with OAuth), or a Novu API key
An MCP-compatible AI tool — Cursor, Claude Code, ChatGPT, Claude Desktop, VS Code, Codex, or similar

Endpoints

Novu Cloud has one MCP endpoint per region:

Region	MCP URL
US	`https://mcp.novu.co/`
EU	`https://eu.mcp.novu.co/`

Use the URL that matches your dashboard region — eu.dashboard.novu.co pairs with the EU endpoint, everything else uses US.

Connect your AI tool

Connecting with OAuth is recommended — you don’t copy or paste a key; your client signs you in and picks up your organization automatically. If your client doesn’t support OAuth, or you’re on self-hosted Novu, use an API key instead.

Open Cursor Settings → Tools & Integrations → New MCP Server, and add:

{
  "mcpServers": {
    "novu": {
      "url": "https://mcp.novu.co/"
    }
  }
}

Save the file. Cursor will prompt you to sign in to Novu the first time it calls a tool.

Add to .vscode/mcp.json (or your user MCP settings):

{
  "servers": {
    "novu": {
      "type": "http",
      "url": "https://mcp.novu.co/"
    }
  }
}

Reload VS Code and approve the sign-in prompt when it appears.

claude mcp add --transport http novu https://mcp.novu.co/

Then run /mcp inside Claude Code to sign in.

Claude Desktop doesn’t yet support remote OAuth, so connect with an API key through the mcp-remote proxy (requires Node.js 18+):

{
  "mcpServers": {
    "novu": {
      "command": "npx",
      "args": [
        "mcp-remote",
        "https://mcp.novu.co/",
        "--header",
        "Authorization:Bearer your-novu-api-key"
      ]
    }
  }
}

Codex connects with an API key today:

export NOVU_API_KEY="your-novu-api-key"

[mcp_servers.novu]
url = "https://mcp.novu.co/"
bearer_token_env_var = "NOVU_API_KEY"

Any MCP client that supports remote OAuth can connect with just the URL and no header:

Setting	Value
URL	`https://mcp.novu.co/` (US) or `https://eu.mcp.novu.co/` (EU)
Transport	Streamable HTTP
Authentication	OAuth (no header), or an API key if your client doesn’t support OAuth

API key (fallback)

Use a Novu API key for clients without OAuth support, mcp-remote / stdio setups, autonomous agents, and all self-hosted Novu deployments. Copy your secret key from the Novu Dashboard and send it as a bearer token:

{
  "mcpServers": {
    "novu": {
      "url": "https://mcp.novu.co/",
      "headers": {
        "Authorization": "Bearer your-novu-api-key"
      }
    }
  }
}

Presenting an API key skips the OAuth sign-in entirely. A key is bound to a single environment, so connect to the endpoint matching its region and there’s nothing else to configure.

Environments

OAuth sessions are scoped to your organization and default to the Development environment. To act on a different environment (for example, Production), call get_environments and pass the environment’s _id as the optional environmentId parameter on any tool call. API keys are already bound to one environment, so environmentId has no effect on API key sessions.

Switch an OAuth session to a specific environment

Open in Cursor

Example prompts

After connecting the Novu MCP server, copy or open these prompts in Cursor to verify the connection and perform common tasks.

Replace placeholder values (for example, subscriber IDs and workflow identifiers) with values from your Novu dashboard.

Verify connection

Test your Novu MCP connection

Open in Cursor

List your notification workflows

Open in Cursor

Subscriber management

Find a subscriber by email

Open in Cursor

Create a new subscriber

Open in Cursor

Trigger and debug

Trigger a workflow for a subscriber

Open in Cursor

Debug failed notifications

Open in Cursor

MCP tools

Your AI assistant discovers these tools automatically when it connects, and calls the right one based on your prompt.

Category	Tool	Description
Auth	`whoami`	Verify the current credential and show your identity and region
Environments	`get_environments`	List environments — use an `_id` as the `environmentId` parameter on other tools
Subscribers	`create_subscriber`	Create a subscriber with name, email, phone, and custom data
Subscribers	`get_subscriber`	Retrieve a subscriber by `subscriberId`
Subscribers	`update_subscriber`	Update a subscriber’s attributes
Subscribers	`delete_subscriber`	Delete a subscriber
Subscribers	`find_subscribers`	Search subscribers by email, name, phone, or ID
Preferences	`get_subscriber_preferences`	Get a subscriber’s channel preferences
Preferences	`update_subscriber_preferences`	Update a subscriber’s channel preferences
Workflows	`create_workflow`	Create a workflow, including its steps
Workflows	`get_workflow`	Get a workflow’s full definition
Workflows	`get_workflows`	List all workflows
Workflows	`update_workflow`	Update an existing workflow
Workflows	`delete_workflow`	Delete a workflow
Workflows	`trigger_workflow`	Trigger a workflow for a subscriber
Workflows	`bulk_trigger_workflow`	Trigger multiple workflows in one call
Workflows	`cancel_triggered_event`	Cancel a pending triggered event
Notifications	`get_notification`	Get a notification with execution logs
Notifications	`get_notifications`	Fetch notifications with filtering
Integrations	`get_integrations`	List channel integrations
Integrations	`get_active_integrations`	List active integrations
Integrations	`delete_integration`	Delete an integration
Integrations	`set_primary_integration`	Set an integration as primary for its channel

Every tool accepts an optional environmentId parameter — see Environments.

Use multiple MCP servers

You can connect both the Novu MCP server and the Novu documentation MCP server at the same time. Each serves a different purpose:

Server	URL	Purpose
Novu MCP	`https://mcp.novu.co/` (US) / `https://eu.mcp.novu.co/` (EU)	Manage your Novu account — workflows, subscribers, triggers
Novu Docs MCP	`https://docs.novu.co/mcp`	Search and read Novu documentation

Connected MCP servers don’t consume context until the AI calls a tool. Be specific in your prompts so the assistant uses the most relevant server — for example, “trigger my welcome workflow” uses the Novu MCP, while “how do I configure digest steps?” uses the Docs MCP.

Troubleshooting

OAuth sign-in loop or never connects

Wrong environment data

OAuth sessions default to Development. Call get_environments and pass the _id you want as environmentId.

401 after previously working

Your OAuth token expired or was revoked — reconnect through your client to sign in again.

Empty results or authentication errors

Double-check you’re on the endpoint for your region (eu.dashboard.novu.co → https://eu.mcp.novu.co/), and that any API key is sent as Authorization: Bearer your-api-key with no extra spaces.

Self-hosted Novu

OAuth isn’t available on self-hosted deployments — connect with an API key from your instance. See API keys.

Still not connecting

Restart your AI assistant after config changes. For Claude Code, run claude mcp list. For Codex, run /mcp in the TUI. For Claude Desktop, confirm Node.js is installed.

Security

Prefer OAuth over long-lived API keys for interactive clients — OAuth tokens are short-lived and revocable.
The server never puts credentials in URLs, and holds no ambient credentials between sessions.
Rotate an API key from the Dashboard immediately if you suspect it’s been exposed.
Self-hosted Novu always uses API keys; OAuth is available for Novu Cloud only.
Use caution when combining the Novu MCP server with other MCP servers or untrusted data in the same session, and review tool calls before approving actions that modify your data.

Agent Skills

Give AI coding assistants implementation guidance for Novu SDKs and workflows.

Agent Toolkit

Embed Novu tools inside your own AI agents with the @novu/agent-toolkit package.

Novu Docs MCP

Connect AI tools to search and read this documentation site.

API keys

Learn how to create and manage the secret keys used for API key authentication.

​About the Novu MCP server

​Prerequisites

​Endpoints

​Connect your AI tool

​API key (fallback)

​Environments

​Example prompts

​Verify connection

​Subscriber management

​Trigger and debug

​MCP tools

​Use multiple MCP servers

​Troubleshooting

​Security

​Related topics

Agent Skills

Agent Toolkit

Novu Docs MCP

API keys

About the Novu MCP server

Prerequisites

Endpoints

Connect your AI tool

API key (fallback)

Environments

Example prompts

Verify connection

Subscriber management

Trigger and debug

MCP tools

Use multiple MCP servers

Troubleshooting

Security

Related topics