Heard Friends

What Heard Friends does

Heard Friends MCP server gives cloud coding agents a communication path to the Heard app on macOS. The service handles short progress reports and messages between an agent and a person using Heard. Reports can describe four states: working, done, needs you, or failed. Heard reads these updates aloud and identifies the agent that sent them.

The reverse path lets a user send a message from Heard to an agent. An agent can retrieve those messages, treat them as instructions, and acknowledge them after picking them up. This is intended for agents that run away from the user's Mac, including hosted or cloud-based coding agents.

The README distinguishes the Friends component as a separate server for comparing coding-agent hours and friends. The tools described here instead cover Heard's cloud-agent reporting and inbox workflow.

How it works

Heard Friends MCP server is hosted at https://api.heard.dev/v1/mcp/agent, so there is no agent-side package to install. The agent connects to that MCP endpoint, and Heard relays reports to the signed-in macOS app. Reports are retained for seven days.

Users can hold the right Command key in Heard, speak the agent's name, and leave a message. The agent reads pending messages with heard_inbox, then uses heard_inbox_ack to mark them as received. Unread inbox messages expire after seven days and are deleted after 30 days. Disconnecting an agent revokes its access.

A practical instruction for an agent is to check the inbox at the start, between work steps, and before finishing, while calling heard_report as its status changes.

Setup and configuration

Install and sign in to the Heard app for macOS before connecting an agent. The app's Settings, Connections, and Cloud agents flow provides the recommended setup path.

OAuth connections are documented for Claude, ChatGPT, Grok Bot, and Codex. Add the hosted MCP URL as a custom connector, choose Connect or Authorize, sign in using the Heard email code, and approve access. Meta Muse, Devin, Manus, and GitHub Copilot coding agent use a token created in the Heard app. Configure that token as an Authorization: Bearer hga_... header and store it in the agent's secret field rather than in a chat.

Claude Code has a separate plugin installation path:

claude plugin marketplace add heardlabs/heard-mcp
claude plugin install heard@heard

After installation, run /mcp in Claude Code and sign in to Heard.

Tools and capabilities

• heard_report sends a short working, done, needs-you, or failed update for Heard to speak on the Mac.
• heard_inbox retrieves messages sent from Heard to the agent.
• heard_inbox_ack marks retrieved messages as picked up.

Hearing reports requires an active Heard trial or subscription. Voice replies require the Heard Power plan.

Limitations and notes

The agent needs access to the hosted endpoint and the user needs the Heard macOS app signed in. The service is a relay: reports are sent to api.heard.dev, then picked up by the Mac app. The provided material does not describe local operation, offline delivery, or additional MCP tools beyond the three listed above.

Heard Friends MCP server should therefore be selected for agent-to-user status and message exchange, not as a general-purpose task management or collaboration API.