Cloud relay

These MCP tools set up and manage the cloud relay from an agent running on the user's Mac: store the Cloudflare token, deploy the relay, pair this Mac, create and revoke the keys that cloud agents use, and check that everything works. They are for an agent that is asked "set up the cloud relay" or "give my cloud agent a key". Cloud agents themselves do not use these tools: they talk to the relay's own remote endpoint, described in Relay API. Each tool here wraps one route of the local relay API.

Concepts#

The cloud relay is a small Cloudflare Worker in the user's own Cloudflare account. A cloud agent cannot reach a Mac, so it puts notifications into a mailbox on the relay, and Herald, which keeps one outbound connection open to it, takes them out and shows them as banners. Nothing is opened on the Mac and there is no shared relay: every user deploys their own. Cloud relay explains the design and the free plan limits, and How the cloud relay works covers security.

The setup order. Set the relay up in this order. The setup state in relay_status (setup.state) tells you where you are; the states are listed in its reply, under Response fields.

1. relay_status: read the state. Skip the steps that are already done.
2. relay_token_url: get the page where the user creates a Cloudflare API token.
3. The user creates the token and gives it to you.
4. relay_set_cloudflare_token: store it.
5. relay_deploy: deploy the relay and pair this Mac. The state becomes online.
6. relay_test: send a test notification through the relay.
7. create_agent_key or relay_instructions: connect a cloud agent.

A custom domain is optional: relay_zones lists the zones, then relay_settings sets customDomain.

What needs the user. Some steps cannot be done by an agent, on purpose.

Secrets are never returned. The Cloudflare API token is stored on this Mac and no tool or route reads it back. The pairing secret is write-only: relay_settings reports only whether one is set. Agent keys are stored on the relay as a hash, so the one secret you ever see is the key in the reply to create_agent_key, once. Do not repeat a token or a key in messages or logs.

Show the whole capture

Settings > Cloud after setup. Everything on this tab is also reachable through the tools on this page.

Tools#

• Status and usage
  • relay_status
  • relay_usage
  • relay_test
• Set up the relay
  • relay_token_url
  • relay_set_cloudflare_token
  • relay_deploy
  • relay_pair
  • relay_unpair
  • relay_delete
• Advanced settings and custom domain
  • relay_settings
  • relay_zones
• Agent keys and connectors
  • create_agent_key
  • revoke_agent_key
  • list_connectors
  • relay_instructions
• Reply subscriptions
  • relay_events
  • relay_remove_event_subscription

Status and usage#

These tools report the state of the relay, what today's traffic has used, and whether a notification really goes through. None of them changes the setup.

relay_status#

Reports whether this Mac is paired with a relay and online, the relay and connector URLs, the agent keys, the Macs on the relay and the last 20 relay items with what happened to each. Call it first, and again after any change.

Arguments

No arguments.

{}

Example result

The reply is shortened: setup.steps and setup.usage are empty here.

{
  "paired": true,
  "state": "Online",
  "online": true,
  "relayURL": "https://herald-relay.example.workers.dev",
  "mcpURL": "https://herald-relay.example.workers.dev/mcp",
  "deviceId": "dev_0000",
  "lastSeenAt": "2026-10-04T10:15:00.000Z",
  "keys": [
    {
      "id": "a1b2c3d4",
      "name": "build-bot",
      "client": "claude",
      "scope": "notify",
      "kind": "static",
      "createdAt": "2026-10-01T09:00:00.000Z",
      "lastUsedAt": "2026-10-04T10:12:00.000Z"
    }
  ],
  "log": [
    {
      "id": "r_0000",
      "key": "build-bot",
      "title": "Build finished",
      "receivedAt": "2026-10-04T10:12:00.000Z",
      "displayed": true,
      "spoken": false,
      "replied": false,
      "duplicate": false
    }
  ],
  "setup": {
    "state": "online",
    "hasToken": true,
    "paired": true,
    "online": true,
    "relayURL": "https://herald-relay.example.workers.dev",
    "mcpURL": "https://herald-relay.example.workers.dev/mcp",
    "workersDevURL": "https://herald-relay.example.workers.dev",
    "customDomainRecommended": true,
    "bundledVersion": "1.0.0",
    "deployedVersion": "1.0.0",
    "updateAvailable": false,
    "steps": []
  },
  "devices": [
    {"id": "dev_0000", "name": "Studio Mac", "online": true, "lastSeenAt": "2026-10-04T10:15:00.000Z", "thisDevice": true, "removable": false}
  ]
}

