MCP · CLI · Skill · REST

Your agent can work the inbox too

Connect Claude, ChatGPT, Cursor or your own scripts to Hearl. They read what people say about your product on X, Reddit and Hacker News, triage it, draft replies and report back. Every change shows up in the timeline as you, via your agent.

Create an API key Read the agent skill

claude · hearl MCP

› Triage my Hearl inbox and assign today's posts.

⏺ hearl.get_summary⎿ needs action 14 · unassigned 6 · overdue 2

⏺ hearl.list_conversations({ view: "unassigned" })⎿ 6 conversations

⏺ hearl.get_conversation({ id: "c_9f2" })⎿ r/macapps · “Sync stopped after 2.3” · 23 replies

⏺ hearl.assign_conversation({ id: "c_9f2", owner: "maya@team.dev" })⎿ → Maya · in_progress

⏺ hearl.add_note({ id: "c_9f2", text: "Draft reply: …" })⎿ note added

What people ask their agents

Morning triage

The agent reads the unassigned queue, closes posts that aren't about your product, and proposes an owner and a due date for the rest. You approve, it applies.

“Triage my Hearl inbox and assign today's posts.”

Draft replies

For high-priority posts nobody answered, the agent reads the whole thread and drafts a reply in the post's language. Drafts go into an internal note for a teammate to post.

“Draft replies to the unanswered Reddit posts about the sync bug.”

Catch follow-ups

When a user writes back after your team replied, the conversation comes back to the inbox. Ask the agent what changed and who owns it.

“Which users followed up since yesterday, and who's on them?”

Weekly report

Top requests and complaints with links, what got resolved, what's overdue and who owns it, in a few hundred words for your team channel.

“Write this week's community feedback report from Hearl.”

From the terminal

Check the queue, claim a post and close it with an outcome without leaving your editor, or script it in CI with --json.

“hearl inbox --view mine”

Feed your own collector

Already scraping forums or Discord? Push those threads into the same inbox with the REST API and let Hearl's AI judge them.

“POST /api/v1/products/{slug}/threads”

Four ways in, one set of tools

MCP, the CLI and the REST API expose the same operations. Create a key under Agents & API in your workspace, read-only or read-write.

MCP server

Remote MCP over Streamable HTTP. Works in Claude Code, Cursor, Windsurf and any MCP client; Claude Desktop connects through the CLI's stdio bridge. Ten tools and three ready-made prompts.

claude mcp add --transport http hearl https://hearl.org/mcp --header "Authorization: Bearer $HEARL_TOKEN"

# Cursor, Windsurf, VS Code…
{
  "mcpServers": {
    "hearl": {
      "type": "http",
      "url": "https://hearl.org/mcp",
      "headers": {
        "Authorization": "Bearer ${HEARL_TOKEN}"
      }
    }
  }
}

CLI

npx hearl. Log in once, then summary, inbox, show, assign, done, due and note. Every command takes --json, and mcp install sets up your clients.

npx hearl login
npx hearl inbox --view unassigned
npx hearl assign <id> me
npx hearl mcp install --client claude-desktop

Agent skill

A SKILL.md that teaches any agent when to use Hearl, how to connect and the triage, reply-drafting and reporting workflows. Listed in the agent skills index.

https://hearl.org/.well-known/agent-skills/hearl/SKILL.md
https://hearl.org/.well-known/agent-skills/index.json

REST API

Plain HTTPS with a Bearer key and an OpenAPI 3.1 description. Use it from scripts, automations or your own collector.

curl "https://hearl.org/api/v1/conversations?view=todo&priority=high" \
  -H "Authorization: Bearer $HEARL_TOKEN"

# OpenAPI: https://hearl.org/api/v1/openapi.json

Tools

Read tools work with any key. Write tools need a read-write key.

`get_summary` hearl summary	Counts of conversations that need action, are unassigned, overdue or need a human check, plus new and closed this week, split by product and platform. Start here to see how the team is doing.	read
`list_conversations` hearl inbox --view unassigned --priority high	List posts and threads from X, Reddit, Hacker News and the other connected channels in a view of the shared inbox, most urgent first. Views: todo (needs action or in progress), unassigned, mine, assisting, overdue, review (the AI was unsure), done, all. Each item has postedAt for date filtering; own_post means the team's own post.	read
`get_conversation` hearl show <id>	Full post with its replies, the thread it answers, the AI judgment with probabilities, whether the team already replied, owner, collaborators, due date, outcome and the activity timeline. Use it before drafting a reply or deciding who should own it.	read
`list_products` hearl products	Products this workspace tracks, with how many conversations need action for each.	read
`list_members` hearl members	Workspace members with id, name, email and role. Use the email or id to assign conversations.	read
`assign_conversation` hearl assign <id> pat@example.com	Give a conversation one owner: a member id, their email, "me" (the person who created this token) or null to unassign. An unstarted conversation moves to in_progress.	write
`set_state` hearl done <id> --outcome "Replied with the 2.3.1 fix"	Move a conversation through the workflow: open, in_progress, waiting_user, waiting_internal or done. When marking done, record the outcome in a sentence (what was replied, fixed or decided).	write
`set_due_date` hearl due <id> 2026-11-12	Set when the conversation should be handled by (ISO date or datetime), or null to clear it. Overdue ones show up in the overdue view.	write
`add_note` hearl note <id> "Draft reply: ..."	Add a note to the conversation's timeline, visible only to the team inside Hearl (never posted publicly). Use @name to mention a member. Good for leaving a draft reply, a summary or a hand-off.	write
`mark_irrelevant` hearl irrelevant <id>	Close a conversation that isn't about the product and record it as filtering feedback. It leaves the inbox; it can be reopened with set_state. Confirm with the user before closing many.	write

Ready-made prompts

/triage_inbox
Go through unassigned conversations, close the irrelevant ones, and suggest an owner and due date for the rest.
/draft_replies
Draft public replies for high-priority posts nobody has answered, and leave each draft as a note for a teammate to post.
/weekly_report
Summarize what people said about the product this week and how the team handled it.

Agents work for your team, not on its behalf in public

Hearl never posts. Agents leave draft replies as internal notes; a person posts them.
Keys act as the member who created them, and the timeline shows the change as that person via the agent.
Read-only keys can look but can't change anything. Revoke any key at once from Agents & API.
Closing posts as irrelevant is marked as destructive, so clients ask before doing it.

أسئلة

Any client that supports MCP: Claude Code, Cursor, Windsurf, VS Code and others connect to the remote server directly; Claude Desktop uses the hearl CLI's stdio bridge. Agents without MCP can use the REST API or the CLI.

No. Hearl doesn't post anywhere. An agent can draft a reply and save it as an internal note so a teammate can review and post it.

No. API keys, the MCP server and the CLI work on every plan, including Free.

With a workspace API key that starts with hl_. Create it under Agents & API, choose read-only or read-write, and give it to the client. OAuth sign-in for MCP clients is planned.

Create an API key OpenAPI