Connect Novu to Claude: Manage Topics and Subscriber Engagement

If you need to connect Novu to Claude to automate notification workflows, manage complex subscriber preferences, or orchestrate multi-channel broadcasts, you need a Model Context Protocol (MCP) server. This server acts as the translation layer between Claude's natural language tool calls and Novu's REST APIs. You can either spend weeks building and maintaining this infrastructure yourself, or use a managed integration platform like Truto to dynamically generate a secure, authenticated MCP server URL.

If your team uses ChatGPT, check out our guide on connecting Novu to ChatGPT or explore our broader architectural overview on connecting Novu to AI Agents.

Giving a Large Language Model (LLM) read and write access to a notification infrastructure platform like Novu is an engineering challenge. You have to handle environment isolation, map massive nested preference schemas to MCP tool definitions, and deal with strict rate limits on bulk events. Every time Novu updates an endpoint or alters a schema, you have to update your server code, redeploy, and test the integration.

This guide breaks down exactly how to use Truto to generate a secure, managed MCP server for Novu, connect it natively to Claude Desktop, and execute complex notification workflows using natural language.

The Engineering Reality of the Novu API

A custom MCP server is a self-hosted integration layer. While the open MCP standard provides a predictable way for models to discover tools, the reality of implementing it against Novu's APIs is painful. You are not just integrating a standard CRUD API - you are integrating an event-driven notification engine.

If you decide to build a custom MCP server for Novu, you own the entire API lifecycle. Here are the specific challenges you will face:

The Upsert Paradigm and Silent Overwrites

Novu relies heavily on upserts for its core resources. When you hit the endpoint to create a subscriber or a topic, Novu will silently update the existing record if the identifier already exists. If you expose this raw behavior to Claude, the model might accidentally overwrite a critical system topic while trying to create a new one. Handling this safely requires injecting specific flags (like failIfExists=true) into the API requests or enforcing strict read-before-write validation logic in your MCP layer.

Deeply Nested Channel Preferences

Subscriber preferences in Novu are not flat booleans. They are deeply nested JSON trees spanning across five distinct channels (email, sms, in_app, chat, push) and can be overridden at the individual workflow level. When an LLM attempts to update a user's preferences to "turn off marketing SMS but keep transactional emails," it has to construct a massive JSON payload that precisely maps to Novu's level, enabled, and channels schema. Generating these schemas and validating the LLM's output against them requires extensive boilerplate code.

Environment Isolation

Novu strictly partitions data between environments (e.g., Development vs Production). Every API call requires an environment-specific API key. If your MCP server does not isolate these contexts perfectly, an AI agent testing a new notification flow could accidentally broadcast a message to your production user base. Truto handles this at the infrastructure level - each MCP server is cryptographically bound to a specific integrated account and environment, eliminating the risk of cross-environment contamination.

Transparent Rate Limit Handling

Notification platforms are highly sensitive to API abuse, especially on broadcast and bulk event endpoints. When you hit a rate limit, Novu returns an HTTP 429 status. A common mistake in custom MCP servers is trying to absorb these errors with internal retry loops, which leads to silent timeouts and stranded LLM context windows. Truto takes a different approach: it does not retry, throttle, or apply backoff on rate limit errors. When Novu returns a 429, Truto passes that error directly to Claude, but it normalizes the upstream rate limit info into standardized IETF headers (ratelimit-limit, ratelimit-remaining, ratelimit-reset). This allows the LLM framework to understand exactly how long it must wait before backing off and retrying the operation itself.

How to Generate a Novu MCP Server with Truto

Truto dynamically generates MCP tools based on the resources and documentation defined for your Novu integration. You do not write any custom tool logic. Instead, you create an MCP server scoped to a single authenticated Novu account, and Truto exposes the documented API endpoints as JSON-RPC 2.0 tools.

You can generate this server via the Truto UI or programmatically via the API.

Method 1: Via the Truto UI

If you want to quickly generate an MCP server for testing or internal agent deployment, use the Truto dashboard.

1. Log into Truto and navigate to Integrated Accounts.
2. Select the connected Novu account you want the agent to access.
3. Click the MCP Servers tab.
4. Click Create MCP Server.
5. Select your desired configuration (e.g., restrict to read methods only, or filter by specific tags like subscribers).
6. Copy the generated MCP server URL (it will look like https://api.truto.one/mcp/a1b2c3d4...).

Method 2: Via the Truto API

For production workflows, you should generate MCP servers programmatically. This allows you to spin up isolated, ephemeral AI environments on demand.

Make a POST request to /integrated-account/:id/mcp with your desired configuration:

curl -X POST https://api.truto.one/integrated-account/YOUR_ACCOUNT_ID/mcp \
  -H "Authorization: Bearer YOUR_TRUTO_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "name": "Claude Novu Automation Server",
    "config": {
      "methods": ["read", "write", "custom"]
    }
  }'