Response fields

The fields of a key in keys:

The fields of a Mac in devices:

Each item of log has the key that sent it, its title, when it arrived, and these flags for what happened:

The setup object has these fields:

HTTP route

GET /v1/relay/status

Side effects

None. Read-only. It asks the relay for the current keys and devices when this Mac is paired.

relay_usage#

Reports what today's relay traffic has used of the Cloudflare free plan. Call it when notifications stop arriving, to see whether a daily limit was reached, or when the user asks how much of the plan is used.

Arguments

No arguments.

{}

{
  "day": "2026-10-04",
  "requests": 212,
  "wsMessages": 96,
  "notifications": 14,
  "pollSeconds": 0,
  "audioUploads": 0,
  "audioBytes": 0,
  "queued": 0,
  "storageBytes": 24576,
  "requestsPercent": 4,
  "budgetExhausted": false
}

Response fields

HTTP route

GET /v1/relay/usage

Side effects

None. Read-only. A Mac that is not paired gets a 409 error.

relay_test#

Checks the relay's /health, then sends a real test notification through the relay with a temporary key and waits for its receipt. Call it after relay_deploy, or when a cloud agent says it cannot reach the Mac. It also reports whether Cloudflare's Browser Integrity Check blocks Python's default User-Agent on the relay's hostname.

Arguments

No arguments.

{}

{
  "healthy": true,
  "paired": true,
  "online": true,
  "roundTrip": true,
  "receipt": "displayed",
  "detail": "A test notification went through the relay and was shown on this Mac. Browser Integrity Check is active on this hostname (expected on workers.dev): Python's default User-Agent (Python-urllib/3.x) is rejected with Error 1010. Agents must send a custom User-Agent such as Herald-Agent/1.0, or set up a custom domain.",
  "browserCheckActive": true
}

Response fields

HTTP route

POST /v1/relay/test

Side effects

Shows a banner titled Relay test on this Mac, unless the user's settings hold it back. It makes a temporary key, then removes the key, the History item and the log line. A relay that is not set up is a 409.

Set up the relay#

These tools take the relay from nothing to online and back. They are the tools behind Settings > Cloud > Enable relay, Unpair and Delete relay from Cloudflare.

The sheet that relay_set_cloudflare_token and relay_deploy do the work of.

relay_token_url#

Returns the Cloudflare page where the user creates the API token that Herald deploys the relay with, and the permissions the token needs. The page opens with every permission filled in and the token named Herald relay. Call it when relay_status shows token-needed, then tell the user to open the page, create the token and give it to you.

Arguments

No arguments.

{}

Example result

The url is shortened to two permissions and permissions to three entries.

{
  "url": "https://dash.cloudflare.com/profile/api-tokens?permissionGroupKeys=%5B%7B%22key%22%3A%22workers_scripts%22%2C%22type%22%3A%22edit%22%7D%5D&accountId=%2A&zoneId=all&name=Herald%20relay",
  "signUpURL": "https://dash.cloudflare.com/sign-up",
  "permissions": [
    {"key": "workers_scripts", "type": "edit", "title": "Workers Scripts: Edit", "why": "upload the relay, switch on its workers.dev address, set its variables"},
    {"key": "workers_r2", "type": "edit", "title": "Workers R2 Storage: Edit", "why": "create the bucket that holds voice replies and its 7-day expiry"},
    {"key": "account_settings", "type": "read", "title": "Account Settings: Read", "why": "find your account id"}
  ],
  "steps": [
    "Open the link (a free Cloudflare account is enough; sign up first if you have none).",
    "Cloudflare shows the token page with the permissions already filled in and the name \"Herald relay\". Press Continue to summary, then Create Token.",
    "Copy the token it shows once, and give it to Herald (Settings > Cloud > Enable relay, or relay_set_cloudflare_token)."
  ]
}

