> For clean Markdown of any page, append .md to the page URL.
> For a complete documentation index, see https://docs.heard.dev/cloud-agents/llms.txt.
> For AI client integration (Claude Code, Cursor, etc.), connect to the MCP server at https://docs.heard.dev/_mcp/server.

# Cloud agents

Agents that run in the cloud can't reach your Mac, and Heard can't watch them from outside. So each cloud agent **reports to Heard** through one remote MCP server, and Heard on your Mac speaks those reports like any local session, named after the agent:

> "Scout finished: the CI fix is merged."
> "Muse needs you: which calendar should I use?"

Every agent uses the same server URL:

```
https://api.heard.dev/v1/mcp/agent
```

> **What you need**
>
> The Heard app for macOS, signed in. Hearing reports works on any plan with an active trial or subscription. Talking back by voice and asking Parrot about your cloud agents need [Heard Power](/heard-power).

## Connect an agent

Open **Settings → Connections → Cloud agents** and pick the agent. Each one shows numbered steps and the exact text to paste, each with a **Copy** button, plus **Copy all steps** for handing the recipe to someone else.

| Agent                                 | How it signs in                                                   |
| ------------------------------------- | ----------------------------------------------------------------- |
| Grok Bot                              | **Authorize**: sign in with your Heard email code, then **Allow** |
| ChatGPT                               | **Authorize**                                                     |
| Claude (claude.ai or the desktop app) | **Authorize**                                                     |
| Meta Muse                             | **Token** created in Heard                                        |
| Devin                                 | **Token**                                                         |
| GitHub Copilot coding agent           | **Token**                                                         |
| Manus                                 | **Token**                                                         |

For token agents, **Create token** shows the token once. Paste it into the agent's secret or header field, never into a chat.

#### Grok Bot

Copy the message from Settings, paste it into a chat with any Grok Bot, then click **Authorize**, sign in to Heard and click **Allow**. Ask the bot to report to Heard; you hear it within about 15 seconds.

#### Meta Muse

Create a token, copy the message from Settings and paste it into a chat with Muse. When Muse asks for the token, paste it into Muse's secret field. Muse runs a test and you hear it within about 15 seconds.

#### Everyone else

Follow the steps on the agent's card in Settings. Each one adds the server URL above as a custom MCP connector and adds one standing instruction so the agent checks its Heard inbox.

### More agents through the CLI

Cursor, Instinct, OpenAI Dots, Claude Code or Codex running on another machine, and any other MCP-capable agent connect the same way, from the CLI bundled with the app:

```bash
/Applications/Heard.app/Contents/MacOS/heard-board connect <agent>
```

`heard-board connections` lists what's connected and `heard-board disconnect <id>` removes one. Claude Code and Codex sessions on this Mac don't need a connector; Heard follows them already.

## Talk back

On Power, hold **right ⌘** and start with the agent's name:

> "Muse, summarize my inbox."
> "Scout, rerun CI."

Heard queues the message in that agent's **Heard inbox** and tells you when the agent picks it up. The agent reads its inbox with the `heard_inbox` tool at the start of a task, between steps and before it finishes, and confirms with `heard_inbox_ack`. Each connection in Settings shows its inbox, and you can cancel a message while it's still queued.

You can also go through Parrot: "Hey Parrot, tell Scout to rerun the tests." Parrot includes cloud agents when you ask it to catch you up or what needs you.

## Limits

* Heard hears what the agent chooses to report. Cloud agents have no lifecycle hooks, so coverage depends on the agent following its standing instruction.
* An agent only reads your message the next time it checks its inbox, so replies are not instant.

## Privacy

Cloud agents send their reports to Heard's relay at `api.heard.dev`, and the Heard app on your Mac picks them up while you're signed in. Reports are deleted after 7 days. Inbox messages expire after 7 days if the agent never picks them up, and are deleted after 30 days either way. Disconnecting an agent revokes its access. See [Privacy and data](/privacy-and-data).

> Heard is the voice layer for coding agents on macOS. Spoken progress from Claude Code and Codex, hands-free replies, and Heard Parrot codebase Q&A. Docs cover setup, listening modes, plans, and privacy.