Skip to main content

Send in-app notifications in Cursor

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.

Cursor reads MCP servers from a JSON file, either per user or per project. Remote servers take a url and optional headers.

Setup

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

01Add the server to mcp.json

~/.cursor/mcp.json (or .cursor/mcp.json in a project)

{
  "mcpServers": {
    "nordva": {
      "url": "https://mcp.nordva.dev",
      "headers": {
        "Authorization": "Bearer nv_live_..."
      }
    }
  }
}

Use the file in your home directory if the key should not live in the repository. A project-level .cursor/mcp.json containing a key belongs in .gitignore.

02Check the connection

Open Cursor Settings and find the MCP section. nordva should be listed with its tools and a green status. In Agent mode, ask it to run setup_check.

Then ask Cursor

  • 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.” Cursor 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.
  • Cursor's agent decides when to call a tool from the tool descriptions; naming the tool in the prompt ("use publish_changelog_entry") removes the guesswork.
  • Tools that send email or remove content are flagged destructive by the server, and their descriptions tell the agent to confirm with you first.