Response fields

HTTP route

GET /v1/relay/token-url

Side effects

None. Read-only. It does not open the page: the user does.

relay_set_cloudflare_token#

Stores the Cloudflare API token on this Mac. Herald uses it only to call api.cloudflare.com for the deploy, and no tool or route ever returns it. This is the one tool that carries a secret in its arguments: do not repeat the token in messages or logs.

Arguments

{"token": "cf_example_token_value_0000"}

{"stored": true}

HTTP route

POST /v1/relay/token

Side effects

Stores the token in Herald's secret store on this Mac and clears an earlier deploy error. Shows nothing. A value that does not look like a token is a 400.

relay_deploy#

Deploys the relay Worker to the user's Cloudflare account, waits until it answers, applies the custom domain when one is set in relay_settings, and pairs this Mac with it. Running it again upgrades the Worker in place with the same name, secrets and data, so it is safe to repeat. It takes up to about a minute.

Arguments

No arguments.

{}

{
  "deployed": true,
  "upgraded": false,
  "relayURL": "https://herald-relay.example.workers.dev",
  "paired": true,
  "online": true,
  "steps": [
    {"step": "verifyToken", "title": "Check the API token", "phase": "done", "detail": "Token is valid."},
    {"step": "upload", "title": "Upload the relay", "phase": "done", "detail": "Uploaded herald-relay."},
    {"step": "health", "title": "Wait for the relay to answer", "phase": "done", "detail": "The relay answered."}
  ],
  "workersDevURL": "https://herald-relay.example.workers.dev",
  "warnings": []
}

Response fields

HTTP route

POST /v1/relay/deploy

Side effects

Creates or updates a Worker and a storage bucket in the user's Cloudflare account, pairs this Mac and turns the relay on. It needs the token from relay_set_cloudflare_token. An upgrade keeps the signing secret, so the pairing and every key survive. When a deploy does change it, this Mac pairs again by itself, the step log shows Pair this Mac again, a warning says so, and agent keys and connectors must be created again. Another deploy already running is a 409.

relay_pair#

Pairs this Mac with the configured relay. relay_deploy does this itself, so call relay_pair only for a relay that already exists and was not deployed by Herald. Then:

1. Set its address with relay_settings: relayURL, and pairingSecret if the relay asks for one.
2. Call relay_pair.

Arguments

No arguments.

{}

{"paired": true, "code": "000000", "deviceId": "dev_0000"}

Response fields

HTTP route

POST /v1/relay/pair

Side effects

Changes state: this Mac becomes a device on the relay and starts a connection. It shows nothing. A relay address that is missing or invalid is an error.

relay_unpair#

Turns the relay off for this Mac. It revokes every agent key and connector and forgets the pairing. The Worker stays in the user's Cloudflare account until relay_delete removes it. Ask the user first, because every cloud agent loses access.

Arguments

No arguments.

{}

{"unpaired": true}

HTTP route

POST /v1/relay/unpair

Side effects

Destructive. Revokes all keys and connectors. If the relay cannot be reached to revoke them, the call fails and changes nothing.

relay_delete#

Deletes the relay Worker from the user's Cloudflare account with every mailbox, key and queued notification, and the voice-reply bucket when it is empty. Cloud agents lose access for good. Ask the user first: it only runs with confirm: true.

Arguments

{"confirm": true}

{"deleted": true, "note": "The Worker is deleted. The bucket herald-relay-audio still holds voice replies (Cloudflare only deletes empty buckets); delete it in the dashboard under R2."}

Response fields

HTTP route

POST /v1/relay/delete

Side effects

Destructive and not undoable. Unpairs this Mac first, deletes the Worker through the Cloudflare API, and forgets the pairing and relay secrets and the relay address. The Cloudflare token stays stored.

Advanced settings and custom domain#

The relay has settings: its limits, how long it keeps things, its name and an optional custom domain. These tools read and change them.

relay_settings#

Without arguments, returns every Advanced setting, whether a pairing secret is set, and the deployed state. With settings, validates and saves the ones you list. A change to a value that lives in the Worker, or to the custom domain, redeploys the relay and the reply says so with the step log. The Cloudflare token is never returned.

