# Heartbeat — how to use (mcp.ai)

Connect your Heartbeat account and use 7 tools for team collaboration straight from your AI agent. Connect with your own API key. Plug-and-play online communities. Heartbeat provides tools for creating and managing online communities with features for users, channels, events, messages, and more.

## Option A — via MCP (recommended)
Remote MCP endpoint (HTTP, streamable): `https://api.mcp.ai/p_heartbeat?ms=1787293440000`
Add it as a custom/remote MCP connector in your client (Claude, Cursor, VS Code…), then authenticate when prompted. Once connected, ask the agent to use the server's tools (e.g. `heartbeat_get_events`).

## Option B — via direct REST API
Base URL: `https://api.mcp.ai/api/heartbeat`
Auth: `Authorization: Bearer sk_live_…` — create a workspace API key at https://mcp.ai/settings/api-keys
Discover endpoints: `GET https://api.mcp.ai/api/heartbeat/_endpoints`

### Endpoints
- `POST https://api.mcp.ai/api/heartbeat/get/events` — Tool to retrieve event information from the community. Use when you need to list events with optional pagination support.
- `POST https://api.mcp.ai/api/heartbeat/list/channels` — Tool to retrieve a paginated list of channels in the community. Use when you need to list, browse, or search for channels in the Heartbeat community. Supports filtering by archived status, channel typ
  - body: { limit?: integer, archived?: string, channelType?: string, startingAfter?: string }
- `POST https://api.mcp.ai/api/heartbeat/list/groups` — Tool to retrieve a paginated list of access groups in the community. Use when you need to browse groups with optional filters for parent groups or user membership. Supports cursor-based pagination.
  - body: { limit?: integer, userId?: string, parentGroupId?: string, startingAfter?: string }
- `POST https://api.mcp.ai/api/heartbeat/list/users` — Tool to retrieve a paginated list of users in the Heartbeat community. Use when you need to get user information with optional filtering by creation date, group membership, or role.
  - body: { role?: string, limit?: integer, groupId?: string, createdAfter?: string, createdBefore?: string, startingAfter?: string }
- `POST https://api.mcp.ai/api/heartbeat/reactivate/user` — Tool to reactivate a previously deleted user by email to allow them to access the community again. Use when you need to restore access for a user who was previously removed.
  - body: { email: string }
- `POST https://api.mcp.ai/api/heartbeat/retrieve/group` — Tool to retrieve a single group by its ID. Use when you need to get detailed information about a specific group in the Heartbeat community.
  - body: { group_id: string }
- `POST https://api.mcp.ai/api/heartbeat/retrieve/user` — Tool to retrieve a single user by their ID. Use when you need to get detailed information about a specific user in the Heartbeat community.
  - body: { user_id: string }

## Example prompts
- "What can I do in Heartbeat?"
- "Show me a summary of my Heartbeat account"

## More
- Page: https://mcp.ai/heartbeat
- Agent spec (llms.txt): https://mcp.ai/heartbeat/llms.txt
- Postman collection: https://mcp.ai/heartbeat/postman.json