The API validates that the Novu integration has documented tools available, generates a secure, cryptographically hashed token, and returns a ready-to-use URL:

{
  "id": "mcp_12345abcde",
  "name": "Claude Novu Automation Server",
  "config": {
    "methods": ["read", "write", "custom"]
  },
  "expires_at": null,
  "url": "https://api.truto.one/mcp/a1b2c3d4e5f67890"
}

This URL is fully self-contained. It encodes the specific Novu tenant, the authentication state, and the method filters.

Connecting the Novu MCP Server to Claude

Once you have your Truto MCP URL, you need to register it with your Claude client. You can do this through the Claude Desktop interface or by modifying the local configuration file.

Method A: Via the Claude UI (If Supported)

If you are using an enterprise version of Claude or ChatGPT with UI-based connector support:

1. Open Settings -> Integrations (or Connectors).
2. Click Add MCP Server or Add custom connector.
3. Paste the Truto MCP URL (https://api.truto.one/mcp/...).
4. Click Add.

Claude will immediately execute an MCP initialize handshake, request the tools/list, and discover all available Novu endpoints.

Method B: Via Manual Config File (Claude Desktop)

For the standard Claude Desktop app, you connect remote MCP servers using a Server-Sent Events (SSE) proxy provided by the official Model Context Protocol CLI.

1. Open your Claude Desktop configuration file:

   • macOS: ~/Library/Application Support/Claude/claude_desktop_config.json
   • Windows: %APPDATA%\Claude\claude_desktop_config.json

2. Add the Truto MCP URL under the mcpServers object using the npx command to run the SSE client:

{
  "mcpServers": {
    "novu_truto": {
      "command": "npx",
      "args": [
        "-y",
        "@modelcontextprotocol/server-sse",
        "https://api.truto.one/mcp/YOUR_TRUTO_TOKEN"
      ]
    }
  }
}

3. Restart Claude Desktop. You will see a hammer icon indicating that the Novu tools are now available in your chat context.

Hero Tools for Novu Automation

Truto dynamically translates Novu's documentation into JSON Schema formats that Claude natively understands. When Claude invokes a tool, Truto maps the flat LLM arguments back into Novu's required query parameters and request bodies.

Here are the highest-leverage tools available for orchestrating Novu through Claude.

Trigger a Workflow Event

Tool: create_a_novu_event

This is the core operational tool in Novu. It triggers a notification workflow for one or more specified subscribers. The LLM must provide the workflow name and the to payload (which can be a subscriber ID or a full subscriber object).

"Trigger the 'weekly-digest' workflow for subscriber ID 'usr_9982'. Pass a custom data payload indicating that their account tier is 'enterprise'."

Create or Upsert a Topic

Tool: create_a_novu_topic

Topics allow you to group subscribers together for targeted broadcasts (like 'all-admins' or 'outage-alerts'). This tool creates a new topic using a unique key and a human-readable name.

"Create a new Novu topic with the key 'eu-server-alerts' and the name 'EU Server Outage Notifications'."

Manage Topic Subscriptions

Tool: create_a_novu_topic_subscription

Once a topic exists, you use this tool to bulk-add subscribers to it. It requires the topic_key and an array of subscriberIds.

"Add subscribers 'dev_01', 'dev_02', and 'ops_lead' to the 'eu-server-alerts' topic we just created."

Audit Global Channel Preferences

Tool: list_all_novu_subscriber_preferences

This tool retrieves the comprehensive preference tree for a specific subscriber. It returns their global channel settings as well as any specific workflow-level overrides, making it perfect for debugging why a user did not receive a specific email.

"Fetch the channel preferences for subscriber ID 'usr_9982'. Tell me if they have marketing emails disabled globally."

Bulk Update Subscriber Preferences

Tool: novu_subscriber_preferences_bulk_update

This powerful tool allows Claude to rewrite a subscriber's channel preferences across multiple workflows in a single request. It handles the complex nested JSON structure required by Novu behind the scenes.

"Update the preferences for subscriber 'usr_9982' to disable SMS and Push notifications entirely, but ensure Email remains enabled."

Sync Subscriber Profiles

Tool: create_a_novu_subscriber

This tool handles identity synchronization. It creates a new subscriber or updates an existing one based on the subscriberId. It accepts standard profile data like firstName, lastName, email, and custom data key-value pairs.

"Sync a new subscriber with the ID 'usr_5511'. Their name is Sarah Connor, email is sarah@example.com, and add custom data tagging her as a beta tester."

For the complete schema definitions and the full inventory of available Novu tools - including environments, inbound routes, and translations - visit the Novu integration page.

Workflows in Action

Connecting an LLM to Novu unlocks autonomous notification management. Here are two real-world examples of how you can instruct Claude to execute complex orchestration sequences.

Scenario 1: Automating an Incident Broadcast

An IT administrator needs to alert a specific group of engineers about an ongoing database migration, but they want to ensure they aren't manually tracking subscriber IDs.

"We have an emergency database migration on the US-East cluster. Create a temporary Novu topic called 'us-east-incident-jan24'. Add subscribers 'eng_mike', 'eng_sarah', and 'eng_david' to it. Then, trigger the 'critical-incident' workflow to that topic, passing the payload data { cluster: 'us-east', eta: '2 hours' }."

Step-by-step tool execution:

1. Claude calls create_a_novu_topic to establish the us-east-incident-jan24 topic.
2. Claude calls create_a_novu_topic_subscription passing the three engineer subscriber IDs to bind them to the topic.
3. Claude calls create_a_novu_event, setting the to field to target the newly created topic, and mapping the custom data payload.

sequenceDiagram
    participant User as IT Admin
    participant Claude as Claude Desktop
    participant Truto as Truto MCP Router
    participant Novu as Novu API
    User->>Claude: "Create topic, add users, trigger broadcast..."
    Claude->>Truto: call_tool("create_a_novu_topic")
    Truto->>Novu: POST /v1/topics
    Novu-->>Claude: Success (Topic Created)
    Claude->>Truto: call_tool("create_a_novu_topic_subscription")
    Truto->>Novu: POST /v1/topics/us-east-incident-jan24/subscribers
    Novu-->>Claude: Success (Subscribers Added)
    Claude->>Truto: call_tool("create_a_novu_event")
    Truto->>Novu: POST /v1/events/trigger
    Novu-->>Claude: Success (Event Dispatched)
    Claude->>User: "The topic is created and the incident workflow has been triggered."

Scenario 2: Resolving Subscriber Channel Fatigue

A support engineer is dealing with a customer who is complaining about receiving too many automated SMS alerts, but still wants to receive billing receipts via email.

"Customer with subscriber ID 'cust_882' is getting too many text messages. Check their current preferences. If SMS is enabled globally, use the bulk update tool to disable their SMS and Push channels, but explicitly keep their Email channel enabled for all workflows."

Step-by-step tool execution:

1. Claude calls list_all_novu_subscriber_preferences for cust_882 to audit the current state.
2. Claude analyzes the JSON response and identifies that the SMS channel is set to enabled: true globally.
3. Claude constructs the nested payload and calls novu_subscriber_preferences_bulk_update to disable SMS and Push while preserving Email.
4. Claude informs the support engineer that the customer's notification noise has been reduced.

Security and Access Control

Exposing an event-driven notification engine to an LLM requires strict governance. Truto MCP servers provide multiple layers of access control configured directly at the server level, ensuring the AI agent can only perform authorized actions.

• Method Filtering: You can restrict a server to specific operations via the config.methods array. Passing ["read"] ensures Claude can audit preferences and topics, but cannot trigger events or create new subscribers.
• Tag Filtering: Integration endpoints are grouped by tags. Passing config.tags: ["subscribers"] exposes only subscriber management tools, hiding sensitive administrative endpoints like environments or domains.
• Secondary Authentication: By setting require_api_token_auth: true, you mandate that the Claude client must supply a valid Truto API token in the headers. This prevents unauthorized access even if the MCP URL is leaked in internal documentation.
• Auto-Expiration: For temporary tasks (like migrating a batch of subscriber preferences), you can set an expires_at ISO datetime. Cloudflare KV and durable objects automatically destroy the token and credentials precisely when the timer hits zero.

Connecting Claude to Novu via a managed MCP server transforms how engineering and support teams handle notification logic. Instead of navigating complex API documentation and writing one-off scripts to fix subscriber states, you can orchestrate your entire messaging infrastructure through natural language.