How to use the Novu MCP server

AI coding assistants can read your code, but they cannot automatically inspect the live systems your application depends on. Without access to your Novu account, they can suggest SDK calls, but they cannot see your actual workflows, subscribers, integrations, or delivery activity.

The Novu MCP server closes that gap. It gives compatible AI clients controlled access to your Novu account. Once connected, your assistant can create workflows, trigger notifications, update subscribers, inspect integrations, and debug delivery failures.

For Novu Cloud, compatible clients can connect through OAuth. Add the Novu MCP URL, sign in to your Novu account, and authorize the connection. Clients that do not support remote OAuth can continue to connect with a Novu API key.

What the Novu MCP server gives your AI client

The Model Context Protocol, or MCP, is an open standard that allows AI applications to connect to external services through discoverable tools.

The Novu MCP server exposes focused operations for working with your notification infrastructure. Your AI assistant can use these tools to:

• Create, inspect, update, and delete workflows
• Trigger workflows for individual subscribers or in bulk
• Search for and manage subscribers
• Read and update subscriber preferences
• Inspect notification activity and execution logs
• Review and manage channel integrations
• Cancel pending workflow events

The server currently exposes 23 tools across authentication, environments, subscribers, preferences, workflows, notifications, and integrations. Your client discovers these tools automatically after connecting.

Connect the Novu MCP server

Choose the endpoint for your Novu Cloud region, then connect using OAuth or an API key.

Choose the endpoint for your region

Novu Cloud provides a separate MCP endpoint for each region:

Use the EU endpoint when you access your account through eu.dashboard.novu.co. Otherwise, use the US endpoint.

Connect with OAuth

OAuth is the recommended authentication method for interactive clients that support it.

You do not need to copy a secret key into your client configuration. Add the Novu MCP endpoint, then sign in to Novu when your client prompts you.

Cursor

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

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

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

Claude Code

Run:

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

Then open Claude Code and run:

/mcp

Follow the prompt to sign in to Novu.

For setup instructions for VS Code, ChatGPT, Claude Desktop, Codex, and other clients, see the Novu MCP server documentation.

Connect with an API key

Use a Novu API key when your client does not support remote OAuth.

API-key authentication is also required for:

• mcp-remote and other stdio proxy configurations
• Autonomous agents without an interactive sign-in flow
• Self-hosted Novu deployments
• Automated environments that load credentials from a secret manager

Copy the secret key for the appropriate environment 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"
      }
    }
  }
}

Providing an API key skips the OAuth sign-in flow. Each API key belongs to one Novu environment, so use a key and MCP endpoint from the same region.

Verify the connection

Verify that your assistant can authenticate before using a tool that changes your Novu account.

Ask your assistant:

Run whoami to verify that I am authenticated and show my Novu organization and region.

The whoami tool confirms the credential and shows the connected identity and region.

You can then test read access:

List the workflows in my Novu environment.

Review the organization, region, and environment before approving operations that modify your Novu account.

Work with the correct Novu environment

OAuth sessions are scoped to your Novu organization and default to the Development environment.

To work with another environment, ask your assistant to call get_environments. It can then pass the selected environment's _id as the environmentId parameter when calling other Novu tools.

For example:

List my Novu environments, then show the workflows in Production.

API keys behave differently. Each API key already belongs to one environment, so passing environmentId does not change the environment used by an API-key session.

What you can do with Novu MCP

Once connected, your assistant can work with the live resources in your Novu account instead of relying only on the code and documentation in its context.

Build and update notification workflows

Creating a notification workflow can require moving between your editor and the Novu dashboard. You create the workflow, configure its channel steps and content, select integrations, and then copy its identifier into your application.

With the Novu MCP server connected, you can start with a prompt:

Create a workflow called order-shipped. Send an in-app notification when an order ships, then send an email after 24 hours if the subscriber has not read the notification.

The assistant can call create_workflow, configure the steps, and create the workflow in your selected Novu environment.

It can then return the workflow identifier for use in your application. Because the assistant has access to your Novu account, it can work with the workflows and integrations that are actually available in that environment.

Debug notification delivery failures

Debugging a failed notification often requires inspecting several pieces of information:

• The workflow that ran
• The subscriber who received it
• The channel integration used
• The status of each workflow step
• Any errors returned by the provider

You can ask:

Why did the order-confirmation notification fail for subscriber user_789?

The assistant can find the subscriber, retrieve matching notifications, inspect the execution logs, and summarize the failure.

For example, it may find that the provider rejected the request, the subscriber disabled the channel, a required subscriber field was missing, or the integration was not configured correctly.

The explanation comes from your Novu delivery activity rather than an inference based only on your application code.

Manage subscribers, preferences, and integrations

The Novu MCP server can also perform operations that would otherwise require a script or several dashboard actions.

For example:

Trigger the re-engagement workflow for these subscriber IDs.

Cancel the pending order-confirmation event for subscriber user_789.

Disable Slack notifications for subscriber user_456, but leave email and push enabled.

Check whether my SendGrid and Twilio integrations are active.

Depending on the request, the assistant can call tools such as bulk_trigger_workflow, cancel_triggered_event, update_subscriber_preferences, or get_active_integrations.

Review the proposed tool call before approving operations that modify workflows, subscribers, preferences, integrations, or delivery state.

Pair Novu MCP with other AI resources

The Novu MCP server can work alongside Novu Agent Skills and the Novu documentation MCP server. Each gives your assistant a different type of context or capability.

Novu Agent Skills

The Novu MCP server and Novu Agent Skills solve related but different problems.

The MCP server gives your assistant live access to your Novu account. It can inspect and modify workflows, subscribers, integrations, and delivery activity.

Agent Skills provide implementation guidance for working with Novu APIs, SDKs, workflow patterns, and notification architecture.

Use the MCP server when your assistant needs to interact with account data. Use Agent Skills when it needs guidance for implementing Novu correctly in your codebase. You can use both together.

Novu documentation MCP server

Novu also provides a separate MCP server for its documentation.

The two MCP servers have different responsibilities:

Server

Connect both when you want your assistant to work with your live account and consult the Novu documentation during implementation.

For example, the prompt "Trigger my welcome workflow" should use the Novu MCP server. The prompt "How do I configure a digest step?" should use the documentation MCP server.

Missing a tool? Request it on the roadmap

Novu MCP continues to grow alongside the product, with new tools shaped by what developers need to accomplish from their AI clients.

Submit a request on the Novu public roadmap when you need:

• A Novu operation that is not currently exposed as a tool
• An action your assistant cannot express
• A workflow your team repeatedly has to complete outside its AI client

Upvotes and comments help the team understand which capabilities to prioritize.

Start using Novu MCP

Novu MCP is available on every Novu Cloud plan. Self-hosted deployments can connect using a Novu API key.

OAuth is available for Novu Cloud and is the recommended authentication method for compatible interactive clients. API keys remain supported for self-hosted deployments, autonomous agents, and clients that do not support remote OAuth.

Create a Novu account and connect the MCP server to your preferred AI client, or read the Novu MCP server documentation for complete client configurations, available tools, example prompts, security guidance, and troubleshooting steps.