Apps, settings & history

These MCP tools manage the things around the banners: the apps that send them, the approvals the user has given, Herald's own settings, quiet hours, the voice and MCP installers, and History. They are for an agent that has to change how Herald behaves for the user, clean up after itself, or look back at what was sent. Every tool here is a thin wrapper over one route of the HTTP API; the tool index lists the rest of the server.

Concepts#

An app is whatever sends notifications, identified by an id such as example.bidbot. Herald creates the app the first time it sends something, or you can create it on purpose with register_app. The record holds a display name, an icon, the bundle id to bring to the front on a click, and the defaults that apply to its banners. The user sees and edits the same record in Settings > Apps.

Per-app settings are what the user decides about one app: its sound, whether banners stay until dismissed, its timeout, the screen corner and display, whether its banners are muted, how they stack, and whether its notifications are spoken. update_app_settings changes them. They are the user's preferences, so say what you change.

Show the whole capture

The Apps tab is what list_apps reads and update_app_settings writes. The Allow this app to run commands switch is an approval that can only be granted here.

Approvals are the permissions only the user can give. There are two kinds:

• An app can be allowed to run command, script and Shortcut buttons, and to call a callback host that is not on this Mac. These are shown by list_apps under approvals.
• A template's commands, scripts and Shortcuts are approved one template at a time, the first time its button is pressed. These are shown by list_approvals.

No tool can grant an approval. A tool can list approvals and withdraw them:

• update_app_settings accepts revokeCommands: true and revokeCallbackHost: true.
• revoke_approval withdraws a template's approval.
• A request that tries to grant one is refused.

After a withdrawal the user is asked again the next time the button is pressed.

Settings are all or nothing. set_settings checks every key and value first. If one is wrong, nothing is changed and the error names the key. The same holds for update_app_settings.

History is the record of every notification Herald delivered, kept after its banner is gone. The history tools read it, show an entry again, export it and delete from it. The format of the records is in History.

Tools#

• Apps
  • register_app
  • list_apps
  • delete_app
  • update_app_settings
• Approvals
  • list_approvals
  • revoke_approval
• Settings
  • get_settings
  • set_settings
• Quiet hours
  • get_quiet_hours
  • set_quiet_hours
• Voice and MCP setup
  • voice_status
  • install_voice
  • install_mcp
• History
  • list_history
  • history_search
  • reshow_notification
  • delete_history
  • export_history

Apps#

These tools create, read, change and remove the records of the apps that send to Herald.

register_app#

Creates an app or updates it. Call it to give an app a display name, an icon, a bundle id and defaults before it sends anything, or to describe an app that does not register itself. Fields you leave out keep their value.

Arguments

{
  "app": "example.bidbot",
  "appName": "BidBot",
  "bundleId": "com.example.bidbot",
  "defaults": {"sound": "Glass", "persistent": true, "timeout": 0}
}

{"ok": true}

HTTP route

POST /v1/register

Side effects

Creates or changes the app record. Shows nothing and never grants the command permission.

list_apps#

Lists the apps that have sent to Herald, with each app's per-app settings, voice settings and approvals. Call it to find an app id, to see what the user has set before you change it, or to check whether an app may run commands.

Arguments

{"app": "example.bidbot"}

{
  "apps": [
    {
      "app": "example.bidbot",
      "appName": "BidBot",
      "bundleId": "com.example.bidbot",
      "settings": {
        "sound": "Glass",
        "persistent": true,
        "timeout": 0,
        "display": "main",
        "muteBanners": false,
        "effectiveCorner": "topRight",
        "corner": null,
        "stacking": null,
        "opens": "com.example.bidbot"
      },
      "voice": {"speak": true, "voice": null, "speed": null, "urgentBreaksQuiet": false},
      "approvals": {
        "commandsRequested": false,
        "commandsConfirmed": false,
        "commandsAllowed": false,
        "callbackHostRegistered": null,
        "callbackHostApproved": null
      }
    }
  ],
  "schema": [
    {"key": "timeout", "group": "Defaults", "type": "number", "description": "Auto-dismiss after this many seconds; 0 never.", "min": 0, "max": 86400}
  ]
}

