Skip to main content

Send in-app notifications from Claude Desktop

Three tools over a small API: send a notification to a user id, list what is unread, mark it read. Useful when an agent runs a job on someone's behalf and should tell them when it is done, or when you want to check what a user is seeing without writing a query.

Claude Desktop's config file starts local processes, so a remote server with a header is reached through the mcp-remote bridge. Node.js 18 or later must be installed.

Setup

You need a secret key (nv_live_…) from Dashboard → API keys.

01Add the bridge to the config file

claude_desktop_config.json (Settings → Developer → Edit Config)

{
  "mcpServers": {
    "nordva": {
      "command": "npx",
      "args": [
        "-y",
        "mcp-remote",
        "https://mcp.nordva.dev",
        "--header",
        "Authorization:${NORDVA_AUTH}"
      ],
      "env": {
        "NORDVA_AUTH": "Bearer nv_live_..."
      }
    }
  }
}

The header value is passed through an environment variable because some platforms split arguments that contain a space. On macOS the file is in ~/Library/Application Support/Claude/, on Windows in %APPDATA%\Claude\.

02Check the connection

Quit and reopen Claude Desktop. The nordva tools should appear in the tools menu of a new chat. Ask it to run setup_check.

Then ask Claude Desktop

  • Notify user 4812 that their import finished, with a link to /imports/77.
  • What unread notifications does user 4812 have?
  • Mark all of user 4812's notifications as read.

For “Notify user 4812 that their import finished, with a link to /imports/77.” Claude Desktop calls send_notification with:

{
  "user_id": "4812",
  "title": "Import finished",
  "body": "1,204 rows imported, 3 skipped.",
  "action_url": "https://app.example.com/imports/77"
}

Returned: The notification id, the user id and the time it was created. The user's client sees it the next time it polls the unread endpoint.

Notifications tools and arguments

send_notification

Confirms firstBuilder

Send an in-app notification to one of your users

user_idrequiredstring, max 256Developer-supplied identifier of the recipient.
titlerequiredstring, max 200Notification headline.
bodyrequiredstring, max 2,000Notification body text.
action_urloptionalstring, max 2,048URL the recipient should be sent to on click.
iconoptional"check" | "warning" | "info" | "error"Visual icon hint.

get_unread_notifications

Read-onlyBuilder

List unread notifications

user_idoptionalstring, max 256Filter to a specific recipient.
limitoptionalnumber, 1–100Page size.
sinceoptionalstringReturn only notifications created strictly after this ISO timestamp.

mark_notifications_read

Builder

Mark notifications as read

notification_idoptionalstring, max 128Mark this specific notification id read.
user_idoptionalstring, max 256Restrict bulk mark-read to one recipient.

Behaviour worth knowing

  • All three tools require the Builder plan. Other plans receive PLAN_UPGRADE_REQUIRED.
  • send_notification reaches a real end user, so the server marks it destructive and clients ask before calling it.
  • Delivery is by polling: your front end reads GET /v1/notifications/unread with a publishable key. Nothing is pushed.
  • mark_notifications_read works on one notification id, or on everything for a user id.
  • Notifications older than 90 days are pruned.
  • The Connectors screen in Claude Desktop and claude.ai expects OAuth. The Nordva Launch server authenticates with an API key header instead, which is why the bridge is needed there.