> ## Documentation Index
> Fetch the complete documentation index at: https://novu-c5de82d9-nv-8794-quote-reply-docs.mintlify.site/llms.txt
> Use this file to discover all available pages before exploring further.

# Novu MCP Server

> Connect Cursor, Claude, ChatGPT, and other AI tools to the Novu MCP server to manage notifications, workflows, subscribers, agents, and conversations using natural language.

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.

<Note>
  Novu also hosts a separate **documentation MCP server** at [docs.novu.co/mcp](https://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.
</Note>

## About the Novu MCP server

The [Model Context Protocol (MCP)](https://modelcontextprotocol.io) 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](/agents/managed-agent/overview), then connect a channel
* List [agent conversations](/agents/conversations) and inspect activity timelines

Some AI tools support both MCP and [Agent Skills](/platform/build-with-ai/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](https://dashboard.novu.co/settings/api-keys)
* 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](#api-key-fallback) instead.

<Tabs>
  <Tab title="Cursor">
    Open **Cursor Settings** → **Tools & Integrations** → **New MCP Server**, and add:

    ```json theme={null}
    {
      "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.
  </Tab>

  <Tab title="VS Code">
    Add to `.vscode/mcp.json` (or your user MCP settings):

    ```json theme={null}
    {
      "servers": {
        "novu": {
          "type": "http",
          "url": "https://mcp.novu.co/"
        }
      }
    }
    ```

    Reload VS Code and approve the sign-in prompt when it appears.
  </Tab>

  <Tab title="Claude Code">
    ```bash theme={null}
    claude mcp add --transport http novu https://mcp.novu.co/
    ```

    Then run `/mcp` inside Claude Code to sign in.
  </Tab>

  <Tab title="ChatGPT">
    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.
  </Tab>

  <Tab title="Claude Desktop">
    Claude Desktop doesn't yet support remote OAuth, so connect with an API key through the [`mcp-remote`](https://www.npmjs.com/package/mcp-remote) proxy (requires Node.js 18+):

    ```json theme={null}
    {
      "mcpServers": {
        "novu": {
          "command": "npx",
          "args": [
            "mcp-remote",
            "https://mcp.novu.co/",
            "--header",
            "Authorization:Bearer your-novu-api-key"
          ]
        }
      }
    }
    ```
  </Tab>

  <Tab title="Codex">
    Codex connects with an API key today:

    ```bash theme={null}
    export NOVU_API_KEY="your-novu-api-key"
    ```

    ```toml theme={null}
    [mcp_servers.novu]
    url = "https://mcp.novu.co/"
    bearer_token_env_var = "NOVU_API_KEY"
    ```
  </Tab>

  <Tab title="Other">
    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](#api-key-fallback) if your client doesn't support OAuth |
  </Tab>
</Tabs>

### 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](https://dashboard.novu.co/settings/api-keys) and send it as a bearer token:

```json theme={null}
{
  "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.

<Warning>
  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](https://docs.novu.co/mcp).
</Warning>

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

<Note>
  Replace placeholder values (for example, subscriber IDs and workflow identifiers) with values from your Novu dashboard.
</Note>

### 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 [user@example.com](mailto:user@example.com) 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 [jane@example.com](mailto:jane@example.com), 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](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>

### Agents and conversations

<Prompt description="Create a managed agent and connect a channel" icon="bot" actions={["copy", "cursor"]}>
  Create a managed Novu agent named Support Bot with a system prompt that answers product questions briefly. After it is created, connect Slack to that agent.
</Prompt>

<Prompt description="Debug an agent conversation" icon="bot" actions={["copy", "cursor"]}>
  List my Novu agents, then show recent conversations for the support-bot agent and inspect the activity timeline of the latest thread.
</Prompt>

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

<Note>
  Every tool accepts an optional `environmentId` parameter - see [Environments](#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`.
</Note>

## Use multiple MCP servers

You can connect both the Novu MCP server and the [Novu documentation MCP server](https://docs.novu.co/mcp) 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

<AccordionGroup>
  <Accordion title="OAuth sign-in loop or never connects">
    Confirm the URL matches your region, and that you haven't also set an `Authorization` header - presenting a credential skips OAuth entirely. Restart your AI assistant after changing the config.
  </Accordion>

  <Accordion title="Wrong environment data">
    OAuth sessions default to Development. Call `get_environments` and pass the `_id` you want as `environmentId`.
  </Accordion>

  <Accordion title="401 after previously working">
    Your OAuth token expired or was revoked - reconnect through your client to sign in again.
  </Accordion>

  <Accordion title="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.
  </Accordion>

  <Accordion title="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`.
  </Accordion>

  <Accordion title="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](/platform/build-with-ai/agent-toolkit) with `backendUrl` set to your API, or call the REST API
    directly. You can still use the [Novu documentation MCP server](https://docs.novu.co/mcp) to search these docs.
  </Accordion>

  <Accordion title="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.
  </Accordion>
</AccordionGroup>

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

## Related topics

<Columns cols={2}>
  <Card title="Agent Skills" href="/platform/build-with-ai/skills">
    Give AI coding assistants implementation guidance for Novu SDKs and workflows.
  </Card>

  <Card title="Agent Toolkit" href="/platform/build-with-ai/agent-toolkit">
    Embed Novu tools inside your own AI agents with the `@novu/agent-toolkit` package.
  </Card>

  <Card title="Managed agents" href="/agents/managed-agent/overview">
    How managed agents, connectors, and channel connect work in Novu.
  </Card>

  <Card title="Agent conversations" href="/agents/conversations">
    How conversation lifecycle and activity look in the dashboard.
  </Card>

  <Card title="Novu Docs MCP" href="https://docs.novu.co/mcp">
    Connect AI tools to search and read this documentation site.
  </Card>

  <Card title="API keys" href="/platform/developer/api-keys">
    Learn how to create and manage the secret keys used for API key authentication.
  </Card>
</Columns>