Response fields

HTTP route

GET /v1/apps/settings

Side effects

None. Read-only.

delete_app#

Removes an app for good: its record, all of its History, its templates, its manifest and the Rive copies, and the icon files Herald made for it. Use it for test and demo apps registered by mistake. It does not revoke a cloud connector: use revoke_agent_key for that.

Arguments

{"app": "example.demo"}

{"ok": true, "deleted": "example.demo"}

HTTP route

DELETE /v1/apps/{id}

Side effects

Destructive and not undoable. Deletes the app's data and closes any banner it still has up. An unknown app is a 404, and Herald's own app, herald, cannot be removed (409). Ask the user first.

update_app_settings#

Changes one app's settings, the same ones the user sets in Settings > Apps. Call it when the user asks for a change such as "mute this app" or "show its banners bottom left". It can also withdraw an approval, never grant one.

Arguments

{
  "app": "example.bidbot",
  "settings": {"muteBanners": true, "corner": "bottomLeft"}
}

{
  "ok": true,
  "applied": ["corner", "muteBanners"],
  "app": {
    "app": "example.bidbot",
    "appName": "BidBot",
    "settings": {
      "sound": "Glass",
      "persistent": true,
      "timeout": 0,
      "display": "main",
      "muteBanners": true,
      "effectiveCorner": "bottomLeft",
      "corner": "bottomLeft",
      "stacking": null
    },
    "voice": {"speak": true, "voice": null, "speed": null, "urgentBreaksQuiet": false},
    "approvals": {
      "commandsRequested": false,
      "commandsConfirmed": false,
      "commandsAllowed": false,
      "callbackHostRegistered": null,
      "callbackHostApproved": null
    }
  }
}

HTTP route

PUT /v1/apps/settings

Side effects

Changes the user's per-app preferences. All or nothing: one bad key changes nothing. Send revokeCommands: true or revokeCallbackHost: true to withdraw an approval. Any other value for those two keys is refused with 403, because only the user grants an approval, in Settings > Apps.

Approvals#

These tools show and withdraw the approvals the user gave to a template's commands, scripts and Shortcuts. There is no tool that grants one.

list_approvals#

Lists the commands, scripts and Shortcuts the user has approved. Call it to see what a template is already allowed to run, or to find the app and template names to pass to revoke_approval.

The followUps list has one row for each template with an enabled follow-up that runs code, and one for each manifest that declares an enabled one. Each row has an approval: approved, needs-approval, app-permission-needed, app-not-allowed or none. Use it to see which follow-ups are waiting for the person. The fields are in GET /v1/actions/approvals.

Arguments

No arguments.

{}

{
  "items": [
    {
      "app": "example.bidbot",
      "template": "Bid won",
      "commands": ["open -a Notes"],
      "approvedAt": "2026-10-01T09:30:00.000Z"
    }
  ],
  "followUps": [
    {
      "app": "example.bidbot",
      "template": "Bid won",
      "source": "template",
      "action": "Forward",
      "kind": "shortcut",
      "origin": "template",
      "approval": "needs-approval"
    }
  ],
  "note": "Approvals are granted by the user when a banner asks; here they can only be listed and revoked."
}

HTTP route

GET /v1/actions/approvals

Side effects

None. Read-only.

revoke_approval#

Withdraws the approval for one template. The user is asked again the next time one of its command, script or Shortcut buttons is pressed. Call it when the user wants to take back a permission.

Arguments

{"app": "example.bidbot", "template": "Bid won"}

{"ok": true}

HTTP route

DELETE /v1/actions/approvals

Side effects

Destructive for the user's earlier decision. Changes state only; shows nothing. A pair with no approval is a 404.

Settings#

These tools read and change Herald's general and voice settings, the ones in Settings > General, Voice and Tooltips. Quiet hours and per-app settings have their own tools.

get_settings#

Reads every general and voice setting with its current value, a schema that says what each key accepts, and the lists of valid choices. Call it before set_settings to see the keys and the current values.

Arguments

No arguments.

{}

