Skip to main content

Send in-app notifications in VS Code

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.

VS Code's agent mode (GitHub Copilot Chat) loads MCP servers from .vscode/mcp.json. Inputs keep the key out of the file.

Setup

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

01Add the server to the workspace

.vscode/mcp.json

{
  "inputs": [
    {
      "type": "promptString",
      "id": "nordva-key",
      "description": "Nordva Launch secret key",
      "password": true
    }
  ],
  "servers": {
    "nordva": {
      "type": "http",
      "url": "https://mcp.nordva.dev",
      "headers": {
        "Authorization": "Bearer ${input:nordva-key}"
      }
    }
  }
}

VS Code prompts for the key the first time the server starts and stores it in its secret storage, so this file is safe to commit. Note that the top-level property is servers, not mcpServers.

02Check the connection

Run MCP: List Servers from the Command Palette and start nordva. In the Chat view, switch to Agent mode and check that the nordva tools are listed under the tools button. Ask it to run setup_check.

Then ask VS Code

  • 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.” VS Code 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.
  • MCP tools are only available in Agent mode, not in Ask or Edit mode.