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.

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:

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.

Add Novu as a custom connector using the MCP URL for your region, and choose OAuth as the connection mechanism. ChatGPT will prompt you to sign in to Novu.

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:

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.

<Prompt description="Switch an OAuth session to a specific environment" icon="bot" actions={["copy", "cursor"]}> List my Novu environments, then show notifications from Production (not Development). </Prompt>

Example prompts

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

Verify connection

<Prompt description="Test your Novu MCP connection" icon="bot" actions={["copy", "cursor"]}> Run whoami to verify I'm authenticated and show my Novu region. </Prompt>

<Prompt description="List your notification workflows" icon="bot" actions={["copy", "cursor"]}> Show me all my notification workflows in Novu. </Prompt>

Subscriber management

<Prompt description="Find a subscriber by email" icon="bot" actions={["copy", "cursor"]}> Find subscriber [email protected] in my Novu account and show their profile details. </Prompt>

<Prompt description="Create a new subscriber" icon="bot" actions={["copy", "cursor"]}> Create a new subscriber with subscriberId user-456, email [email protected], and firstName Jane in my Novu account. </Prompt>

Trigger and debug

<Prompt description="Trigger a workflow for a subscriber" icon="bot" actions={["copy", "cursor"]}> Trigger my welcome-email workflow for subscriber test-user-123 with payload containing userName "Jane" and activationLink "https://app.example.com/activate". </Prompt>

<Prompt description="Debug failed notifications" icon="bot" actions={["copy", "cursor"]}> Show recent failed notifications in the last 24 hours and help me debug delivery issues. </Prompt>

MCP tools

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

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:

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

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.

Related topics