{
  "settings": {
    "port": 48617,
    "launchAtLogin": true,
    "muteAllSounds": false,
    "stacking": "byApp",
    "historyCapPerApp": 500,
    "tooltipLevel": "nameAndDescription",
    "voiceEngine": "kokoro",
    "voiceDefault": "af_heart",
    "voiceSpeed": 1,
    "voiceLang": "en-us",
    "voiceSystem": null
  },
  "schema": [
    {"key": "muteAllSounds", "group": "General", "type": "boolean", "description": "Global mute for notification sounds (the bell menu's Mute)."}
  ],
  "options": {
    "sounds": ["none", "Glass", "Ping"],
    "displays": [{"id": "main", "name": "Main display"}],
    "corners": ["topRight", "topLeft", "bottomRight", "bottomLeft"],
    "stackingLevels": ["byApp", "byIssuer", "bySender", "never"],
    "voiceEngines": ["kokoro", "system", "off"],
    "voices": [{"id": "af_heart", "name": "Heart"}],
    "historyCapChoices": [100, 500, 1000]
  }
}

Response fields

HTTP route

GET /v1/settings

Side effects

None. Read-only.

set_settings#

Changes one or more general or voice settings in a single call. Every value is checked first; one bad key changes nothing. These are the user's own preferences, so say what you are changing. The keys, types and ranges are in PUT /v1/settings.

Arguments

{"settings": {"muteAllSounds": true, "stacking": "bySender", "voiceSpeed": 1.2}}

Example result

The reply is the same as get_settings with the keys that were changed listed in applied. schema and options are shortened here.

{
  "settings": {
    "port": 48617,
    "launchAtLogin": true,
    "muteAllSounds": true,
    "stacking": "bySender",
    "historyCapPerApp": 500,
    "tooltipLevel": "nameAndDescription",
    "voiceEngine": "kokoro",
    "voiceDefault": "af_heart",
    "voiceSpeed": 1.2,
    "voiceLang": "en-us",
    "voiceSystem": null
  },
  "schema": [
    {"key": "voiceSpeed", "group": "Voice", "type": "number", "description": "The default speech speed, 0.5 to 2.0.", "min": 0.5, "max": 2}
  ],
  "options": {"corners": ["topRight", "topLeft", "bottomRight", "bottomLeft"]},
  "applied": ["muteAllSounds", "stacking", "voiceSpeed"]
}

HTTP route

PUT /v1/settings

Side effects

Changes the user's settings. All or nothing. Changing port restarts the local server a moment after the reply and the reply carries a note saying so; this MCP server follows the new number from the port file. Changing launchAtLogin registers or removes the login item.

Quiet hours#

Quiet hours are the times Herald stays silent: spoken text, sounds and optionally banners. A window repeats on chosen days. An ad hoc silence starts now and runs until a time you give. The full rules, including what an urgent notification can break through, are in Quiet hours.

get_quiet_hours#

Reads the schedule, any ad hoc silence and what is silenced right now. Call it before you speak or send a sound, or before you change the schedule. While speech is silenced, speak and send_notification with speech are held back and logged in History as suppressed with the reason quiet-hours.

Arguments

No arguments.

{}

{
  "windows": [
    {
      "id": "w1",
      "days": [],
      "start": "22:30",
      "end": "07:30",
      "speech": true,
      "sounds": false,
      "banners": false,
      "speakSummary": false
    }
  ],
  "status": {
    "active": true,
    "speech": true,
    "sounds": false,
    "banners": false,
    "until": "2026-10-05T07:30:00.000Z",
    "source": "window"
  }
}

Response fields

HTTP route

GET /v1/settings/quiet-hours

Side effects

None. Read-only.

set_quiet_hours#

Changes quiet hours. Tell the user before you silence them. Give one of:

• windows to replace the schedule.
• until or minutes to start an ad hoc silence.
• resume to end the current silence.

Arguments

At least one of windows, until, minutes or resume is required.

{"windows": [{"days": ["mon", "tue", "wed", "thu", "fri"], "start": "22:30", "end": "07:30", "speech": true, "sounds": true}]}

