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 https://mcp.novu.co/ 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 server on this page (mcp.novu.co) 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. The Novu MCP Server prepares your notification infrastructure for the broader AI ecosystem — any MCP-compatible client like Cursor, Claude Code, Codex, or VS Code can connect and act on your Novu environment. 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 are complementary — connect the MCP server for account operations and install skills for implementation guidance.

How the Novu MCP works

The Novu MCP Server exposes your notification system as a set of tools. When your AI assistant connects:

It authenticates using your API key.
It discovers available tools.
It executes actions based on your prompts.

Instead of calling APIs directly, the AI translates your request into tool calls and executes them against your Novu environment.

Prerequisites

To use the Novu MCP Server, you need:

A Novu API key
An MCP-compatible AI tool (Cursor, Codex, Claude Code, Claude Desktop, VS Code)

Some tools like Claude Desktop require Node.js to run MCP servers locally through the mcp-remote proxy.

Access the Novu MCP server

The Novu MCP Server is hosted at https://mcp.novu.co/ and uses Streamable HTTP transport. Authenticate every request by sending your secret key in the Authorization header as Bearer your-novu-api-key.

Setting	Value
Transport	Streamable HTTP
Authentication	Bearer token (Novu secret key)
US endpoint	`https://mcp.novu.co/`
EU endpoint	`https://mcp.novu.co/?region=eu`

Your region is determined by your dashboard URL:

Dashboard URL	Region	MCP URL
`dashboard.novu.co`	US	`https://mcp.novu.co/`
`eu.dashboard.novu.co`	EU	`https://mcp.novu.co/?region=eu`

Use the MCP URL that matches your dashboard region in every configuration example below.

Setup

Get your secret key

Your secret key authenticates your AI tool with Novu.

Go to the Novu Dashboard.
Navigate to API Keys.
Under Secret Keys, copy your secret key.

Identify your region

Check your dashboard URL to choose the correct MCP endpoint. US accounts use https://mcp.novu.co/; EU accounts use https://mcp.novu.co/?region=eu.

Configure your AI tool

Follow the client-specific instructions in the next section. Replace your-novu-api-key with the secret key you copied, and use the MCP URL for your region.

Test the connection

Ask your assistant to run a simple prompt such as “Check my Novu API key status” or “Show me all my notification workflows.” If you get results back, the server is connected.

Connect your AI tool

Cursor supports remote MCP servers through its built-in settings UI, which writes to an mcp.json file.

Open MCP settings

Open Cursor Settings, select Tools & Integrations, then under MCP Tools select New MCP Server. This opens your mcp.json file.

Add the Novu MCP server

Add the following to the mcpServers object:

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

Save and verify

Save the file. Cursor detects the new server automatically. In Cursor’s chat, ask “What MCP tools do you have available?” — you should see the Novu server listed.

VS Code reads MCP configuration from .vscode/mcp.json in your workspace, or from user-level MCP settings.

Create mcp.json

Create a .vscode/mcp.json file in your project (or open your user MCP settings).

Add the Novu MCP server

Add the following configuration:

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

Reload and verify

Reload VS Code and open the MCP panel. The novu server should appear as a connected server.

Codex reads MCP configuration from ~/.codex/config.toml. The CLI and IDE extension share this file.

Export your API key

Export your API key as an environment variable:

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

Add the Novu MCP server

Open ~/.codex/config.toml and add:

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

Restart and verify

Save the file and restart Codex. Run /mcp inside the Codex TUI — you should see novu listed as a connected server.

Claude Code manages MCP servers through its claude mcp command.

Add the Novu MCP server

In your terminal, run:

claude mcp add --transport http novu https://mcp.novu.co/ \
  --header "Authorization: Bearer your-novu-api-key"

Optional: make it global

To make Novu available across all projects, add the --scope user flag:

claude mcp add --scope user --transport http novu https://mcp.novu.co/ \
  --header "Authorization: Bearer your-novu-api-key"

Verify the connection

Run claude mcp list, or run /mcp inside Claude Code to check server status.

Claude Desktop connects to remote MCP servers through a local proxy (mcp-remote), which requires Node.js 18 or higher.

Open Claude Desktop config

Open Claude Desktop, go to Settings, find the Developer section, and select Edit Config. This opens your claude_desktop_config.json file.

Add the Novu MCP server

