Overview

herald-mcp is Herald's MCP server. It lets an AI agent, such as Claude Code, Codex, Claude Desktop or any other MCP client, do on your Mac what you do with Herald's own windows: show a banner, speak a message, ask you a question and read your answer, and design how an app's banners look and what their buttons do. This page is the reference for the server as a whole: how it connects, what every tool shares, how an agent is identified, which resources it offers, and an index of all 70 tools. It is for people who build or configure an agent integration. To install the server in a client, see Connect an agent.

Concepts#

What the server is. herald-mcp is a small program that ships inside Herald.app, in Herald.app/Contents/Helpers/.

• An MCP client starts it as a child process and talks to it over standard input and output.
• It holds no data of its own. Every tool turns into one call to the HTTP API of the running Herald, and the reply comes back to the agent as the tool's result.
• Herald.app must therefore be running, except for component_schema and validate_template, which work without it.

What it never does. The server never presses a banner button and never runs an action. In practice:

• A command, script or Apple Shortcut that a template adds asks you for confirmation inside Herald the first time it would run, and again whenever it changes.
• The permissions that let an app run commands, scripts and Shortcuts, or call a remote host, cannot be granted through the server. The agent is the program that approval guards against, so only you can give it, in Settings > Apps.
• An agent can read those approvals and withdraw them. See Actions.

Transport. The server speaks JSON-RPC 2.0, one message per line, on standard input and output. It implements MCP protocol version 2025-06-18 and also accepts 2025-03-26 and 2024-11-05. It writes logs to standard error only, so standard output carries protocol messages and nothing else. It offers tools and resources. It offers no prompts.

Who it is for. It is for an agent that should tell you something while it works, and for an agent that you want to help design banners. Agents that run in the cloud, away from this Mac, reach Herald through the cloud relay instead; see Cloud.

How the server connects to Herald#

Herald writes its port and its bearer token into its support folder, ~/Library/Application Support/Herald/. The server reads the port and token files there, exactly as the herald command line tool does. Normally there is nothing to configure. These options exist for a second Herald, such as a debug build on another port, and for tests.

herald-mcp --version prints the version and herald-mcp --help prints the usage.

To try the server by hand, send it two lines. The first starts the session and the second calls a tool.

printf '%s\n' \
  '{"jsonrpc":"2.0","id":1,"method":"initialize","params":{"protocolVersion":"2025-06-18","capabilities":{},"clientInfo":{"name":"cli","version":"0"}}}' \
  '{"jsonrpc":"2.0","id":2,"method":"tools/call","params":{"name":"herald_status","arguments":{}}}' | herald-mcp

Conventions#

These rules hold for every tool.

Results are JSON text. A successful call returns one text block that holds a JSON document. Keys are sorted and short documents stay on one line. Two tools return a picture as well: render_preview and designer_snapshot return an image block (image/png) followed by a text block with the file path, the byte count and the pixel size.

Failures are results, not protocol errors. A tool that cannot do what was asked returns a result with isError: true. The text is a JSON document with ok: false, an error sentence that says what to do next, and extra fields where they help, such as errors with a path and a cell id. The agent can read it and try again.

{
  "ok": false,
  "error": "Missing required argument 'app'."
}

Only an unknown tool name is a JSON-RPC error, code -32602. A missing required argument is a tool error before any request reaches Herald.

Errors about Herald itself use fixed wording:

Arguments are forgiving. A number or boolean given as a string ("5", "true") is accepted. An object given as a JSON string is accepted. Unknown arguments are ignored by most tools. send_notification passes them through as notification fields.

Each tool carries hints. Every tool in tools/list has a title and the MCP annotations readOnlyHint, destructiveHint, idempotentHint and openWorldHint, so a client can ask you before it runs a destructive call.

Validation issues are objects in the errors and warnings lists of a failed or checked template. Each has these keys:

Agent identity#

An agent that sends notifications is an issuer like any other app: it has an app id, a name, an icon, a sound, a manifest and a default template. You design its banners in the Designer and set its sound and corner in Settings > Apps.

Installing a client from Settings > MCP (or with install_mcp or herald mcp install) does two things:

1. It writes the server entry into the client's configuration with --agent <slug>.
2. It registers the agent as an issuer, with the app id agent.<slug>.

--agent accepts the slug (claude-code) or the full id (agent.claude-code). A slug holds lower-case letters, digits and hyphens, at most 48 characters. A name that leaves nothing usable after slugging makes the server exit with a usage message.

With an agent identity set, app becomes optional on the tools that take it.

• The server fills in the agent's own app when a call leaves app out.
• tools/list shows app as optional and names the default in the description.
• An explicit app always wins.

These tools take the agent's own app when app is left out:

• send_notification
• send_test
• speak
• dismiss
• list_stacks
• get_replies
• wait_for_reply
• list_history

Every other tool is unchanged.

What the install registers. The registered manifest declares the fields an agent has to say. A field that is not sent collapses on the banner. Each field has a sample for previews.

The manifest declares three actions: open, reply and open-link. The default template is named agent. It shows these parts:

• The product icon.
• The title and body.
• A status badge that carries the agent's symbol.
• The close button.
• The project and the time.
• The button row.

The full format is in Manifests.

Every control on an agent banner does one thing, and none repeats another:

An agent that names no buttons gets Open, Reply and, with a link, Open link. The manifest's appBundleId or appPath sets what Open brings forward:

• Claude Desktop opens Claude.app.
• Claude Code, Codex and generic clients open the terminal or editor the install ran from, and Terminal when none is found.

You can change the target in Settings > MCP (Opens:, then Choose app), with the opens argument of install_mcp, or with update_app_settings.

Installing again is safe. Herald brings the manifest up to date, but it keeps your template once it exists, the app's sound, name and icon, and a default template you chose.

Cloud agents. An agent key created for the cloud relay also becomes an issuer, with the app id cloud.<key name>. Its banner offers Reply, Record and Open link, because there is nothing on this Mac to open. See Connect an agent.

Resources#

Resources are documents an agent can read without calling a tool. The URI parts after the scheme are percent-encoded, so a template named Bid won is Bid%20won.

resources/list always shows the guide, and shows the manifests and templates when Herald answers. resources/templates/list returns the two URI templates. The server does not support resource subscriptions.

Tool index#

There are 70 tools in five areas. Each tool is described once, in the page named in its row.

Notifications#

Show banners, speak, close banners and ask the user a question. All on one page.

Manifests and templates#

Read the fields an app sends, design templates, check them, add buttons, and manage assets. All on one page.

Apps, settings and History#

Register and configure apps, read and change settings, manage voice and the MCP install, and work with History. All on one page.

Cloud relay#

Set up and manage the cloud relay from this Mac. All on one page.

Related#

• Connect an agent to install the server in Claude Code, Codex or Claude Desktop and see a worked session.
• Agent quick start for the shortest path to a first notification.
• HTTP API for the calls behind each tool.
• Parity with the app for the list of what the app does and which tool does the same.
• Cloud for agents that run away from this Mac.