# SweetHive — How SweetHive works — and how to get the most out of it.

One markdown file with the whole guide — give it to ChatGPT, Claude or any assistant and ask how to use SweetHive and boost your activity.

Source: https://docs.sweethive.com/en/ (generated from the official SweetHive documentation).


---


# What SweetHive is

SweetHive is a workspace where every place of work has its own context and its own
scope. Instead of one big chat, information is organised into a **tree of contexts**,
and who sees what is decided by **groups** — not by long recipient lists.

## The three building blocks

- **Hive** — a workspace (a company, a project, a school, a museum, a family).
  Everything lives inside a hive.
- **Context** — a node inside a hive. Contexts form a tree: a context can contain
  sub-contexts, as deep as you need (e.g. *WEREA SRL → Administration → People →
  Payroll*).
- **Group** — a set of people. Groups are attached to contexts and gate visibility:
  you see a context only if one of your groups is **active** there.

## How visibility flows

Visibility flows **down** the tree: access to a context also covers the contexts
within it. A message you write in a context, addressed to a group, is visible to
that group in that context and everything below it — never wider.

> **The golden rule:** nothing is visible to someone unless a group they belong to is
> active on that context. This is what keeps mixed-trust audiences (staff, partners,
> clients) safely separated in one hive.

## What lives in a context

Beyond messages, each context aggregates its content into built-in apps — **Gallery**
(images and video), **Notes**, **Tasks**, **Planner** (events), **AnyDocs** (files and
links) — and can host custom apps installed by an admin. Everything obeys the same
visibility law.

## Where AI fits

SweetHive is built to work with AI assistants: you can connect your own agent (Claude,
an OpenClaw-class agent, or any MCP-capable assistant) with a scoped token that never
exceeds your own visibility, chat with it from inside SweetHive, and download this
whole guide as a single markdown file to teach any AI how SweetHive works — see
[Use SweetHive with AI](/en/use-sweethive-with-ai/).


---


# Quick start

## Sign in

