MCP endpoint

The relay is also a remote MCP server, so an agent platform that speaks MCP can use it without writing HTTP calls. This page documents the one URL, POST /mcp, the methods it answers, and the four tools it offers. Read it if you are building an MCP client, or if you want to know exactly what the relay does with each request. To set up a connection from ChatGPT, Claude or Codex, follow Connect an agent instead.

The examples use $RELAY for the relay's origin and $KEY for the credential, as in Agent endpoints.

RELAY="https://herald-relay.example.workers.dev"
KEY="hrk_..."

Before you start#

• You hold an agent key (hrk_...) or a connector access token (hra_...), sent as Authorization: Bearer $KEY. An approved connector works until the user revokes it. Tokens never expire and are never rotated.
• Send a custom User-Agent header, as the examples do. See Relay API for why.

Concepts#

The transport is Streamable HTTP in its simplest form. Every request is a POST with one JSON-RPC 2.0 message, and every reply is one JSON response. There is no Server-Sent Events stream and no Mcp-Session-Id, so a request never depends on an earlier one.

One URL serves two kinds of client. The relay tells them apart by what the request carries.

A session-less client gets tools only. Reply events, which tell an agent the moment the user answers, are offered to stateless clients. The relay has no handshake for them, so every request states its own context.

A stateless request carries these parts. The headers repeat the method and the tool name so a proxy can route without parsing the body.

A stateless reply also carries resultType: "complete" and a _meta member naming the server, as the examples below show.

Tools are a thin layer over the agent endpoints. A tool call goes to the same checked HTTP route, so the limits, the validation and the errors are the endpoint's. A connector cannot send buttons, commands, scripts or any code: the relay accepts text and presentation fields only.

A method a client's kind does not have is answered with -32601.

The endpoint#

POST /mcp#

The one MCP endpoint. Use it as the server URL when you register Herald in an MCP client.

Request

The body is one JSON-RPC request. An array of requests is refused.

curl -s -X POST "$RELAY/mcp" \
  -H "Authorization: Bearer $KEY" \
  -H "Content-Type: application/json" \
  -H "User-Agent: Herald-Agent/1.0" \
  -d '{"jsonrpc":"2.0","id":1,"method":"ping"}'

{"jsonrpc": "2.0", "id": 1, "result": {}}

Errors

Notes

• A 401 carries WWW-Authenticate: Bearer resource_metadata="$RELAY/.well-known/oauth-protected-resource", so an OAuth client learns where to sign in. A token that was sent and rejected adds error="invalid_token". The 403 answers carry no such header.
• Every request needs a valid credential, even one the relay answers itself, such as ping. The check comes before the protocol checks, so a bad key with a wrong version header gets 401.
• A request with no id is a notification, such as notifications/initialized. The relay answers 202 with no body. A message with no method is a response from the client: the relay ignores it and answers 202.
• A tool call authenticates with its own request to the Mac's mailbox, so it costs one request. Any other method costs one GET /v1/status check. Both count toward the Mac's daily request budget, and only a 401 or 403 from that check stops the request.
• A GET on /mcp answers 405 with Allow: POST and the JSON-RPC error -32000. The relay offers no event stream.

initialize#

Starts a session-less handshake. The relay keeps no session: the reply only says what the server can do, and the client then sends tools/list and tools/call. The relay echoes the client's protocol version when it supports it and answers 2025-06-18 otherwise. A stateless client does not send initialize.

Request

curl -s -X POST "$RELAY/mcp" \
  -H "Authorization: Bearer $KEY" \
  -H "Content-Type: application/json" \
  -H "User-Agent: Herald-Agent/1.0" \
  -d '{"jsonrpc":"2.0","id":1,"method":"initialize","params":{"protocolVersion":"2025-06-18","capabilities":{},"clientInfo":{"name":"my-agent","version":"1.0.0"}}}'

Example response

The instructions text is shortened here.

{
  "jsonrpc": "2.0",
  "id": 1,
  "result": {
    "protocolVersion": "2025-06-18",
    "capabilities": {"tools": {"listChanged": false}},
    "serverInfo": {"name": "herald-relay", "title": "Herald cloud relay", "version": "1.1.0"},
    "instructions": "Send notifications to the user's Mac with send_notification; read receipts with get_receipt; wait for an answer with wait_for_reply."
  }
}

