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

# Heard Friends in your AI assistant

> **Note**
>
> Looking for cloud agents (Grok Bot, Muse, ChatGPT, Claude) that talk to you through Heard? That's a different server: see [Cloud agents](/cloud-agents).

Heard Friends is a small MCP server, so any assistant that supports MCP can read your monthly agent hours, show your board next to your friends, and send an invite when you ask. It's hosted by Heard. There's nothing to install or run.

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

## Get your key

#### Sign in at heard.dev/connect

Open [heard.dev/connect](https://heard.dev/connect) and sign in with your Heard account.

#### Click Get my key

The page shows a ready-to-paste line for each app, with your key already in it. Copy it now. It's only shown once.

#### Paste it into your assistant

Follow the steps for your app below, then restart the app.

One key per account. Getting a new key turns off the old one, and **Turn it off** on the same page turns it off for good.

## Add it to your app

#### Claude Code

```bash
claude mcp add --transport http heard https://api.heard.dev/v1/mcp/share \
  --header "Authorization: Bearer hgs_your_key"
```

Or install the plugin, which reads the key from `HEARD_KEY`:

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

#### Codex

Add this to `~/.codex/config.toml` and set `HEARD_KEY` in your shell:

```toml
[mcp_servers.heard]
url = "https://api.heard.dev/v1/mcp/share"
bearer_token_env_var = "HEARD_KEY"
```

#### Cursor

Add this to `~/.cursor/mcp.json`:

```json
{
  "mcpServers": {
    "heard": {
      "type": "http",
      "url": "https://api.heard.dev/v1/mcp/share",
      "headers": { "Authorization": "Bearer hgs_your_key" }
    }
  }
}
```

#### Claude.ai, ChatGPT, Grok, Muse

Add a custom connector (in ChatGPT it's a custom MCP server under developer mode). Use the URL above and the header `Authorization: Bearer hgs_your_key`. One-click sign-in for these apps is on the way, and it won't need a key.

## Things to ask

* "How many hours did my coding agents work this month?"
* "Where am I on my Heard board?"
* "Write a short post about my month with my invite link."
* "Invite [sam@example.com](mailto:sam@example.com) to Heard."

## What it can do

| Tool                  | What it does                                                                                             | Changes anything? |
| --------------------- | -------------------------------------------------------------------------------------------------------- | ----------------- |
| `heard_my_month`      | Your agent hours this month and your rank among friends                                                  | No                |
| `heard_share_card`    | A ready-to-paste line with your hours and invite link                                                    | No                |
| `heard_compare`       | You and your friends, ranked by agent hours                                                              | No                |
| `heard_invite_friend` | Emails one friend an invite. It shows you a preview first and only sends after you say yes. Max 5 a day. | Sends one email   |

## What your assistant sees

Your first name, your agent hours for the month, your rank on your board, and your invite link. Friends show up only if they chose to share their hours. Heard counts hours from the timestamps Claude Code and Codex save on your Mac. Your prompts and code never leave your Mac. See [Privacy and data](/privacy-and-data).

## If it doesn't work

* **"A Heard share key is required"**: the header is missing. Check that it reads `Authorization: Bearer hgs_...` with a space after Bearer.
* **"Unknown or revoked Heard share key"**: you got a newer key or turned this one off. Get a new one at [heard.dev/connect](https://heard.dev/connect).
* **0 hours**: hours come from the Heard app on your Mac. Open Heard once so it can count this month.

> 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.