Connect Betterness One
Work on your Betterness One workspace from Claude or ChatGPT.
This reference describes the v2 default catalog of 49 tools. Availability depends on the deployed release; use tools/list to discover the tools currently available.
Connection details
| Endpoint | https://api.betterness.one/mcp |
| Transport | Stateless HTTP |
| Auth | Sign in with your Betterness account (OAuth), or a bko_* workspace key |
This is a different server from the members' one (https://api.betterness.ai/mcp). It reads and acts on a business workspace. Shared member health is available only through get_member_health, with members:health, the seat’s health permission and the member’s sharing consent. It does not grant unrestricted access to personal health records.
Connect
- Add
https://api.betterness.one/mcpto your app: Claude custom connector, ChatGPT custom MCP server, or in Claude Codeclaude mcp add --transport http betterness-one https://api.betterness.one/mcp, then/mcp→ Authenticate. - Sign in with the Betterness account you use for Betterness One.
- Accept the permissions on the consent screen.
The connection is yours, not one workspace's: every tool names the workspace it works in (workspaceId), and list_workspaces lists the ones you belong to. Each call checks, for that workspace, that you are still a member and what your seat may do there, as Betterness One does.
Permissions
| Permission | What it allows |
|---|---|
workspace:read | Read a workspace, its channels and its team |
instagram:read | Read Instagram insights: overview, audience, posts, reels, stories, hashtags |
instagram:connect | Start connecting an Instagram account (you finish it in Betterness One) |
insights:read | Read workspace-wide member numbers |
content:draft | Read the Library and the workspace's posts |
content:publish | Publish, schedule, change and cancel posts, after you confirm |
calendar:read | Read the Marketing Calendar |
calendar:write | Create, move and delete your own Calendar events, after you review a preview and confirm |
members:read | Read permitted member profiles, membership and activity |
members:health | Read health shared by a member, subject to consent and seat permissions |
space:read | Read the Space and its data request |
space:write | Edit Space content and settings; preview draft discard, data request and slug changes |
space:publish | Preview and confirm publishing or hiding a Space |
perks:read | Read perks, partners and analytics |
perks:write | Save drafts and preview and confirm live perk and partner actions |
clients:read | Optional coaching tools, only when enabled by the deployment. These five tools are outside the default catalog. |
Permissions also depend on your current workspace seat and enabled modules. A scope alone does not grant access.
Tools
| Tool | What it does | Permission |
|---|---|---|
list_workspaces | The workspaces you can work in, your role and what your seat opens in each | None: every connection can list them |
get_workspace | The business, its goal, team size and connected Instagram accounts | workspace:read |
get_instagram_insights | Instagram overview: profile, KPIs against the period before, trend, formats, best posts | instagram:read |
get_instagram_history | Posts, reels or stories in a date range with their metrics, or one post's detail | instagram:read |
get_instagram_audience | Followers over time, age and gender, places, active hours, follower and non-follower reach | instagram:read |
get_instagram_hashtags | Each hashtag's results against the account's own median, and the pairs used together | instagram:read |
connect_instagram | Whether Instagram is connected, and a Betterness One link to connect it | instagram:connect |
get_member_insights | Workspace-wide member numbers: sessions, bookings, check-ins, churn | insights:read |
list_media | Images and videos in the workspace Library | content:draft |
list_posts | Instagram posts made with Quick Create, and their status | content:draft |
get_post | One post in full, and whether it can still change | content:draft |
prepare_post | Preview an Instagram post. Changes nothing. | content:publish |
prepare_post_update | Preview editing, rescheduling or retrying a post. Changes nothing. | content:publish |
cancel_scheduled_post | Preview cancelling a scheduled post. Changes nothing. | content:publish |
confirm_post | Publish, change or cancel the post as you approved | content:publish |
get_calendar | Everything on the Marketing Calendar for a range | calendar:read |
create_calendar_event | Preview creating an event; confirm to save it | calendar:write |
update_calendar_event | Preview moving or editing your event | calendar:write |
delete_calendar_event | Preview deleting one of your events. Changes nothing. | calendar:write |
confirm_workspace_action | Run the approved Calendar, Space or Perks action | The previewing tool's |
list_members | Members visible to your seat in this workspace, including unlinked contacts. Returns memberId, name when permitted and connection state. Search and paginate; assigned-only seats see only their assigned members. | members:read |
get_member_profile | The workspace member record as Contacts shows it, with field-level privacy. No health data: use get_member_health for that. memberId comes from list_members. | members:read |
get_member_membership | The member’s plans, credit balances and pause policies in this workspace. Uses the same access and financial redaction as the app. Requires Contacts and Membership. memberId comes from list_members. | members:read |
get_member_activity | The member’s bookings, attendance and cancellations in this workspace, paginated. Uses the same access and financial redaction as the app. Requires Contacts and Membership. memberId comes from list_members. | members:read |
get_member_health | Health the member shares with this workspace: biomarkers, metrics/workouts, goals and labs. Requires members:health and the seat’s health permission. Returns sharing reasons and a wellness note; every read is audited. MemberId comes from list_members. For wellness support, not diagnosis. | members:health |
get_space | Read the saved Space editor, its public version, slug and check-in method. Does not initialize, repair or enrich a Space. Published Spaces may carry a separate unpublished draft. Requires Space access. | space:read |
get_space_data_sharing | Read the Space's live and draft data request and supported categories, without changing anything. This is the request ceiling, not any member's consent; members choose their own sharing. | space:read |
update_space_content | Save specified Space content fields using the editor's validation. On a published Space, edits stay in the unpublished draft. Does not publish, change the data request or slug. Use prepare_space_publish to preview publication. | space:write |
add_space_gallery_image | Import one image from the workspace Library or approved Bank source into the Space gallery. Uses the editor's ownership checks, image validation and gallery limit. On a published Space the image stays in the draft until approved publication. | space:write |
set_space_check_in_method | Change how members check in: front_desk, qr, or self. This operating setting takes effect immediately, independently of the content draft. Owner/admin only; also requires permission to edit Space. | space:write |
prepare_space_publish | Preview publishing the saved Space draft, with before/after content and effects. Writes no Space data. Show the preview and ask for explicit approval, then use confirm_workspace_action. If the Space changes meanwhile, prepare again. | space:publish |
prepare_space_unpublish | Preview hiding the public Space and clearing its unpublished draft. The join code stays reserved for republishing. Writes no Space data. Show the effects and ask for explicit approval, then use confirm_workspace_action. | space:publish |
prepare_space_discard_draft | Preview dropping the Space's saved unpublished changes and returning to the public version. Nothing is discarded yet. Show the preview, ask for explicit approval, then use confirm_workspace_action. | space:write |
prepare_space_data_request | Preview replacing the Space's data request. Narrowing removes member access immediately when confirmed; the editor's draft/publish rules still apply. Does not grant member consent. Show the effects, ask for explicit approval, then use confirm_workspace_action. | space:write |
prepare_space_slug | Preview claiming or changing the Space public slug. Owner/admin only. Checks availability but does not reserve it until confirmation. Show the address change and redirect effect, ask for explicit approval, then use confirm_workspace_action. | space:write |
list_perks | List own, shared or open partner perks, twenty per page. Pure read; does not provision a company. | perks:read |
get_perk | Read a perk visible to this workspace. Redemption secrets remain hidden for unaccepted partner perks. | perks:read |
search_perk_partners | Search active B1 workspaces eligible for perk invitations. | perks:read |
get_perk_partners | Read active and ended collaborators of a perk this workspace owns. | perks:read |
get_perk_analytics | Read the app analytics with its workspace timezone and privacy suppression. Maximum 366 days. | perks:read |
save_perk_draft | Create or edit a draft without publication or emails. Refuses live perks. Omitted fields and partners are preserved on edits. Supply perkId only to edit an existing draft. Use prepare_perk_publish afterwards. | perks:write |
duplicate_perk | Copy a perk owned by this workspace into a new draft with draft partner invitations. Sends no emails and does not publish. | perks:write |
prepare_perk_publish | Publish a saved draft with its current fields and invitations. Preview only, with email recipients and effects; makes no business change or email. Show the preview and obtain explicit approval, then call confirm_workspace_action. If state or recipients change, prepare again. | perks:write |
prepare_perk_update | Change a live perk; omitted fields and partners are preserved. Preview only, with email recipients and effects; makes no business change or email. Show the preview and obtain explicit approval, then call confirm_workspace_action. If state or recipients change, prepare again. | perks:write |
prepare_perk_delete | Disable a perk and remove it from every collaborating Space. Preview only, with email recipients and effects; makes no business change or email. Show the preview and obtain explicit approval, then call confirm_workspace_action. If state or recipients change, prepare again. | perks:write |
prepare_add_partner_perk | Host an eligible open partner perk for this Space members. Preview only, with email recipients and effects; makes no business change or email. Show the preview and obtain explicit approval, then call confirm_workspace_action. If state or recipients change, prepare again. | perks:write |
prepare_perk_invitation_response | Accept or decline a pending perk invitation. Preview only, with email recipients and effects; makes no business change or email. Show the preview and obtain explicit approval, then call confirm_workspace_action. If state or recipients change, prepare again. | perks:write |
prepare_leave_perk | Stop hosting a partner perk in this Space. Preview only, with email recipients and effects; makes no business change or email. Show the preview and obtain explicit approval, then call confirm_workspace_action. If state or recipients change, prepare again. | perks:write |
prepare_manage_perk_partner | Resend or cancel an invitation, or remove a collaborating partner. Preview only, with email recipients and effects; makes no business change or email. Show the preview and obtain explicit approval, then call confirm_workspace_action. If state or recipients change, prepare again. | perks:write |
Parameters and answers: All tools.
Publishing waits for you
prepare_post shows the caption, media, account and time, and changes nothing. The post is published or scheduled only after you approve it in the chat and the app calls confirm_post. Changing or cancelling a post works the same way. Posts use media from your workspace Library. See Publish an Instagram post.
Try it
- "Which of my Instagram posts did best last month, and why?"
- "Who follows me on Instagram, and when are they online?"
- "Which hashtags bring me the most reach?"
Workspace keys
For a script or an agent that runs without you, create a bko_* workspace key in Betterness One under Settings → Connections, and send it as Authorization: Bearer bko_.... A key acts only in the workspace it was created in: pass that workspaceId, and any other one is refused. Member bk_* keys do not work on this server, and bko_* keys do not work on the members' one.
Disconnect
In Betterness One, Settings → Connections lists every app connected by signing in, under Connected apps. See Connected apps.