Arguments

customDomain takes an object with a zone and a hostname, or null to remove it. A custom domain puts the relay on a hostname in the user's own Cloudflare zone, switches Browser Integrity Check off for that hostname only, and points Herald at it. It is optional.

• It lets agents with default library User-Agents work, and gives the relay a stable address.
• Without it, an agent sends a custom User-Agent such as Herald-Agent/1.0.
• Pick the zone with relay_zones.
• It needs the token's Zone permissions from relay_token_url.
• Connectors already added to a cloud agent keep the old address and must be added again with the new one.

{"settings": {"maxQueue": 50}}

{
  "settings": {
    "accountId": "00000000000000000000000000000000",
    "workerName": "herald-relay",
    "subdomain": "example",
    "bucket": "herald-relay-audio",
    "audioRetentionDays": 7,
    "queueTTLHours": 24,
    "notificationsPerDay": 500,
    "maxQueue": 50,
    "bodyLimitBytes": 32768,
    "ratePerKey": 60,
    "maxDevices": 5,
    "deviceName": "",
    "pingSeconds": 300,
    "deployedHash": "0000000000000000",
    "deployedAt": "2026-10-04T09:00:00.000Z"
  },
  "pairingSecretSet": true,
  "errors": {},
  "redeployed": true,
  "steps": [
    {"step": "upload", "title": "Upload the relay", "phase": "done", "detail": "Uploaded herald-relay."}
  ],
  "warnings": []
}

Response fields

HTTP route

• To read: GET /v1/relay/settings
• To change: PUT /v1/relay/settings

Side effects

Without settings, none. With it, changes the relay's settings, and redeploys the Worker when a value that lives in it, or the custom domain, changed. An invalid value changes nothing and is a 400.

relay_zones#

Lists the zones (domains) in the user's Cloudflare account that the stored token can see, each with a suggested hostname. Call it to pick a zone for the customDomain setting of relay_settings.

Arguments

No arguments.

{}

{
  "zones": [
    {"id": "00000000000000000000000000000000", "name": "example.com", "status": "active", "suggestedHostname": "herald.example.com"}
  ]
}

Response fields

HTTP route

GET /v1/relay/zones

Side effects

None. Read-only. It calls the Cloudflare API with the stored token. A token without the Zone: Read permission fails with a clear message: the user then creates a new token from the page in relay_token_url.

Agent keys and connectors#

A cloud agent signs in to the relay in one of two ways:

• A key is a secret string you create here and paste into the agent.
• A connector is an agent that signs in with OAuth, such as ChatGPT, and the user approves on the Mac.

Both can send notifications and read their receipts and replies, and nothing else: they cannot run commands, set callbacks or change anything on this Mac. Their notifications arrive as the app cloud.<name>. Connect a cloud agent is the task guide.

create_agent_key#

Creates a notify-only key for a cloud agent, the same as Settings > Cloud > Agent keys. The reply holds the key once, because the relay keeps only a hash, and a connector block with the URL and Bearer header for Claude, Codex and any remote MCP client. The Mac must be paired.

Arguments

{"name": "build-bot", "client": "claude"}

Example result

connectorConfig is a multi-line text and is shortened here to its first lines.

{
  "id": "a1b2c3d4",
  "name": "build-bot",
  "client": "claude",
  "scope": "notify",
  "key": "hrk_...",
  "mcpURL": "https://herald-relay.example.workers.dev/mcp",
  "connectorConfig": "# Herald cloud relay: notifications only (send_notification, get_receipt, wait_for_reply, herald_status)\n# Key \"build-bot\". It is shown once. Anyone holding it can notify you, nothing else. Revoke it in Herald > Settings > Cloud.\n\nURL:            https://herald-relay.example.workers.dev/mcp\nAuthorization:  Bearer hrk_..."
}

Response fields

HTTP route

POST /v1/relay/keys

Side effects

Creates a key on the relay and registers the app cloud.<name> on this Mac. A Mac that is not paired is a 409. At most 20 keys can be active at once.

revoke_agent_key#

Revokes a key or a connector by its id. It stops working at once, and notifications it already queued are still delivered. Call it when a cloud agent should lose access, or to remove a connector from list_connectors.

