Connect Novu to Claude: Manage Subscriber Preferences and Global Layouts

If you need to connect Novu to Claude to automate your notification infrastructure, update subscriber preferences, or deploy layout changes across environments, you need a Model Context Protocol (MCP) server. This server acts as the translation layer between Claude's LLM tool calls and Novu's REST APIs. You can either build and maintain 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 transactional notification engine like Novu is an engineering challenge. You must handle complex channel preference schemas, environment promotions, and strict API rate limits. Every time an endpoint changes or you need to expose a new template variable, 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, and execute complex 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 vendor APIs is painful. Novu is not a simple CRUD database. It is a stateful, environment-aware notification router.

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:

Multi-Channel Preference Hierarchies Novu manages user preferences globally and per-workflow across five distinct channels (email, SMS, in-app, push, and chat). The API payload to update these preferences requires a highly specific JSON structure. If you expose raw endpoints to Claude without well-defined JSON Schemas, the model will frequently hallucinate preference structures or attempt to pass invalid channel arrays. A managed MCP server translates these requirements into a strict, machine-readable schema that forces the LLM to output valid payloads.

Environment Promotion Complexity In Novu, resources like layouts and workflows belong to specific environments (Development vs. Production). Moving a template from Dev to Prod requires calling specialized sync endpoints with exact environment IDs. A custom MCP server must map these IDs accurately. If an LLM hallucinates an environment ID, it could accidentally overwrite production templates with untested layouts.

Strict Rate Limits and Error Handling Novu enforces limits on high-volume endpoints. If your AI agent decides to run a loop to manually trigger 500 individual events instead of using the bulk trigger endpoint, Novu will return an HTTP 429 Too Many Requests error. It is critical to note that Truto does not retry, throttle, or apply backoff on rate limit errors. When the upstream Novu API returns a 429, Truto passes that error directly to the caller. Truto normalizes the upstream rate limit information into standardized IETF headers (ratelimit-limit, ratelimit-remaining, ratelimit-reset). The caller - in this case, the Claude agent - is entirely responsible for interpreting these headers and executing retry and backoff logic.

Instead of building this boilerplate from scratch, you can use Truto. Truto normalizes authentication and pagination, exposing Novu's endpoints as ready-to-use MCP tools.

How to Generate a Novu MCP Server with Truto

Truto dynamically generates MCP tools based on the active API documentation and capabilities of your connected Novu instance. You can create an MCP server either through the Truto UI or programmatically via the API.

Method 1: Via the Truto UI

The fastest way to get started is by generating a server URL directly from the Truto dashboard.

