Novu MCP Server

The Novu MCP Server exposes Novu’s notification and agent infrastructure as tools that AI assistants can discover and use in real time. Connect your AI tool to manage subscribers, workflows, integrations, agents, conversations, 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, agents, 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
Create and update agents, then connect a channel
List agent conversations and inspect activity timelines

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
OAuth access, or a Novu Cloud 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, use a Novu Cloud 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 a Novu Cloud API key if your client doesn’t support OAuth

API key (fallback)

Use a Novu Cloud API key for clients without OAuth support, mcp-remote / stdio setups, and autonomous agents. 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.

The hosted Novu MCP endpoints connect to Novu Cloud only. They do not proxy requests to a self-hosted Novu API, even when you provide an API key from that instance. Novu does not currently publish a self-hosted account MCP server. Self-hosted users can still connect the separate read-only Novu documentation MCP server.

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

Agents and conversations

Create a managed agent and connect a channel

Open in Cursor

Debug an agent conversation

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
Agents	`create_agent`	Create an agent
Agents	`get_agents`	List agents with cursor pagination
Agents	`get_agent`	Retrieve a single agent by identifier (slug)
Agents	`update_agent`	Update an agent’s name, status, bridge URL, or behavior
Agents	`connect_agent`	Connect a channel to an existing agent
Conversations	`get_conversations`	List agent conversations with optional filters
Conversations	`get_conversation_activities`	Inspect a conversation timeline
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. Agent tools use the agent’s identifier (slug), not the Mongo _id. Conversation tools on this MCP server require Novu Cloud. Self-hosted Enterprise can still use Conversations in the dashboard and API, but not through mcp.novu.co.

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, agents, conversations, 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

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.

Conversations return 404

get_conversations and get_conversation_activities on this MCP server require Novu Cloud with Conversations enabled. They are not available through MCP on self-hosted deployments. Confirm you passed an agent identifier (slug) as agentId, not a Mongo _id.

Self-hosted Novu

The account-management MCP server is not currently available for self-hosted Novu. https://mcp.novu.co/ and https://eu.mcp.novu.co/ connect to Novu Cloud and do not accept a self-hosted API URL. Use the Agent Toolkit with backendUrl set to your API, or call the REST API directly. You can still use the Novu documentation MCP server to search these docs.

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.
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.

Managed agents

How managed agents, connectors, and channel connect work in Novu.

Agent conversations

How conversation lifecycle and activity look in the dashboard.

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.

Getting Started

Integrate <Inbox />

Integrate <Subscription />

Build a Workflow

Integrate Channels Providers

SDKs

Developer

Account

Build with AI

Additional Resources

Novu MCP Server

About the Novu MCP server

Prerequisites

Endpoints

Connect your AI tool

API key (fallback)

Environments

Example prompts

Verify connection

Subscriber management

Trigger and debug

Agents and conversations

MCP tools

Use multiple MCP servers

Troubleshooting

Security

Agent Skills

Agent Toolkit

Managed agents

Agent conversations

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

​Agents and conversations

​MCP tools

​Use multiple MCP servers

​Troubleshooting

​Security

​Related topics

Agent Skills

Agent Toolkit

Managed agents

Agent conversations

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

Agents and conversations

MCP tools

Use multiple MCP servers

Troubleshooting

Security

Related topics