Arguments

{"id": "a1b2c3d4"}

{"revoked": true, "id": "a1b2c3d4"}

HTTP route

DELETE /v1/relay/keys/{id}

Side effects

Destructive. The agent cannot send again, and its reply subscriptions end. A malformed id is a 400, and an unknown one is an error from the relay.

list_connectors#

Lists the connectors that signed in to the relay with OAuth, such as ChatGPT and clients that cannot send a custom key, and the requests still waiting for the user's approval. A connector appears as an agent key of kind oauth, so revoke_agent_key removes it. Approval happens only on the Mac, in a banner or with the 6-digit code in Settings > Cloud: no tool approves a request, and the approval code is never returned.

Arguments

No arguments.

{}

{
  "connectors": [
    {
      "id": "e5f6a7b8",
      "name": "chatgpt",
      "client": "other",
      "scope": "notify",
      "kind": "oauth",
      "displayName": "ChatGPT",
      "createdAt": "2026-10-02T14:00:00.000Z",
      "lastUsedAt": "2026-10-04T08:30:00.000Z"
    }
  ],
  "pending": [
    {
      "id": "req_0000",
      "clientName": "My agent",
      "redirectHost": "agent.example.com",
      "expiresAt": "2026-10-04T10:25:00.000Z",
      "userCode": "BDFG-HJKM"
    }
  ]
}

Response fields

HTTP route

GET /v1/relay/connectors

Side effects

None. Read-only.

relay_instructions#

Returns the exact text to give a cloud agent so that it connects: the connector URL, the steps and the User-Agent note. Call it after the relay is online, then show or paste the text for the user.

Arguments

The client values:

{"client": "claude"}

Example result

The text is shortened to its first lines.

{
  "client": "claude",
  "text": "Claude Code / Codex CLI (a static key)\n\nClaude Code:\nclaude mcp add --transport http herald https://herald-relay.example.workers.dev/mcp --header \"Authorization: Bearer <your key>\"\n\nAny other MCP client: URL https://herald-relay.example.workers.dev/mcp, header Authorization: Bearer <your key>"
}

Response fields

HTTP route

GET /v1/relay/instructions

Side effects

None. Read-only. Any other client value is a 400.

Reply subscriptions#

A cloud agent can ask the relay to call it when the user replies to one of its notifications, instead of polling. That request is a subscription. A connector's approval is all a subscription needs, so the user does nothing more. These tools show the live subscriptions and end one. Reply events explains how an agent subscribes.

relay_events#

Lists the live reply subscriptions: which connector is called, at which host, and how many events are waiting for it. It never returns a URL path or a secret.

Arguments

No arguments.

{}

{
  "restrictedTo": [],
  "subscriptions": [
    {
      "id": "sub_00000000000000000000",
      "event": "notification.reply",
      "host": "agent.example.com",
      "key": {"id": "e5f6a7b8", "name": "chatgpt", "displayName": "ChatGPT"},
      "createdAt": "2026-10-03T12:00:00.000Z",
      "pending": 0
    }
  ]
}

Response fields

HTTP route

GET /v1/relay/events

Side effects

None. Read-only. A Mac that is not paired gets a 409 error.

relay_remove_event_subscription#

Ends one reply subscription. The connector stays approved and can subscribe again. Call it when a cloud agent should stop being called, but keep its access. To remove the agent entirely, use revoke_agent_key, which ends all of its subscriptions.

Arguments

{"id": "sub_00000000000000000000"}

{"removed": true, "id": "sub_00000000000000000000"}

HTTP route

DELETE /v1/relay/events/subscriptions/{id}

Side effects

Destructive for that subscription only. A malformed id is a 400.

Related#

• Cloud relay: what the relay is and how to set it up by hand.
• Connect a cloud agent: the task guide for creating a key and pasting it into an agent.
• Reply events: how a cloud agent subscribes to replies.
• Relay API: the local routes behind these tools.
• Relay's remote API: the endpoints a cloud agent calls.
• Apps and settings tools: the tools for apps, approvals, settings and History.
• MCP tool index and conventions: how the server reports errors and what every tool shares.