1. Log into your Truto account and navigate to the integrated account page for your active Novu connection.
2. Click the MCP Servers tab.
3. Click Create MCP Server.
4. Select your desired configuration. You can filter the server to only allow specific methods (like read or write) or specific tags.
5. Click Save and copy the generated MCP server URL (it will look like https://api.truto.one/mcp/abc123def456). Keep this URL secret; it contains the authentication token for your Novu instance.

Method 2: Via the Truto API

For platform teams generating MCP servers automatically for their end-users, you can create a server via a REST API call. This provisions the server and returns the endpoint URL instantly.

Endpoint: POST /integrated-account/:id/mcp

Request body:

{
  "name": "Novu Automation Agent",
  "config": {
    "methods": ["read", "write", "custom"]
  }
}

Response:

{
  "id": "7f3a8b9c-1234-5678-abcd-9876543210ef",
  "name": "Novu Automation Agent",
  "config": {
    "methods": ["read", "write", "custom"]
  },
  "expires_at": null,
  "url": "https://api.truto.one/mcp/a1b2c3d4e5f6g7h8i9j0"
}

How to Connect the Novu MCP Server to Claude

Once you have your Truto MCP URL, you need to connect it to Claude. There are two ways to do this, depending on whether you are using the consumer-facing Claude interface or running a custom agent.

Method A: Via the Claude UI

If your organization has enabled custom connectors in Claude, you can add the server directly through the interface.

1. Copy the MCP server URL from Truto.
2. In Claude, navigate to Settings -> Integrations -> Add MCP Server (or the equivalent Custom Connectors menu for your tier).
3. Paste the Truto URL into the Server URL field.
4. Click Add. Claude will automatically perform the JSON-RPC initialization handshake and populate its context with the available Novu tools.

Method B: Via Manual Config File

If you are using Claude Desktop for local development, you must configure the MCP server by modifying the claude_desktop_config.json file. Because Truto MCP servers are hosted remotely, you must use the Server-Sent Events (SSE) transport protocol.

Locate your configuration file:

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

Add the following configuration, replacing the URL with your Truto MCP URL:

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

Save the file and restart Claude Desktop. The model will instantly ingest the tool schemas and be ready to execute commands.

Hero Tools for Novu Automation

Truto exposes the entirety of the Novu API, but a few high-leverage endpoints drive the majority of AI-led operations. Here are the core tools your agent will use to orchestrate notification infrastructure.

list_all_novu_subscribers

This tool allows Claude to query your subscriber base. It supports searching by email, phone, subscriberId, or name. This is critical for mapping a human-readable request to a strict Novu identifier before attempting any updates.

"Search our Novu subscribers for user 'alex.chen@example.com' and tell me their internal subscriberId and online status."

update_a_novu_subscriber_preference_by_id

Use this tool to update channel preferences for a subscriber. It handles the complex payload required to turn specific channels (like SMS or push) on or off, either globally or scoped to a specific workflowId.

"User 'alex.chen@example.com' (subscriberId: usr_8892) requested to stop receiving SMS notifications. Please update their Novu global preferences to disable the SMS channel, but leave email and in-app enabled."

novu_events_bulk_create

Instead of making repeated API calls that risk triggering HTTP 429 rate limit errors, this tool allows Claude to trigger multiple notification workflow events in a single payload. It is strictly capped at 100 events per request.

"We have an emergency maintenance window. Trigger the 'system-alert' workflow for these 45 subscriber IDs using the bulk create tool. Pass the maintenance start time as a payload variable."

create_a_novu_layout

Layouts act as the global HTML wrapper for your email notifications. This tool allows an LLM to generate raw HTML/CSS strings and save them directly as reusable templates in your Novu environment.

"Create a new Novu layout named 'Enterprise Standard 2026'. Use the provided HTML string containing our new logo and footer legal text. Set the content variable injected in the center."

update_a_novu_environment_variable_by_id

Novu environments rely on variables to swap out URLs or API keys between Dev and Prod. This tool lets Claude inject or update those variables programmatically.

"Update the environment variable 'MAIN_APP_URL' in our development environment to point to 'https://staging.example.com'."

novu_environments_publish

Once a layout, workflow, or configuration has been tested in Development, this tool promotes those changes to the target environment (typically Production). It effectively syncs the state between two Novu spaces.

"Publish the latest workflow changes from the current development environment to the production environment."

To view the complete inventory of available endpoints and schema definitions, visit the Novu integration page.

Workflows in Action

Exposing individual tools to Claude is only the first step. The real value of an MCP server is enabling the LLM to orchestrate complex, multi-step operations autonomously. Here are two practical examples.

Scenario 1: Global Subscriber Preference Audit and Update

Customer support teams frequently receive requests to alter communication preferences. Doing this manually requires logging into a dashboard, finding the user, and toggling specific channels. Claude can automate this entirely.

"A user named Sarah Jenkins emailed support asking to disable all push notifications but keep her email alerts. Find her in Novu and apply the correct preference updates globally."

How the agent executes this:

1. list_all_novu_subscribers: The agent searches for Sarah Jenkins to retrieve her specific subscriberId.
2. list_all_novu_subscriber_preferences: The agent retrieves her current preference state to ensure it doesn't overwrite necessary configurations.
3. update_a_novu_subscriber_preference_by_id: The agent submits a payload targeting the push channel, setting enabled: false, while leaving email untouched.

The agent confirms to the user that the push channel has been deactivated globally for Sarah.

Scenario 2: Promoting a Template Layout to Production

Updating email templates across environments usually requires a developer to manually copy HTML strings or click through the Novu UI to initiate a sync. Claude can manage this deployment pipeline.

sequenceDiagram
    participant User as Developer
    participant Claude as Claude
    participant MCP as Truto MCP
    participant NovuDev as Novu (Dev)
    participant NovuProd as Novu (Prod)
    
    User->>Claude: "Create a 'Holiday Promo' layout in Dev, then publish to Prod."
    Claude->>MCP: Call create_a_novu_layout (HTML payload)
    MCP->>NovuDev: POST /v1/layouts
    NovuDev-->>MCP: 201 Created (Layout ID)
    Claude->>MCP: Call novu_environments_publish
    MCP->>NovuProd: POST /v1/environments/publish
    NovuProd-->>MCP: 204 No Content
    MCP-->>Claude: Success
    Claude->>User: "Layout created and synced to Production."

How the agent executes this:

1. create_a_novu_layout: The agent generates the requested HTML structure and submits it to the Dev environment.
2. novu_environments_compare: The agent optionally runs a diff to verify what changes are staged for promotion.
3. novu_environments_publish: The agent triggers the sync, pushing the new 'Holiday Promo' layout into Production.

The user gets a fully deployed layout without writing a single API request.

Security and Access Control

Giving an AI agent administrative access to your notification infrastructure requires strict security controls. Truto provides several mechanisms to lock down your Novu MCP server:

• Method Filtering: Limit the server to specific operation types. For example, use methods: ["read"] to allow the agent to query subscribers and logs, but prevent it from triggering events or altering layouts.
• Tag Filtering: Restrict access to specific resource groups. If you only want the agent managing user data, you can tag subscriber endpoints and filter the MCP server to exclude workflow and environment endpoints entirely.
• Require API Token Auth: By enabling require_api_token_auth, possessing the server URL is no longer sufficient. The MCP client must also pass a valid Truto API token in the Authorization header, ensuring only authenticated personnel can invoke the tools.
• Expiration Dates: Use the expires_at property to create short-lived MCP servers. This is ideal for giving an agent temporary access to run a specific migration or deployment script, after which the server automatically self-destructs.

Moving Past Boilerplate Integration Code

Managing subscriber states, orchestrating multi-channel events, and syncing environment layouts via API requires significant engineering overhead. Hardcoding these endpoints into an LLM application guarantees maintenance debt the moment Novu updates a schema or alters a pagination cursor.

By routing Claude through a managed MCP server, you offload the authentication, schema mapping, and error passthrough. Your engineering team can focus on designing better AI workflows instead of debugging JSON payloads and tracking down rate limit headers.

:::cta{buttonText="Talk to us" buttonUrl="https://cal.com/truto/partner-with-truto"} Stop building custom LLM integration layers. Generate secure, authenticated MCP servers for Novu and 100+ other SaaS platforms in seconds. Talk to our engineering team today. :::