Add the following to the mcpServers object (or create the object if it does not exist):

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

Restart Claude Desktop

Save the file and restart Claude Desktop.

Any MCP-compatible tool can connect to the Novu MCP Server using these connection details:

Setting	Value
URL	`https://mcp.novu.co/` (US) or `https://mcp.novu.co/?region=eu` (EU)
Transport	Streamable HTTP
Authentication	`Authorization: Bearer your-novu-api-key`

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

The Novu MCP server provides tools for interacting with your Novu environment. Your AI assistant discovers tools at connection time through the MCP tools/list handshake. Agents determine when to call each tool based on your prompt. For example, a request to “find subscriber user@example.com” may call find_subscribers, while “send a welcome email” may call trigger_workflow.

Core operations

These tools let you inspect your account configuration:

Tool	Description
`get_api_key_status`	Check API key status and region configuration
`get_environments`	List development and production environments

Subscriber management

These tools let you create, inspect, and manage your subscribers:

Tool	Description
`create_subscriber`	Create a new subscriber with attributes like name, email, phone, and custom data
`get_subscriber`	Retrieve a single subscriber by their `subscriberId`
`update_subscriber`	Update an existing subscriber’s attributes
`delete_subscriber`	Delete a subscriber by their `subscriberId`
`find_subscribers`	Search for subscribers using various query parameters

Preferences

These tools let you view and update how subscribers receive notifications:

Tool	Description
`get_subscriber_preferences`	Get subscriber notification preferences for all channels
`update_subscriber_preferences`	Update subscriber notification preferences for specific channels

Workflow management

These tools let you create, inspect, and manage notification workflows:

Tool	Description
`create_workflow`	Create a new workflow with comprehensive configuration including steps
`get_workflow`	Get detailed information about a specific workflow
`get_workflows`	Get all available workflows
`update_workflow`	Update an existing workflow
`delete_workflow`	Delete an existing workflow by its unique identifier

Triggering and events

These tools let you execute workflows and manage pending notifications:

Tool	Description
`trigger_workflow`	Trigger a workflow to send notifications to a subscriber
`bulk_trigger_workflow`	Trigger multiple workflows in a single API call
`cancel_triggered_event`	Cancel a pending triggered event

Notifications

These tools let you inspect delivery and execution data:

Tool	Description
`get_notification`	Get a specific notification by ID with detailed execution logs
`get_notifications`	Get notifications and events with advanced filtering options

Integrations

These tools let you manage the channel providers connected to your Novu account:

Tool	Description
`get_integrations`	List all channel integrations (email, SMS, push, chat, in-app)
`get_active_integrations`	List only the active integrations
`delete_integration`	Delete an integration by its `integrationId`
`set_primary_integration`	Mark an integration as the primary for its channel

Use multiple MCP servers

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

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

Connected MCP servers do not 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

If your setup is not working, the following sections cover the most common issues.

Authentication errors

Verify your API key is valid and has no extra spaces or line breaks.
Check that you are using the correct header format: Authorization: Bearer your-api-key.

Empty results

Confirm you are using the correct region. If your dashboard is at eu.dashboard.novu.co, you need the EU endpoint (https://mcp.novu.co/?region=eu).

Connection issues

Restart your AI assistant after making configuration changes.
For Claude Desktop, ensure Node.js is installed and accessible from your terminal.
For Claude Code, run claude mcp list to confirm the server is registered.
For Codex, run /mcp in the TUI to check server status.

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 to authenticate the MCP server.

​About the Novu MCP server

​How the Novu MCP works

​Prerequisites

​Access the Novu MCP server

​Setup

​Connect your AI tool

​Example prompts

​Verify connection

​Subscriber management

​Trigger and debug

​MCP tools

​Core operations

​Subscriber management

​Preferences

​Workflow management

​Triggering and events

​Notifications

​Integrations

​Use multiple MCP servers

​Troubleshooting

​Related topics

Agent Skills

Agent Toolkit

Novu Docs MCP

API keys

About the Novu MCP server

How the Novu MCP works

Prerequisites

Access the Novu MCP server

Setup

Connect your AI tool

Example prompts

Verify connection

Subscriber management

Trigger and debug

MCP tools

Core operations

Subscriber management

Preferences

Workflow management

Triggering and events

Notifications

Integrations

Use multiple MCP servers

Troubleshooting

Related topics