Notifications

These tools let an agent check that Herald is running, put a banner or a spoken message in front of the user, take a banner away again, and ask the user a question and wait for the answer. They are the part of the MCP server an agent uses while it works, as opposed to the tools that design how banners look (templates) or change settings (apps and settings).

Every tool here is a thin wrapper over one call to Herald's HTTP API. The conventions shared by all tools (result format, errors, the app default of an agent) are in the MCP server overview.

How these tools fit together#

A notification belongs to an app, identified by an id such as example.bidbot. An agent installed from Settings > MCP has an app of its own (agent.claude-code, for example) and the server sends as that app when a call leaves app out. See Agent identity.

The usual order of calls:

1. herald_status once, to confirm Herald is running.
2. send_notification to tell the user something, or speak to say it without a banner.
3. wait_for_reply when the notification asked a question.
4. dismiss or snooze when the event behind a banner is over or can wait.

While you design a template, call send_test instead of send_notification: it fills the fields from the manifest's sample values, so you do not have to invent a payload.

Tools#

Check that Herald is running#

Call this first. Every other tool except component_schema and validate_template needs Herald running.

herald_status#

Reports whether Herald answers, which version it is, which port and support folder this server uses, how many apps, manifests, templates and Shortcuts exist, and which script files are in the scripts folder. It never fails: when Herald is down it says so and says how to start it.

Arguments

No arguments.

{}

{
  "server": "herald-mcp 1.1.0",
  "supportDirectory": "/Users/you/Library/Application Support/Herald",
  "port": 48617,
  "tokenFile": true,
  "running": true,
  "version": "1.8.1",
  "pid": 4821,
  "apps": ["example.bidbot", "herald"],
  "manifests": 1,
  "templates": 2,
  "shortcuts": 3,
  "scriptsDirectory": "/Users/you/Library/Application Support/Herald/scripts",
  "scripts": ["follow-up.sh"]
}

The fields of the result:

HTTP route

• GET /v1/health reports whether Herald runs.
• GET /v1/apps supplies the app ids.
• GET /v1/manifests supplies the manifest count.
• GET /v1/templates supplies the template count.
• GET /v1/shortcuts supplies the Shortcut count.

Side effects

None. Read-only.

Show a banner#

send_notification is the tool for real messages. send_test is the tool for checking a design.

send_notification#

Delivers a real notification: a banner appears on the user's screen and the notification is stored in History. The payload is the same as POST /v1/notify, so every notification field described there can be passed as an extra argument. Fields the tool does not list in its own table are passed through unchanged.

Two rules protect the user:

• A button, or a follow-up action, that carries a shell command, a script or a shortcut is refused unless allowCommandButtons is true. Anyone can send as any app id, and such a button would run under the permission the user gave that app to run commands, scripts and Shortcuts.
• When the app is an agent app (its id starts with agent.) and the call names no buttons, Herald shows the agent's own buttons: Open, Reply and, when the notification has a link, Open link.

A banner from an agent app with no buttons named in the call: Herald adds Open and Reply.

To ask a question, send with persistent: true and an id, then call wait_for_reply.

Arguments

{
  "app": "example.bidbot",
  "title": "Bid accepted",
  "body": "Your bid of $4,200 was accepted.",
  "id": "bid-42",
  "persistent": true,
  "buttons": [{"label": "Open", "url": "https://example.com/bids/42"}]
}

{"sent": true, "id": "bid-42", "app": "example.bidbot"}

When a command button is refused, the result has isError set and the reason in error, and nothing is sent.

HTTP route

POST /v1/notify.

Side effects

Shows a banner, plays the app's sound and adds a History entry. With speak, audio or presentation set it also speaks or plays. Quiet hours can hold back the sound and speech.

send_test#

Shows a saved template for real, so you can see the banner, its sound and its buttons on screen. Herald fills the template with the manifest's sample values and sends the manifest's actions as the issuer's buttons, so actionRules have something to act on. The template must be saved first with put_template. Use render_preview to look at a design without showing a banner.

The notification id is mcp-test-<template>, so calling the tool again overwrites the banner instead of stacking a new one. Manifest actions that run a shell command are left out unless allowCommandButtons is true. Pressing an issuer callback button calls the issuing app, so tell the user before they click.

Arguments

{"app": "example.bidbot", "template": "bid-won", "data": {"bids": 14}}

{
  "sent": true,
  "id": "mcp-test-bid-won",
  "app": "example.bidbot",
  "template": "bid-won",
  "fields": ["bids", "item", "title"],
  "issuerActions": ["view", "withdraw"],
  "leftOutCommandActions": []
}

The reply has these parts:

• fields lists the field keys that were sent.
• issuerActions lists the manifest actions shown as buttons.
• leftOutCommandActions lists the command actions that were held back.

The tool fails in two cases. If the template does not exist, the error lists the saved and built-in names. If neither template nor the manifest's defaultTemplate is available, the error says so.

HTTP route

• POST /v1/notify shows the banner.
• GET /v1/manifest is read first, for the sample values.
• GET /v1/templates is read first, to check that the template exists.

Side effects

Shows a real banner on the user's screen with sample values, plays the app's sound and adds a History entry.

Speak without a banner#

speak#

Says text aloud on the Mac with Herald's local voice, with no banner. History keeps the text, so the log stays searchable. Use it to report that a long task finished or needs attention. Keep it to a sentence or two. Nothing leaves the Mac.