{
  "windows": [
    {
      "id": "w2",
      "days": ["mon", "tue", "wed", "thu", "fri"],
      "start": "22:30",
      "end": "07:30",
      "speech": true,
      "sounds": true,
      "banners": false,
      "speakSummary": false
    }
  ],
  "status": {"active": false, "speech": false, "sounds": false, "banners": false}
}

HTTP route

PUT /v1/settings/quiet-hours

Side effects

Changes the user's schedule or starts or ends a silence. windows replaces every window, so read the schedule with get_quiet_hours first if you want to keep the others. A notification with priority urgent breaks quiet hours only for apps whose Urgent can break quiet hours setting the user turned on.

Voice and MCP setup#

These tools mirror Settings > Voice and Settings > MCP. They report what is installed and start the installers. See Voice for what the voice engines do and the MCP guide for connecting a client.

voice_status#

Reports the speech engine, whether the optional Kokoro voice is installed, the install progress and the voices available. Call it before you ask the user to install Kokoro, and to poll after install_voice.

Arguments

No arguments.

{}

{
  "engine": "kokoro",
  "kokoro": {
    "installed": false,
    "missing": ["kokoro-v1.0.onnx", "voices-v1.0.bin", "Python environment"],
    "folder": "/Users/you/Library/Application Support/Herald/tts",
    "busy": true,
    "phase": {"state": "downloading", "file": "kokoro-v1.0.onnx", "fraction": 0.42},
    "existingInstallationAvailable": false,
    "log": ["Downloading kokoro-v1.0.onnx"]
  },
  "voices": [{"id": "af_heart", "name": "Heart"}],
  "lastError": null
}

Response fields

HTTP route

GET /v1/voice

Side effects

None. Read-only.

install_voice#

Starts, cancels or shortcuts the Kokoro voice install. Call it only after the user agrees, because install downloads about 340 MB and builds a Python environment. Poll voice_status for progress.

Arguments

{"action": "install"}

{"ok": true, "action": "install", "next": "Poll GET /v1/voice for progress."}

HTTP route

POST /v1/voice/install

Side effects

Downloads files and creates a folder on this Mac. Ask the user first. Two calls fail by design:

• install when Kokoro is already installed is a 409.
• useExisting with no complete ~/.claude/tts is a 404.

install_mcp#

Without client, reports the status of each MCP client and the path of the server. With client, adds herald-mcp to that client's configuration, registers the agent as an app, and gives it a manifest, a default template and an icon. Call it only when the user asked for it, because it edits another application's configuration.

Arguments

What the install does depends on client:

• cli installs the herald command-line tool instead of an MCP entry.
• For the other clients, the server is added with --agent <client> and a backup of the configuration file is kept. claudeCode runs claude mcp add.
• Running it again keeps the user's edits.
• The agent's app id is agent.claude-code, agent.codex, agent.claude-desktop or agent.<slug>, as in Agent identity.
• Without opens, the button opens Claude.app for Claude Desktop, and for the others the terminal or editor the server runs in, else Terminal.

{"client": "claudeCode"}

{
  "ok": true,
  "message": "Registered with Claude Code (user scope).",
  "touched": "claude mcp add --scope user herald -- /Applications/Herald.app/Contents/MacOS/herald-mcp --agent claude-code",
  "alreadyExists": false,
  "agent": {"app": "agent.claude-code", "name": "Claude Code", "server": "--agent claude-code"},
  "issuer": {
    "app": "agent.claude-code",
    "manifestWritten": true,
    "templateCreated": true,
    "template": "agent",
    "templateUpgraded": false,
    "opens": "com.apple.Terminal",
    "icon": "/Users/you/Library/Application Support/Herald/icons/agent.claude-code.png",
    "iconMissing": false
  }
}

Without client the reply is the status:

{
  "server": "/Applications/Herald.app/Contents/MacOS/herald-mcp",
  "clients": [
    {"client": "claudeCode", "name": "Claude Code", "status": "Installed"},
    {"client": "codex", "name": "Codex", "status": "Not installed"},
    {"client": "claudeDesktop", "name": "Claude Desktop", "status": "Client not found"},
    {"client": "generic", "name": "Other", "status": "Not installed"}
  ],
  "genericConfig": "{\"mcpServers\": {\"herald\": {\"command\": \"/Applications/Herald.app/Contents/MacOS/herald-mcp\"}}}",
  "genericCommandLine": "/Applications/Herald.app/Contents/MacOS/herald-mcp",
  "cli": {"destination": "/usr/local/bin/herald", "installed": false}
}

