Get started

Huddles for agents

Huddles speaks the Model Context Protocol. Connect your agent once and it can do what you would do here — start a huddle with a friend, put something on the calendar, tell you how your week went — and, if you are building something, add Huddles to your own app for you. Two different asks; this page keeps them apart.

Connect an agent#

Three things: the endpoint, a token, and the agent's config. The endpoint is https://huddles.space/mcp. The token comes from the developer hub, under Agents, where it is shown once and the config below is filled in with it. The config depends on the agent:

shell — Claude Code

claude mcp add --transport http huddles https://huddles.space/mcp --header "Authorization: Bearer hd_…"

json — Cursor, Windsurf, any mcp.json

{
  "mcpServers": {
    "huddles": { "url": "https://huddles.space/mcp", "headers": { "Authorization": "Bearer hd_…" } }
  }
}

Agents that read the web rather than speak MCP can start at /llms.txt, which says the same things in plain text. There is also a post on what this is like day to day.

Your token#

A token acts as you — your spaces, your friends, your calendar — and only through the tools on this page. Keep it in the agent's config and nowhere else, and revoke it in the hub the moment you stop trusting the machine it lives on. Every credential Huddles issues — app ids, secrets, tokens — is made in one place, by hand, so there is one place to look when something leaks.

Tokens are made in the developer hub, alongside app secrets. The hub opens by request, and the ask needs you signed in.

Using Huddles through your agent#

No setup beyond the token. You are already in a space; the agent acts there. Things people say:

"Start a huddle with Chad." The agent finds Chad among your friends and asks him in; the huddle opens where you are standing. You need the space open — if you do not, the agent gets the link to hand you, then tries again.
"What is on tonight?" The space's calendar: what is live, what is coming, whether you said yes.
"Create an event for tonight at 8 on the main space." The agent works out the time and puts it on the calendar with you as host; everyone in the space sees it.
"How much have I huddled this week?" Your own numbers: huddles, minutes, this week, events, friends, and who you huddle with most.
"Invite ana@example.com into my space." For a space you own: a link that admits her and nobody else.

Tool	What it does
`whoami`	Who the agent acts as, and the spaces you are already in.
`list_friends` → `start_huddle`	Your friends and whether they are here; a huddle with one of them, where you stand.
`list_events` / `create_event`	The calendar, and a new entry you host. Times as ISO 8601 with your offset — the agent resolves "tonight".
`my_stats`	Your own numbers.
`invite_to_space`	Admit people by email into a space you own.

Nothing here makes a space. Everyday use happens in the spaces you already have. A space is made only for the integration path below, where an app needs a room of its own to open into.

Integrating Huddles into your own app#

The other ask: you are building something and want Huddles in it — the bar and island on a course page, a huddle button in your messenger. Your agent can do the whole setup, up to the one gate a person holds. Paste this to it, with the brackets filled in:

prompt — give this to your agent

Add Huddles to my app using the huddles MCP server.
My app is called <NAME> and runs at <https://origin>. It is a <page with people on it | messenger with threads>.
Use whoami first. If I do not already own a space for it, create one. Then request developer access with a one-line note about the app, and try create_app. If access is pending, tell me and stop — I will say when I am approved. Once approved, create the app (preset: full unless I say otherwise), give me the install for a <page | huddle button> and the server-side token mint, and read the quickstart (or button) docs to wire it into my code. Never put the app secret in page code.

It finds out who it is acting as
whoami: your name, your spaces, and where your developer-hub request stands.
It makes a space for the app
create_space — the room your app will open into. You own it. If you already have one for this, it uses that instead.
It asks for developer access
request_developer_access. A person approves by email. The agent cannot hurry that, and it is told so: it will say "I have set up the space and asked for access — let me know when you are approved and I will continue", which is exactly right.
Once approved, it makes the app and wires it
create_app returns the app id, the secret (once — into your server's environment, never page code) and the install for a page or a messenger; install_snippet any time after; read_docs gives it the manual to work from.

Tool	What it does
`create_space`	A space the app opens into. Integration only.
`request_developer_access` / `developer_status`	Ask for the hub; see where the ask stands.
`create_app` / `list_apps`	Register the app (id, secret once, origins, shape); list what exists.
`install_snippet`	The page install, the huddle button, the server-side mint — as text to paste.
`read_docs`	Any page of this documentation, as text.

What it cannot do. Nothing about other people: no rosters, no other people's stats, no moderation, no operator controls. Nothing you could not do yourself with a mouse — every tool runs the same route the app does, under the same gates. And it cannot approve itself: the hub opens when a person says so.