Go to [sweethive.com](https://sweethive.com) and sign in with your email (or phone)
and password. SweetHive uses a single sign-on across the whole product family, so the
same account works on the web app, the mobile apps and the satellite products.

On **iOS and Android** the SweetHive app signs you in with the same credentials —
see [Mobile apps](/en/mobile/).

## The home page: My SweetHive

After signing in you land on **My SweetHive**, your personal dashboard:

- **Invitations** — hives you've been invited to; accept to join.
- **Hives** — every hive you belong to, with **Create new** to start your own.
- **Contexts** — quick access to the contexts you use.
- **Connectors** — external services (Gmail, Google Calendar, Google Drive, …)
  you've connected; see [Connectors](/en/connectors/).
- The **activity feed** — messages shared with your groups across all your hives.

## Finding your way around

- The **top bar** shows where you are (hive → context breadcrumb) and hosts
  **Write a message** and **search**.
- The **icon rail** on the left switches between the areas of the current hive:
  Contexts, Groups, People, Apps, Agents, Connectors, Notifications.
- The **message panel** is docked beside the content and always follows the context
  you're in: it shows the feed of the current context subtree.

## Your first steps

1. **Join or create a hive** — accept an invitation, or [create a hive](/en/create-a-hive/)
   with the guided wizard.
2. **Open a context** and read its dashboard: description, sub-contexts, active
   groups, apps, people.
3. **Write a message** — pick the context and the target groups, attach what you
   need, send. See [Messages](/en/messages/).
4. **Install the mobile app** — SweetHive is on the App Store and Google Play; see
   [Mobile apps](/en/mobile/).

## Languages

SweetHive speaks **English, Italiano, Français, Deutsch and Español**. Set your
language in *Settings → Profile → Preferences* — the app (and links to these docs)
follow it.


---


# Create a hive

Anyone can create a hive. The person who creates it becomes its first admin, with an
**Admin group** created automatically. Creation is a **guided wizard** that helps you
design a complete environment — contexts and groups — before anything is created.

Start from **My SweetHive → Hives → Create new**.

## Step 1 — Create

Choose what you want to build: **Company**, **Team**, **School** or **Project** on
SweetHive — or a **Museum** (AerariumChain) / **Academy** (WiredExperience) on the
satellite platforms. Your choice tunes the rest of the wizard.

## Step 2 — Plan

Pick who owns the hive:

- **Personal** — the hive lives on your personal account and its (free) plan.
- **Organisation** — the hive belongs to one of your organisations and runs on the
  organisation's plan. See [Settings](/en/settings/) for creating organisations and
  managing plans.

## Step 3 — Template

Pick a starting structure from the template catalog for your cluster, or start
**Blank**. Your purpose from step 1 preselects a matching template when there is one.
A template describes a ready-made environment: the context tree, the groups, and
which groups are active where.

## Step 4 — Environment

This is the heart of the wizard: a full **tree editor** where you shape the
environment before it exists. You can:

- **add, rename and delete contexts**, nested as deep as you need;
- **add, rename and delete groups**;
- **toggle which groups are active in each context** — deciding, node by node, who
  will see what.

Take your time here: a well-designed tree means visibility takes care of itself later.

## Step 5 — Details

Name the hive, add an optional description, and import a **cover image** — drag to
reposition, zoom with the slider; SweetHive resizes it for you. If the environment
you built is worth reusing, tick **“save this environment as a reusable template”**
and it joins your template catalog for next time.

**Create** applies the whole edited tree in one atomic operation — contexts, groups
and activations come to life together, and you land in the new hive as its admin.

> **Tip:** design groups around *audiences* (Staff, Suppliers, Clients, Board), not
> around org charts. You'll target messages at audiences every day.


---


# Contexts

Contexts organise a hive into a tree. Every context has its own dashboard, its own
feed, its own apps — and its own audience, decided by the groups active on it.

## Create a context

Only a hive admin can create contexts — the **Create new** button appears on the
context dashboard when you have admin rights there.

1. Open the context you want to create inside (or the hive root).
2. In the **Contexts inside** card, choose **Create new**.
3. Optionally import and crop a cover image.
4. Name it, add a description, then **Create**. The new context opens automatically.

A new context inherits the hive's **Admin** group, so admins can immediately manage
it. Activate member groups to open it to more people.

## The context dashboard

Opening a context shows:

- **Description & cover** — what this place is for.
- **Contexts inside** — the sub-contexts you can see.
- **Active groups** — who can see this context. Admins activate and deactivate
  groups here; see [Groups](/en/groups/).
- **Apps** — the built-in apps plus any custom apps installed here; see
  [Built-in apps](/en/built-in-apps/).
- **People** — who is effectively in this context, via its active groups.

The docked **message panel** beside the dashboard shows the feed for this context
*and everything below it* — messages posted deeper in the tree surface here too, and
you can filter them (see [Messages](/en/messages/)).

## Moving around

The **breadcrumb** in the top bar shows the path from the hive root to where you are;
**Go UP** climbs one level. The icon rail's **Contexts** item lists the current
context's subtree.

> **Design tip:** a context is a *place*, not a topic label. If a set of information
> has its own audience or its own lifecycle — a project, a department, a client — it
> deserves its own context.


---


# Groups

A group is a named set of people (e.g. *Admin*, *Founders*, *DevGroup*, *Suppliers*).
Groups belong to a hive and are attached to contexts to grant visibility. They are
the only thing that decides who sees what.

## Create a group

1. In a hive, open **Groups** from the icon rail.
2. Choose **Create**, give the group a name and description.
3. Add people to the group.

## Edit who is in a group

From the **Groups** page, open a group and choose **Edit users** — a two-column
editor shows who is *in* the group and who else is in the hive. Move people in and
out and **Save**; their visibility across every context where the group is active
updates immediately.

You can also work from the person's side: on the **People** page, use a person's
**⋮ → Change groups** to adjust all their memberships at once.

## Activate a group on a context

A context shows its **Active groups** on the dashboard. Activating a group on a
context is what makes that context (and everything below it) visible to the group's
members. Deactivate a group to remove that access instantly.

> Because visibility flows down, activate a group **as high in the tree as the access
> should reach — and no higher.**

## Everyday patterns

- **Admin group** — created automatically with the hive; active everywhere admins
  need to manage.
- **One group per audience** — Staff, Clients, Suppliers, Board. Messages are then
  targeted by audience with one chip.
- **Project circles** — a group per project team, active only on the project's
  context; the rest of the hive stays invisible to them.
- **Temporary access** — activate a group for the duration of an engagement, then
  deactivate it. No cleanup of individual permissions needed.


---


# People & invitations

Open **People** from the icon rail to see who is in the hive. From here you invite
new people and manage the ones already in.

## Invite someone

1. Choose **Invite people** and send an invitation by email.
2. The invitee sees it in **My SweetHive → Invitations** and accepts to join.
3. Once in, add them to the right [groups](/en/groups/) — until then they only see
   what the default membership allows.

## Manage a person

- **⋮ → Change groups** — adjust exactly what they can see, across all groups in one
  dialog.
- **Remove from hive** — revokes all their access at once.

## What a new member sees

Nothing, until a group they belong to is active on a context. This is by design:
you can safely invite a client or an external collaborator into the hive, and they
will only ever see the contexts you open to their group.

> **Tip:** invite first, then place. It's normal for a new member to see an almost
> empty hive until you've added them to their groups.


---


# Messages

Messages are always written **in a context** and addressed **to one or more groups** —
that is how SweetHive keeps scope honest. The message (and any attachment) is visible
to those groups in that context and below, never wider.

## Write and share

1. Open the context you want to post in.
2. Choose **Write a message** (top bar) or **Write** on the context dashboard.
3. Confirm the context and pick the target groups shown as chips.
4. Type your message. Add images, files, a link, a task, an event or a note from the
   attachment picker.
5. **Send.** Recipients see it in their activity stream; you can see who has seen it.

**Reply** to keep a thread together. A message can only be seen by people who share
one of its groups — there is no way to leak it wider.

## Content and attachments

- **Images and videos** also appear in the context's **Gallery** app.
- **Files and links** appear in **AnyDocs**. Click any content to open it
  full-screen, with the original message beside it.
- **Notes** are documents you can edit; they appear in the **Notes** app.
- **Tasks** and **events** land in **Tasks** and **Planner**.
- Content from your [connectors](/en/connectors/) — a Gmail message, a calendar
  event, a Drive file — can be shared into a context as a rich card.

## Search and filter the feed

The message panel follows the context you're in and shows the feed of its whole
subtree. To find things:

- **Search messages** from the top bar searches the text of the feed.
- **Filters** narrow the feed by:
  - **date range** — from/to;
  - **author** — only messages from selected people;
  - **content type** — messages with images, files, links, tasks, events or notes;
  - **sub-contexts** — include the whole subtree or only the current context.

Filters combine, and the active filter is always visible above the feed — clear it
with one click.

## Notifications

New messages for your groups raise in-app notifications (the **Notifications** page
collects them all) and **push notifications** on the mobile apps. Tapping a push
opens the exact message in its context.


---


# Apps in a context

Every context aggregates its content into **built-in apps**, and a hive admin can
install **custom apps** on top. Apps see data through the same scope law as
everything else: only what the person using them can see, never beyond it.

## The built-in apps

| App | What it collects |
|---|---|
| **Gallery** | every image and video posted in the context subtree |
| **Notes** | editable documents created from the composer |
| **Tasks** | tasks attached to messages, with status |
| **Planner** | events attached to messages, on a calendar |
| **AnyDocs** | every file and link, in one searchable place |

Open them from the **Apps** card on the context dashboard. Content opens
full-screen with the original message beside it, so nothing loses its context.

## Install a custom app (admins)

1. Open the context and find the **Apps** card on the dashboard.
2. Choose **Add app** (visible to admins).
3. Pick an app from the catalog and choose **Add**. It appears under *Installed apps*.
4. Open it from the Apps card — **embedded** apps render in place; **external** apps
   open in a new window (or the in-app browser on mobile).

Remove an app anytime from its menu — its access stops immediately.

## Professional app families

SweetHive also hosts production app families used by thousands of organisations —
for example the **Safety-BI** document and training registries (**DocBI**,
**Document BI**, **Records**, **DBI Global**), used for per-employee certificates,
context document management and employee records. If your organisation uses them,
they appear in the context's Apps card like any other app.

Want to build your own app? See the
[developer guide](/en/build-an-app/).


---


# Connectors

**Connectors** bring your external services into SweetHive so their content can be
shared into contexts with the same group-based visibility as everything else. Open
the hub from **My SweetHive → Connectors** or the **Connectors** item in the icon
rail.

## Available today

- **Gmail** — browse your inbox (read-only) and share an email into a context as a
  rich card.
- **Google Calendar** — browse your upcoming events (read-only) and share an event
  into a context.
- **Google Drive** — browse your files (read-only) and share a file card into a
  context. Drive shares the same Google connection as Gmail and Calendar.

More connectors — Outlook, Dropbox, OneDrive, Slack, Telegram, Trello, Asana, Jira,
GitHub — are on the roadmap and appear in the hub as **coming soon**.

## Connect Google

1. Open **Connectors → Gmail** (or Google Drive).
2. Choose **Connect** — a Google consent window opens; approve the read-only scopes.
3. Your mail / events / files appear in the connector page, read-only.

**Privacy by design:**

- Access is **read-only** — SweetHive never sends mail, creates events or modifies
  files on your behalf.
- Your Google tokens are stored **server-side only** and never reach the browser.
- Disconnect at any time from the connector page; access stops immediately.
- If a new capability is added to the Google connector (as Drive was), you'll simply
  be asked to reconnect once to grant the extra read scope.

## Share into a context

Every mail, event or file in a connector has a **Share** action:

1. Choose **Share** on the item.
2. Pick the **hive → context → groups** in the share dialog.
3. Send — the item lands in the context feed as a rich card (subject/sender for
   mail, title/time for events, name/type for files), visible only to the groups you
   targeted.

This is the bridge between your personal tools and your team's contexts: instead of
forwarding an email, you *place* it where it belongs.


---


# Settings

Open **Settings** from your avatar in the top bar. Settings has three main sections
today — Profile, Plan & billing, and Organizations — with more (orders, providers)
on the way.

## Profile

Everything about you:

- **Identity** — name, avatar (upload and crop), contact details, address, social
  links.
- **Preferences** — including your **language** (English, Italiano, Français,
  Deutsch, Español); the whole app follows it instantly.
- **Password** — change it with your current password.
- **Visibility** — each profile field carries its own visibility setting, so you
  decide what other members can see.

Each card saves independently — edit, then **Save** on that card.

## Plan & billing

Your personal account carries its own plan (free by default); each **organisation**
carries its own — normally paid — plan. Hives and resources are assigned to you *or*
to an organisation.

- **Current plan** — with live member and storage meters.
- **Available plans** — upgrade via secure Stripe checkout; billing can also run by
  bank transfer where enabled.
- **Payment methods** — saved cards, default card, remove.
- **Billing data** — invoice details (company name, VAT, address) used on receipts.
- **Payment history** — every payment with downloadable receipts and invoices.

## Organizations

An organisation is a legal/billing entity that can own hives and resources.

- **Create** an organisation (pick a unique username; it gets its own business
  cluster).
- **Profile & invoicing** — the organisation's identity and billing data.
- **Admins** — two admin roles: *global* admins manage everything, *finance* admins
  manage billing. Add or remove either.
- **Plan & quota** — the organisation's plan, member/storage usage, its own cards
  and payment history.

When you [create a hive](/en/create-a-hive/) on an **Organisation plan**, it's the
organisation that owns it — and its plan, members and storage that count.


---


# Mobile apps

SweetHive is available as a native app for **iOS** and **Android**, with the same
account and the same data as the web app.

## Download

- **iPhone / iPad** — search for **SweetHive** on the **App Store**.
- **Android** — search for **SweetHive** on **Google Play**.

Sign in with the same email (or phone) and password you use on
[sweethive.com](https://sweethive.com).

Everything works the same as on the web: contexts, groups, messages, apps and
connectors follow the same visibility rules everywhere.


---


# Use SweetHive with AI

SweetHive is designed to work *with* your AI assistant, whichever one you use. There
are two levels: teach an AI **about** SweetHive, and connect an AI **to** your
SweetHive.

## 1. Teach your AI about SweetHive (the .md guide)

This entire documentation is available as **one markdown file per language**:

**[Download the SweetHive guide (.md)](/downloads/sweethive-guide.en.md)**

Give that file to ChatGPT, Claude, Copilot or any assistant — attach it to a chat, a
project, or a custom assistant's knowledge — and it instantly knows how SweetHive
works: hives, contexts, groups, visibility, messages, connectors, settings, apps.

Then ask things like:

- *“Based on this guide, design a hive structure for my architecture studio with
  staff, external consultants and clients.”*
- *“What groups should I create so suppliers see logistics but never pricing?”*
- *“Draft the weekly update message for my DevGroup and tell me which context to
  post it in.”*
- *“How can my team use connectors to stop forwarding emails around?”*
- *“Audit this plan: who would see what if I activate ‘Clients’ on the project
  root?”*

Every page of this site is also available as raw markdown — add `.md` to any
article URL (e.g. `/en/messages.md`) — and AI crawlers can discover everything via
[`/llms.txt`](/llms.txt).

## 2. Connect an AI to your SweetHive

Beyond knowing *about* SweetHive, your assistant can securely read (and, if you
allow it, post into) your actual hives:

- [Connect an agent](/en/connect-an-agent/) — issue a scoped access token from
  SweetHive; works with Claude Desktop, Claude Code, OpenClaw-class agents and any
  MCP-capable assistant.
- [Chat with your agent](/en/chat-with-your-agent/) — talk to your connected agent
  from inside SweetHive.

Then your questions stop being hypothetical:

- *“What changed in Project A this week?”*
- *“Summarise the open tasks in Administration → People.”*
- *“Draft a status update for the DevGroup in Gigapixel.”*

## Boost your activity — a recipe

1. **Download the guide** above and give it to your assistant once.
2. **Design with it** — let it propose your context tree and groups; build the
   result with the [hive creation wizard](/en/create-a-hive/).
3. **Connect it** with a read-only token to your working contexts.
4. **Make it a habit** — morning catch-up (“what's new for me?”), weekly summaries,
   drafted updates you approve before posting.

Your AI knows the method; your SweetHive holds the facts — scoped, safe and always
under your control.


---


# SweetHive Agents Node

The **SweetHive Agents Node** is a desktop app for macOS and Windows that runs
your SweetHive agents **on your own computer**. Your agents answer with AI
models executed locally — prompts and content never leave your machine during
inference — and the app can also connect assistants like **Claude** or
**ChatGPT** to your SweetHive content through MCP.

> Using OpenClaw? It keeps working as an alternative runtime: it reads the same
> config bundles. The Agents Node simply makes everything one guided install.

## Install

1. Download the app:
   - [macOS (Apple Silicon)](https://downloads.sweethive.com/agents-node/mac/SweetHive-Agents-Node-arm64.dmg)
   - [macOS (Intel)](https://downloads.sweethive.com/agents-node/mac/SweetHive-Agents-Node-x64.dmg)
   - [Windows](https://downloads.sweethive.com/agents-node/win/SweetHive-Agents-Node-Setup.exe)
2. Open it, review and **accept the terms**.
3. **Sign in with your SweetHive account** (the same email and password as the
   web app).

The app keeps itself up to date automatically.

> **macOS note** — the current preview build is not yet notarized by Apple, so
> macOS may say the app "is damaged and can't be opened". It isn't: move the
> app to *Applications*, then run this once in Terminal and open it normally:
> `xattr -cr "/Applications/SweetHive Agents Node.app"`

## Add context agents

A *context agent* is a scoped connection to the hives and contexts you choose —
it can never see more than you can. You can add one from either side, and both
stay in sync:

- **From the app** — *Context agents → New context agent*: name it, pick the
  hives, choose a capability and expiry. It appears in SweetHive → **My agents**
  instantly.
- **From SweetHive web** — *My agents → Connect an agent*: create the token,
  download the config bundle and import it in the app (*Context agents → Import
  config bundle*).

Chat with your agents from **My agents** in SweetHive — replies are generated
on your computer. See [Chat with your agent](/en/chat-with-your-agent/).

## Local models

The Agents Node uses [Ollama](https://ollama.com) to run models locally. The
*Local models* tab detects it (with a download link if it is missing), lets you
pull models — **llama3.2** is a good start — and pick the default one. In
*Settings → Storage folders* you can choose where models, temporary files and
tool libraries are stored.

## Connect Claude or ChatGPT

The *Connect AI apps* tab turns the node into an MCP server for your assistant:

- **Claude Desktop / Claude Code** — copy the ready-made snippet into your
  Claude configuration; the assistant gets tools to list, search and read your
  scoped SweetHive content, plus any local tool servers you add.
- **HTTP endpoint (advanced)** — a local, secret-protected MCP endpoint for
  other clients.

## Privacy & control

- Tokens are scoped, expire, and can be revoked anytime from **My agents**.
- Secrets are stored encrypted with your operating system's key store.
- Model inference runs entirely on your machine.


---


# Connect an agent

You can connect a local AI assistant — Claude Desktop, Claude Code, an
OpenClaw-class agent, or any MCP-capable agent — to SweetHive. It connects with a
**scoped access token** that never exceeds what you can see, and that you can revoke
at any time.

## Create a connection

1. Open **My agents** from the home rail (or *Settings → Connected agents*).
2. Choose **Connect an agent**.
3. Name it, pick the **hives and contexts** it may access, choose a **capability**
   and an **expiry**.
4. Create the token. **Copy it (shown once)** or download the config bundle.
5. Register the connector with your local agent using the bundle — see
   [MCP connector setup](/en/mcp-connector/).

## Capabilities

| Capability | The agent can |
|---|---|
| **Read** (default) | read items and search in its scope |
| **Read + draft** | also prepare drafts for you to send |
| **Read + post** | also post messages — with your one-time confirmation per context |

## What stays safe

- The token's scope is **intersected with your live visibility on every request**.
  Leave a group, and the token loses that access at the same instant.
- **Read-only is the default.** Posting needs a Read + post token and a one-time
  confirmation per context.
- Anything a connected agent posts is attributed **“via you”** and obeys the same
  group targeting as any message.
- **Revoke** a token in one click from its card — access stops immediately.
- Every token's card shows when it was last used and how much it has read, and hive
  admins can allow, restrict to read-only, or block external agents on their hive
  entirely.

> Your agent runs **outside** SweetHive. Anything the token can read, treat as being
> on your machine — so scope it tightly: the contexts it needs, nothing more.

## See your agents at work

The **My agents** page lists every token with its scope, capability, expiry and a
live **online** indicator (the agent has checked in recently). From a context, you
can also see which of your agents currently cover it.


---


# Chat with your agent

Once an agent is [connected](/en/connect-an-agent/), you don't have to leave
SweetHive to use it: the **Chat with agent** app gives you a direct conversation
with it.

## Where to chat

- From **My agents** — open the chat on any of your connected agents.
- From a **context** where the agent's scope applies — the conversation is then
  scoped to that context, so “summarise what's new here” means *here*.

## How it works

- You write a message; your agent picks it up the next time it checks in (usually
  within seconds — the **online** dot tells you it's connected) and replies in the
  same thread.
- The agent replies **in its own voice, to you only** — a chat reply is not a post
  into the context feed.
- If the agent has a **Read + post** token, you can ask it to draft or post a real
  message into a context; posting always respects group targeting and is attributed
  *via you*.

## Good things to ask

- *“Catch me up on this context since yesterday.”*
- *“What tasks are still open in Project A?”*
- *“Draft a short update for the DevGroup about the release — I'll review it.”*
- *“Which contexts had the most activity this week?”*

> The chat is bounded by the agent's token: it can only discuss what its scope —
> intersected with **your** live visibility — allows it to see.


---


# Build an app

Developers can build custom apps for SweetHive — a small data view embedded in a
context, or a full product on its own URL. You register the app once, receive client
credentials, and build against the **App SDK**.

## Two kinds of app

| | **Embedded** | **External** |
|---|---|---|
| Where it runs | inside the SweetHive context UI (a sandboxed iframe) | its own URL / domain, launched from SweetHive |
| Good for | data views, forms, dashboards scoped to a context | full products with their own UI |

Both authenticate the same way: a **short-lived scoped token**, bounded server-side
by the install's scope **and** the viewer's live visibility. Your app never sees
more than the person using it can see, and access is revoked the instant they lose
it.

## Register and build

1. Open **Developer → Apps** from the user menu.
2. Choose **Register app**: name it, pick *Embedded* or *External*, set the URL,
   icon and capability.
3. Save the **client ID and secret** (shown once).
4. **Download the SDK dev guide (.md)** — the complete contract: the iframe
   handshake, auth, the scoped data API, testing and publishing. Drop it into your
   repo and build with your AI coding assistant.
   Also available here: [SWEETHIVE_APP_SDK.md](/downloads/SWEETHIVE_APP_SDK.md).
5. Set the app to **Active** so hive admins can install it from
   *Context → Apps → Add app*.

## How the standard works

- **Embedded apps** run in a sandboxed iframe and receive a short-lived scoped token
  via a `postMessage` handshake — never a cookie, so it also works in the mobile
  apps. Your app must allow SweetHive to frame it (a `frame-ancestors` CSP that
  includes the mobile app origins — the SDK guide gives the exact header).
- **External apps** open at their own URL with a signed launch; on mobile they open
  in the native in-app browser.
- Every data call is bounded server-side by the install scope intersected with the
  viewer's live visibility — same law, same audit as any SweetHive actor.

## Test and publish

Register your app with a localhost URL, install it into a test context, and the
handshake delivers a real scoped token against your data. When it's ready, set it
**Active** — and disable it anytime; installs stop immediately.


---


# MCP connector setup

SweetHive exposes its Agent Client API as an **MCP server**. Any MCP-capable agent —
Claude Desktop, Claude Code, Cowork, OpenClaw-class agents and others — connects with
one **scoped access token** you issue from SweetHive. One server, one token model,
every client.

First, [create a token](/en/connect-an-agent/) in
**My agents → Connect an agent** and download the config bundle (it contains your
`endpoint` and `token`).

## What your agent gets

| Tool | Does |
|---|---|
| `whoami` | the token's effective scope, capability and owner |
| `contexts` | the granted hive/context tree |
| `items` | recent items from a context and its subtree |
| `search` | search messages, notes and files across granted contexts |
| `post_message` | post into a context (*Read + post* tokens only; first post asks your confirmation) |
| `chat_pull` / `chat_reply` | the [in-SweetHive chat](/en/chat-with-your-agent/) with you |

## Configure your client

**Local connector (stdio)** — works today with Claude Desktop, Claude Code and any
stdio-MCP client. Install the packaged SweetHive connector, then add:

```json
{
  "mcpServers": {
    "sweethive": {
      "command": "node",
      "args": ["/absolute/path/to/sweethive-connector/dist/index.js"],
      "env": {
        "SWEETHIVE_ENDPOINT": "https://sweethive.com/server/web",
        "SWEETHIVE_TOKEN": "shv_..."
      }
    }
  }
}
```

**Remote (streamable HTTP)** — where the hosted MCP endpoint is enabled, point your
client at it with the token as a Bearer credential:

```json
{
  "mcpServers": {
    "sweethive": {
      "url": "https://sweethive.com/mcp",
      "headers": { "Authorization": "Bearer shv_..." }
    }
  }
}
```

Your agent can now answer things like *“what changed in Project A this week?”* or
*“draft a status update for the DevGroup.”*

## Notes

- **Capability** (Read / Read + draft / Read + post) is fixed on the token;
  read-only is the default.
- **Revocation and group changes take effect immediately** — there is no cached
  scope. A leaked config exposes a bounded, killable scope, never your account
  credentials.
- Content flowing in from an external agent is treated as untrusted: it cannot carry
  privileged mentions or invoke internal SweetHive agents, and it is rate-limited
  per token.