Errors

Notes

• The real instructions text is longer. It also describes the OAuth device flow and the reply event.
• The reply has no events capability. A client that asks for 2026-07-28 in initialize gets 2025-06-18 back and stays a session-less client.

tools/list#

Lists the four tools with their input schemas. It answers both kinds of client.

Request

No parameters.

curl -s -X POST "$RELAY/mcp" \
  -H "Authorization: Bearer $KEY" \
  -H "Content-Type: application/json" \
  -H "User-Agent: Herald-Agent/1.0" \
  -d '{"jsonrpc":"2.0","id":2,"method":"tools/list"}'

Example response

The inputSchema and annotations of each tool are shortened here.

{
  "jsonrpc": "2.0",
  "id": 2,
  "result": {
    "tools": [
      {
        "name": "send_notification",
        "title": "Send a notification to the user's Mac",
        "inputSchema": {"type": "object", "required": ["title"]},
        "annotations": {"readOnlyHint": false, "idempotentHint": true}
      },
      {
        "name": "get_receipt",
        "title": "Get delivery receipts",
        "inputSchema": {"type": "object", "required": ["notificationId"]},
        "annotations": {"readOnlyHint": true}
      },
      {
        "name": "wait_for_reply",
        "title": "Wait for the user's reply",
        "inputSchema": {"type": "object", "required": ["notificationId"]},
        "annotations": {"readOnlyHint": true}
      },
      {
        "name": "herald_status",
        "title": "Is the user's Mac reachable",
        "inputSchema": {"type": "object"},
        "annotations": {"readOnlyHint": true}
      }
    ]
  }
}

A stateless request, with the headers and _meta described above, gets the same list with two additions in result: "resultType": "complete" and a _meta member with the server's name, title and version.

curl -s -X POST "$RELAY/mcp" \
  -H "Authorization: Bearer $KEY" \
  -H "Content-Type: application/json" \
  -H "User-Agent: Herald-Agent/1.0" \
  -H "MCP-Protocol-Version: 2026-07-28" -H "Mcp-Method: tools/list" \
  -d '{"jsonrpc":"2.0","id":3,"method":"tools/list","params":{"_meta":{"io.modelcontextprotocol/protocolVersion":"2026-07-28","io.modelcontextprotocol/clientCapabilities":{}}}}'

Errors

tools/call#

Runs one tool. The params carry the tool's name and its arguments. The four tools are described under Tools.

Request

curl -s -X POST "$RELAY/mcp" \
  -H "Authorization: Bearer $KEY" \
  -H "Content-Type: application/json" \
  -H "User-Agent: Herald-Agent/1.0" \
  -d '{"jsonrpc":"2.0","id":4,"method":"tools/call","params":{"name":"herald_status","arguments":{}}}'

Example response

Every tool result has the same envelope. The JSON the endpoint returned is both the text of content and the structuredContent.

{
  "jsonrpc": "2.0",
  "id": 4,
  "result": {
    "content": [
      {
        "type": "text",
        "text": "{\"online\":true,\"lastSeenAt\":\"2026-10-02T13:14:19.111Z\",\"quietHours\":{\"active\":false}}"
      }
    ],
    "structuredContent": {
      "online": true,
      "lastSeenAt": "2026-10-02T13:14:19.111Z",
      "quietHours": {"active": false}
    }
  }
}

When the endpoint refuses the call, the result adds isError: true and holds the endpoint's error body. This is what send_notification returns for a forbidden field:

{
  "jsonrpc": "2.0",
  "id": 5,
  "result": {
    "content": [
      {
        "type": "text",
        "text": "{\"error\":\"forbidden_fields\",\"message\":\"rejected fields: command.\",\"fields\":[\"command\"]}"
      }
    ],
    "structuredContent": {
      "error": "forbidden_fields",
      "message": "rejected fields: command.",
      "fields": ["command"]
    },
    "isError": true
  }
}

The message is shortened here.

Errors

Notes

