MCP Server

The Novu MCP Server exposes Novu's notification infrastructure as tools that AI assistants can discover and use in real time.

Once connected, you can use natural language to manage notifications in Novu directly from your AI tool. For example, 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

How Novu MCP works

The Novu MCP Server exposes your notification system as a set of tools.

When your AI assistant connects:

1. It authenticates using your API key.
2. It discovers available tools.
3. 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.

Prerequisite

To use the Novu MCP Server, you'll need:

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

Setup

Follow these steps to setup the Novu MCP server:

1. Get your secret key

Your secret key authenticates your AI tool with Novu. To retrieve it:

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

2. Identify your region

Your region determines which URL your AI tool connects to. To identify it, check your dashboard URL:

The MCP URL above is what you'll use in the next step when configuring your tool.

3. Configure your tool

The following sections cover setup for the most common MCP-compatible AI tools. Before you start, keep two things in mind as you work through the examples:

• Replace the API key. Each example uses your-novu-api-key as a placeholder. Replace it with the API key you copied earlier.
• Use the correct URL for your region. The examples use the US endpoint (https://mcp.novu.co/). If you're on the EU region, replace it with https://mcp.novu.co/?region=eu.

Cursor

Cursor supports remote MCP servers through its built-in settings UI, which writes to an mcp.json file. To add the Novu MCP Server:

1. Open Cursor Settings, and select Tools & Integrations.

2. Under MCP Tools, select New MCP Server. This opens your mcp.json file.

3. Add the following to the mcpServers object:

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

4. Save the file. Cursor detects the new server automatically.

Codex

Codex reads MCP configuration from ~/.codex/config.toml. The CLI and IDE extension share this file, so you only need to configure the server once. To add the Novu MCP Server:

1. Export your API key as an environment variable in your shell:

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

2. Open ~/.codex/config.toml in your preferred text editor and add the following:

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

3. Save the file and restart Codex. To verify the connection, run /mcp inside the Codex TUI. You should see novu listed as a connected server.

Claude Code

Claude Code manages MCP servers through its claude mcp command. To add the Novu MCP Server:

1. In your terminal, run:

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

2. To make Novu available across all your projects instead of just the current one, add the --scope user flag:

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

3. Verify the connection by running claude mcp list. You can also run /mcp inside Claude Code to check server status.

Claude Desktop

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

1. Open Claude Desktop, go to Settings, and find the Developer section.

2. Select Edit Config. This opens your claude_desktop_config.json file.

3. Add the following to the mcpServers object (or create the object if it doesn't 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"
         }
       }
     }
   }

4. Save the file and restart Claude Desktop.

Other tools

Any MCP-compatible tool can connect to the Novu MCP Server. Use the following connection details:

• URL:
  • US: https://mcp.novu.co/
  • EU: https://mcp.novu.co/?region=eu
• Transport: Streamable HTTP (recommended).
• Authentication: Send your API key in the Authorization header as Bearer your-novu-api-key.

Test your setup

To verify that the connection works, try any of the prompts below in your AI assistant:

"Check my Novu API key status"
"Show me all my notification workflows"
"Find subscriber with email [email protected]"

If you get results back, the Novu MCP Server is connected and working.

Available tools

The Novu MCP server currently provides 23 tools for interacting with your Novu environment:

Core operations

These tools let you inspect your account configuration:

Subscriber management

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

Preferences

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

Workflow management

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

Triggering and events

These tools let you execute workflows and manage pending notifications:

Notifications

These tools let you inspect delivery and execution data:

Integrations

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

Troubleshooting

If your setup isn't working, the following sections cover the most common issues.