Quiet hours hold speech back; a held message is logged in History as suppressed. See Quiet hours.

Arguments

{"app": "example.bidbot", "text": "The auction closed. You won the lot.", "id": "auction-7-done"}

{"spoken": true, "id": "auction-7-done", "app": "example.bidbot"}

HTTP route

POST /v1/speak. The voice fields are explained in Voice.

Side effects

Speaks aloud on the user's Mac and adds a History entry. Shows no banner.

Close or postpone a banner#

dismiss#

Closes banners. The notification stays in History. The arguments choose what closes:

• id closes one banner.
• group closes every banner of the app that was sent with that group (a stack).
• all: true closes every banner of the app.

If you give more than one, id wins, then group.

Arguments

One of id, group or all is needed.

{"app": "example.bidbot", "id": "bid-42"}

{"dismissed": "bid-42", "app": "example.bidbot"}

The result depends on the argument used:

• With group: {"dismissedGroup": "auction-7", "app": "example.bidbot"}.
• With all: {"dismissedAll": true, "app": "example.bidbot"}.

HTTP route

• POST /v1/dismiss closes one banner, when you give an id.
• POST /v1/dismissAll closes a stack or every banner, when you give a group or all.

Side effects

Closes banners on screen. Changes no stored data.

snooze#

Hides a banner and shows it again after minutes, the same as the clock menu on the banner. With cancel: true it brings a snoozed banner back at once, without a new alert sound.

Arguments

{"app": "example.bidbot", "id": "bid-42", "minutes": 30}

{"ok": true, "until": "2026-10-04T15:30:00Z"}

A cancel returns {"ok": true}.

HTTP route

• POST /v1/snooze hides the banner.
• POST /v1/unsnooze is used instead when cancel is true.

Side effects

Hides the banner now and shows it again later, or shows it at once on a cancel.

Stacks#

Herald folds notifications that share a stacking key into one banner with a counter. The user's stacking level decides the key:

The levels are explained in Stacking.

list_stacks#

Lists the stacks on screen, each with its level, app, group, count, whether it is open and its notifications, newest first. Use the app and group it returns with expand_stack and with dismiss.

Arguments

{"app": "example.bidbot"}

{
  "count": 1,
  "stacks": [
    {
      "level": "byIssuer",
      "app": "example.bidbot",
      "group": "auction-7",
      "count": 2,
      "expanded": false,
      "notifications": [
        {"app": "example.bidbot", "id": "bid-43", "title": "Outbid", "group": "auction-7", "deliveredAt": "2026-10-04T15:02:10Z"},
        {"app": "example.bidbot", "id": "bid-42", "title": "Bid accepted", "group": "auction-7", "deliveredAt": "2026-10-04T14:58:31Z"}
      ]
    }
  ]
}

HTTP route

GET /v1/stacks.

Side effects

None. Read-only.

expand_stack#

Opens a stack of banners as a list, or closes it again.

Arguments

{"app": "example.bidbot", "group": "auction-7", "expanded": true}

{"ok": true}

HTTP route

POST /v1/stacks/expand.

Side effects

Changes how a stack looks on screen. Changes no stored data.

Ask the user a question#

An agent has no web server of its own that Herald could call when the user presses a button, so answers come back through a queue. The sequence is: send a persistent notification with an id and status: "question", then wait for the reply to that id. The Reply button of an agent banner opens a text field inside the banner; what the user types is stored on the notification and in the app's reply queue. See How banners behave for the Reply action.

{"app": "agent.claude-code", "title": "Which branch?", "body": "main or release/2?", "status": "question", "persistent": true, "id": "q-branch"}

Send that with send_notification, then call wait_for_reply with {"notificationId": "q-branch", "timeoutSeconds": 120}.

get_replies#

Lists the answers the user typed into banners, oldest first, from a per-app queue. History keeps every reply on its notification whether or not the queue is cleared. Each reply has these fields:

Arguments

{"app": "agent.claude-code", "consume": true}

{
  "count": 1,
  "replies": [
    {
      "notificationId": "q-branch",
      "app": "agent.claude-code",
      "text": "release/2",
      "repliedAt": "2026-10-04T15:04:55Z",
      "title": "Which branch?"
    }
  ]
}

HTTP route

GET /v1/replies.

Side effects

With consume: true, removes the returned replies from the queue. Otherwise none.

wait_for_reply#

Waits until the user answers one notification, for at most timeoutSeconds.

• It answers at once when the reply is already there.
• When nothing arrives in time it returns replied: false. Call it again to keep waiting.
• A reply is taken out of the queue unless consume is false.

Arguments

{"notificationId": "q-branch", "timeoutSeconds": 120}

{
  "replied": true,
  "reply": {
    "notificationId": "q-branch",
    "app": "agent.claude-code",
    "text": "release/2",
    "repliedAt": "2026-10-04T15:04:55Z",
    "title": "Which branch?"
  }
}

When no answer came, the result is {"replied": false, "timedOut": true, "waitedSeconds": 120}.

HTTP route

GET /v1/replies/wait. The server allows the request the wait time plus 15 seconds.

Side effects

Blocks until a reply arrives or the time ends. Removes the reply from the queue unless consume is false.

Related#

• MCP server overview for the conventions and the index of every tool.
• Notifications API for the fields a notification accepts.
• Agent quick start to send a first notification as an agent.
• How banners behave for click, Reply, close and timeout.