• A stateless result also carries resultType: "complete" and a _meta member naming the server.
• A tool call to send_notification, get_receipt, wait_for_reply or herald_status makes one request to the Mac's mailbox. A call that fails before it reaches the mailbox (an unknown tool, a missing id) costs one status check instead.

Tools#

Each tool forwards to the agent endpoint named in its block. The arguments and result fields are the endpoint's, so the endpoint's tables are the full reference. These blocks list what an MCP client sees.

send_notification#

Queues a notification for the user's Mac. Call it to tell the user something or to ask for an answer. It takes the same text and presentation fields as the endpoint and refuses buttons, commands, callbacks and scripts.

Arguments

{
  "title": "Build finished",
  "body": "All 214 tests passed.",
  "speak": true,
  "expectReply": true,
  "notificationId": "build-214"
}

Example result

The structuredContent is the notification's receipt. The content text holds the same JSON as a string and is omitted here.

{
  "structuredContent": {
    "duplicate": false,
    "notificationId": "build-214",
    "received": true,
    "receivedAt": "2026-10-02T13:00:04.000Z",
    "queued": true,
    "displayed": false,
    "spoken": false,
    "replied": false,
    "expectReply": true,
    "suppressed": false
  }
}

HTTP route

POST /v1/notify. The tool schema sets additionalProperties to false, and the relay refuses a field outside its whitelist whatever the client sends.

Side effects

Queues a notification, and Herald shows a banner on the Mac, speaks, or both. A repeated notificationId is not queued again.

get_receipt#

Reads the receipts for a notification you sent: received, displayed, spoken, replied, suppressed. Call it to learn whether the user saw a notification or whether quiet hours held it back.

Arguments

{"notificationId": "build-214"}

{
  "structuredContent": {
    "notificationId": "build-214",
    "received": true,
    "receivedAt": "2026-10-02T13:00:04.000Z",
    "queued": false,
    "displayed": true,
    "displayedAt": "2026-10-02T13:00:05.210Z",
    "spoken": false,
    "replied": false,
    "expectReply": true,
    "suppressed": false
  }
}

HTTP route

GET /v1/receipts/{notificationId}. The relay keeps an id for 24 hours.

Side effects

None. Read-only.

wait_for_reply#

Waits for the user's answer to a notification sent with expectReply. Call it after send_notification. When nothing came, it returns replied: false and timedOut: true, and you call it again to keep waiting.

Arguments

{"notificationId": "build-214", "timeoutSeconds": 30}

{
  "structuredContent": {
    "notificationId": "build-214",
    "replied": false,
    "timedOut": true,
    "suppressed": false
  }
}

A typed answer has text. A voice answer has transcript, made on the user's Mac and possibly imperfect, and an audioUrl that stays valid for 3600 seconds, with durationSeconds.

HTTP route

GET /v1/replies/{notificationId} with wait set to timeoutSeconds. The tool stops at 55 seconds, five below the endpoint's limit of 60, so the client's own timeout is not reached first.

Side effects

None. Read-only. A call that waits keeps the Mac's mailbox awake and counts against its daily poll seconds. To be told instead of waiting, subscribe to the reply event.

herald_status#

Says whether the user's Herald is online, when it was last seen, and whether quiet hours are on. Call it before you depend on a fast answer. Nothing else about the Mac is exposed.

Arguments

No arguments.

{}

{
  "structuredContent": {
    "online": true,
    "lastSeenAt": "2026-10-02T13:14:19.111Z",
    "quietHours": {"active": false}
  }
}

HTTP route

GET /v1/status.

Side effects

None. Read-only.

JSON-RPC errors#

A JSON-RPC error has code and message, and sometimes data. This is the reply to an unsupported protocol version:

{
  "jsonrpc": "2.0",
  "id": 1,
  "error": {
    "code": -32022,
    "message": "Unsupported protocol version",
    "data": {
      "supported": ["2026-07-28", "2025-06-18", "2025-03-26", "2024-11-05"],
      "requested": "1900-01-01"
    }
  }
}

Related#

• Agent endpoints: the HTTP routes behind the four tools.
• Events: server/discover, the reply event and webhook delivery.
• Relay API: credentials and the shared error format.
• Limits and errors: every limit and error code.
• Connect an agent: set up a connection step by step.