# Huddles

> Live huddles — voice, camera, whiteboards, documents, going live — in a space of your own at https://huddles.space, and embeddable in a platform's own page. For agents: an MCP server at the person's level.

## Connect (MCP)

Endpoint: POST https://huddles.space/mcp (Streamable HTTP, JSON-RPC 2.0, stateless; no server stream).
Auth: Authorization: Bearer hd_… — a personal access token the person makes in the developer hub (https://huddles.space/developers/hub → Agents). The hub opens by request (https://huddles.space/developers/access); approval is a person's, by email. That is the one step an agent cannot do for them.

Claude Code:   claude mcp add --transport http huddles https://huddles.space/mcp --header "Authorization: Bearer hd_…"
Cursor / any mcp.json:
  { "mcpServers": { "huddles": { "url": "https://huddles.space/mcp", "headers": { "Authorization": "Bearer hd_…" } } } }

## Two different asks — tell them apart first

### 1. Using Huddles, as the person
"Start a huddle with Chad." "What is on tonight?" "Create an event for 8pm on the main space." "How much have I huddled this week?"
- whoami — who you act as and the spaces they are already in. Never create a space for this.
- list_friends → start_huddle(spaceSlug, with) — the huddle opens where the person stands and the friend is asked in. If they do not have the space open, you get ok:false with the link; hand it to them and try again.
- list_events(spaceSlug) / create_event(spaceSlug, title, startsAt as ISO 8601 with offset, detail?, maxSeats?, region?, recurDays?) — resolve "tonight at 8" yourself before calling.
- my_stats — huddles, minutes, this week, events, friends, who they huddle with most.
- invite_to_space(spaceSlug, emails) — for a space they own.

### 2. Integrating Huddles into their own app
"Add Huddles to my app." "Put a huddle button in my messenger."
1. whoami — their spaces and developer status.
2. create_space — the app needs a space of its own to open into. Skip if they name a space they already own.
3. request_developer_access(note) — a person approves by email; you cannot hurry it.
4. create_app — returns { ok:false, reason:"access_pending" } until approved. Tell the user: "I have set up the space and asked for access; let me know when you are approved and I will create the app and wire the install." Then stop.
5. Once approved: create_app(spaceSlug, name, origins, preset?) → the app id, the secret (once; it goes in their server's environment, never page code), the install snippets. read_docs("quickstart") for a page, read_docs("button") for a call button in a messenger, read_docs("auth") for the token their server mints.

### Tools
- whoami: Who the token acts as: name, whether the account is verified, developer-hub status (none / pending / approved / owner), and the spaces they are in with their role. Call this first.
- request_developer_access: Ask for the developer hub (app ids and secrets). A person approves by email; the agent cannot hurry it. Returns told:true when the operator was emailed, or the time an earlier ask has been waiting since. Then tell your user: "Let me know when you are approved and I will continue."
- developer_status: Where the developer-hub request stands: none, pending, approved, denied, or owner.
- read_docs: Read a page of the developer documentation as text. Pages: overview, quickstart, access, agents, island, button, shapes, walk-ins, courses, messengers, communities, auth, widget, reference, security, limits, troubleshooting. Start with "quickstart" for the page integration and "button" for a call button in a messenger.
- list_spaces: The spaces the person is in, with slug, name and role (admin = owner). Apps and events live in a space.
- create_space: Make a new space the person owns — only when integrating Huddles into their own app, which needs a space of its own to open into. Everyday use (huddles, events, friends) happens in the spaces they already have; do not make one for that. Returns the slug (never changes), the join code the link carries, and the link. Free accounts may run one space.
- list_apps: The embed apps on spaces the person owns: id, name, origins, shape. Never a secret — a secret is shown once, by create_app.
- create_app: Register an embed app on a space the person owns: the public id the widget uses, the secret that signs tokens (returned once — hand it to the user to put in their server's environment, never in page code), the origins allowed to frame it, and a shape (full / call / chat — all free for now). Needs developer-hub access: before approval this returns ok:false with reason access_pending, and the right move is to tell the user you will continue once approved.
- install_snippet: The exact code to put on a page: the page integration (bar + island), the huddle button for a messenger, and the server-side token mint. Pure text; call it any time.
- my_stats: The person's own numbers: huddles, minutes talking, this week, events hosted and going to, friends, and who they huddle with most in a space.
- list_friends: The person's friends, with whether each is here right now, plus pending requests each way. Friends are mutual; a huddle can only be started with a friend.
- list_events: Upcoming and live events in a space: title, when (epoch ms and ISO), who hosts, whether the person is going. Never who else is.
- create_event: Put an event in a space's calendar. The person hosts it; everyone in the space sees it; those who say yes get a reminder. Resolve relative times ("tonight at 8") to an ISO 8601 time with the person's offset before calling.
- start_huddle: Start a huddle with a friend, by name. The huddle opens where the person is standing in the space and the friend is asked in (a notice if they are here, an email either way). The person must have Huddles open in that space — if not, this returns ok:false with the link to open; tell the user to open it and ask again.
- invite_to_space: Invite people into a space the person owns, by email. Each gets a link that admits them and nobody else. Returns the links too, for pasting into a message.

## Documentation
- https://huddles.space/developers — overview
- https://huddles.space/developers/agents — this, for people: the two paths, where the token comes from, a prompt to give an agent
- https://huddles.space/developers/quickstart — two lines on a page
- https://huddles.space/developers/button — the huddle button for messengers
- https://huddles.space/developers/shapes — full / call / chat and the keys under them
- https://huddles.space/developers/walk-ins — visitors with no backend
- https://huddles.space/developers/auth — the token the platform's server mints
- https://huddles.space/developers/widget — embed.js API
- https://huddles.space/developers/reference — HTTP reference
- https://huddles.space/developers/security — what travels where
- https://huddles.space/developers/limits — free limits and Premium
- https://huddles.space/developers/troubleshooting — why media, mounting or the token fail, and Huddles.diagnose()
- https://huddles.space/blog/huddles-with-your-agent — the post