Voice & MCP setup

These endpoints do what two Settings tabs do: install the Kokoro voice, and install Herald's MCP server into an AI client such as Claude Code. Use them when an installer script or an agent sets Herald up for the user. The examples use the $HERALD and $TOKEN variables from Connect.

What gets installed#

Kokoro is the natural-sounding speech engine. It is an optional download of about 340 MB that runs entirely on this Mac. Without it, Herald speaks with the macOS system voice. Installing takes a while, so the install endpoint only starts the work and you follow progress by reading the state.

The MCP server, herald-mcp, is a small program inside the Herald app that lets an AI agent send notifications and design templates. Installing it means adding an entry to the client's own configuration file. Herald keeps a backup of the file it edits. Installing also registers the agent as an app in Herald, so its notifications arrive with the agent's name and icon.

Settings > MCP. The Install button does what POST /v1/mcp/install does for that client.

Endpoints#

Voice#

GET /v1/voice#

Returns the current speech engine, whether Kokoro is installed, the progress of a running install, and the voices you can use. Poll it after starting an install.

Request

No parameters.

curl -s "$HERALD/v1/voice" -H "Authorization: Bearer $TOKEN"

{
  "engine": "kokoro",
  "kokoro": {
    "installed": true,
    "missing": [],
    "folder": "/Users/you/Library/Application Support/Herald/tts",
    "busy": false,
    "phase": {"state": "idle"},
    "existingInstallationAvailable": false,
    "log": []
  },
  "voices": [
    {"id": "af_heart", "name": "af_heart"},
    {"id": "af_bella", "name": "af_bella"},
    {"id": "bm_george", "name": "bm_george"}
  ],
  "lastError": null
}

Response fields

The phase object always has a state:

POST /v1/voice/install#

Starts the Kokoro download, cancels one that is running, or links an installation that already exists on this Mac. The reply comes back at once. Follow the progress with GET /v1/voice.

Request

curl -s -X POST "$HERALD/v1/voice/install" \
  -H "Authorization: Bearer $TOKEN" -H "Content-Type: application/json" \
  -d '{"action": "install"}'

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

Errors

Notes

• install downloads about 340 MB. This is the only time Herald's speech uses the network.
• useExisting links a complete Kokoro in ~/.claude/tts so that nothing is downloaded twice.
• Installing Kokoro does not switch the engine. Set voiceEngine to kokoro with PUT /v1/settings.

MCP server#

GET /v1/mcp#

Returns where the MCP server is, whether each known client has it installed, and the configuration to paste into a client Herald does not know.

Request

No parameters.

curl -s "$HERALD/v1/mcp" -H "Authorization: Bearer $TOKEN"

{
  "server": "/Applications/Herald.app/Contents/Helpers/herald-mcp",
  "clients": [
    {"client": "claudeCode", "name": "Claude Code", "status": "Installed"},
    {"client": "codex", "name": "Codex", "status": "Installed"},
    {"client": "claudeDesktop", "name": "Claude Desktop", "status": "Not installed"},
    {"client": "generic", "name": "Generic", "status": "Not installed"}
  ],
  "genericCommandLine": "claude mcp add --scope user herald -- /Applications/Herald.app/Contents/Helpers/herald-mcp",
  "genericConfig": "{\"mcpServers\": {\"herald\": {\"command\": \"/Applications/Herald.app/Contents/Helpers/herald-mcp\", \"args\": []}}}",
  "cli": {"destination": "/usr/local/bin/herald", "installed": true}
}

Response fields

POST /v1/mcp/install#

Installs the MCP server into one client, or installs the herald command-line tool. It does what the Install button for that client does in Settings > MCP.

Request

curl -s -X POST "$HERALD/v1/mcp/install" \
  -H "Authorization: Bearer $TOKEN" -H "Content-Type: application/json" \
  -d '{"client": "claudeCode", "opens": "com.apple.Terminal"}'

{
  "ok": true,
  "message": "Installed in Claude Code.",
  "touched": "/Users/you/.claude.json",
  "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": {"bundleId": "com.apple.Terminal"},
    "icon": "/Users/you/Library/Application Support/Herald/agent-icons/claude-code.png",
    "iconMissing": false
  }
}

Response fields

Errors

Notes

• The agent's app id is agent.claude-code, agent.codex or agent.claude-desktop. For generic it is agent. followed by a slug of name.
• Installing again keeps what the user changed since: the agent's template, its icon and its settings.
• cli installs the herald tool to /usr/local/bin/herald. Its reply has only ok, message and touched.
• A backup of the edited configuration file is kept beside it with the extension .bak.

Related#

• Make Herald speak: choose an engine and send a spoken notification.
• Connect an agent with MCP: the guided version of the MCP install.
• MCP reference: how agents become apps, and every tool.
• herald CLI: the command-line tool this API can install.