HTTP route

• Without client: GET /v1/mcp
• With client: POST /v1/mcp/install

Side effects

Edits another application's configuration file and registers an app in Herald. An install that already exists is a 409 unless reinstall is true.

History#

History holds every notification Herald delivered. These tools list and search it, show an entry again as a banner, export it and delete from it.

list_history#

Lists the most recent notifications, newest first, with the template used, the button the user pressed and the field values the template bound. Call it to see what an app really sends. render_preview with source: "last" reads the same record.

Arguments

{"app": "example.bidbot", "limit": 2}

{
  "count": 1,
  "items": [
    {
      "id": "bid-42",
      "app": "example.bidbot",
      "title": "Bid won: Walnut desk",
      "template": "Bid won",
      "deliveredAt": "2026-10-04T10:12:03.000Z",
      "dismissedAt": "2026-10-04T10:12:40.000Z",
      "actionUsed": "open",
      "fields": {"item": "Walnut desk", "price": 240}
    }
  ]
}

Response fields

HTTP route

GET /v1/history

Side effects

None. Read-only.

history_search#

Searches History the way its search box does: every word must appear, in any case and with accents ignored, in the title, subtitle, body, app id or app name. Results are newest first. Call it to find a notification when you do not know its id.

Arguments

{"q": "walnut desk", "limit": 5}

{
  "query": "walnut desk",
  "count": 1,
  "items": [
    {
      "id": "bid-42",
      "app": "example.bidbot",
      "notification": {"app": "example.bidbot", "id": "bid-42", "title": "Bid won: Walnut desk", "template": "Bid won"},
      "deliveredAt": "2026-10-04T10:12:03.000Z",
      "dismissedAt": "2026-10-04T10:12:40.000Z",
      "actionUsed": "open"
    }
  ]
}

Each item is the full History record, trimmed here. Its fields are described in History.

HTTP route

GET /v1/history/search

Side effects

None. Read-only.

reshow_notification#

Shows a notification from History again as a new banner, with its sound and a fresh delivery time. It is the Re-show as Banner action of the History window. Call it when the user asks to see something again.

Arguments

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

{"ok": true, "id": "bid-42"}

id is the id of the new banner's notification.

HTTP route

POST /v1/history/reshow

Side effects

Shows a banner on the user's screen, plays its sound, and speaks it if the notification asked for speech. An id that is not in History is a 404.

delete_history#

Deletes one notification from History and closes its banner, clears one app's whole History, or clears everything. The arguments choose the scope:

• app and id delete one entry.
• app and all: true clear one app.
• all: true alone clears every app.

Arguments

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

{"ok": true}

HTTP route

• With app and id: DELETE /v1/history/item
• With all: DELETE /v1/history

Side effects

Destructive and not undoable. Removes the records and closes the banner of a single entry. Without id and without all: true the tool refuses to run. Ask the user first.

export_history#

Returns History as JSON, newest first, for one app or all. With path, Herald writes the file itself and returns only the count, which keeps a large History out of the conversation.

Arguments

{"app": "example.bidbot", "path": "~/Desktop/bidbot-history.json"}

{"count": 218, "path": "/Users/you/Desktop/bidbot-history.json", "bytes": 164210}

Without path the result has count and an items array that holds every record.

HTTP route

GET /v1/history/export

Side effects

Writes the file when path is given. Otherwise read-only. A path is a 400 in two cases:

• It does not end in .json.
• Its folder does not exist.

Related#

• MCP tool index and conventions: how the server reports errors and how an agent gets its own app id.
• MCP guide: install the server, connect a client and follow a worked session.
• Cloud relay tools: the tools for the cloud relay and its agent keys.
• Quiet hours: what the windows and the ad hoc silence do.
• Voice: the speech engines and the Kokoro install.
• Apps API, Settings API and History API: the routes behind these tools.