# Balsio MCP Server

Connect Balsio to AI assistants and LLM workflows. The MCP server gives AI tools access to read and send messages, manage threads and channels, handle reactions, schedule messages, and organize your inbox — all through a standardized interface that works with Claude, ChatGPT, Codex, and other MCP clients.

## Authentication

MCP clients can authenticate with OAuth. For manual integration token setup, create an integration from the [Integrations page](https://balsio.com/app/integrations) and use the generated token.

## Client Setup

The Balsio MCP server is available at `https://balsio.com/api/v1/mcp`.

### Claude

**Team, Enterprise (claude.ai)**

Navigate to Settings > Connectors, search for Balsio and connect it.

**Free, Pro, Max**

From Claude settings > Connectors, add the [Balsio connector](https://claude.ai/directory/balsio).

### ChatGPT

Open the [Balsio app](https://chatgpt.com/plugins/plugin_asdk_app_6a69de26852081918a58fceabac1bd8d) and connect it.

### Claude Code

```bash
claude mcp add --transport http balsio https://balsio.com/api/v1/mcp
```

Run `/mcp` in a Claude Code session to authenticate.

### Codex

```bash
codex mcp add balsio --url https://balsio.com/api/v1/mcp
```

Run `codex mcp login balsio` to authenticate.

### Others

Clients that support remote MCP servers can connect with the URL `https://balsio.com/api/v1/mcp` and sign in with OAuth on first connect.

## Scope

MCP endpoint:
- `POST /api/v1/mcp`

Auth:
- `Authorization: Bearer sk_...` (integration API key)
- `Authorization: Bearer oat_...` (OAuth 2.0 access token)

## OAuth 2.0 (PKCE public client)

1. Discover OAuth metadata:
  - `GET /.well-known/oauth-authorization-server`
  - `GET /.well-known/oauth-protected-resource`
2. Redirect user to the authorization endpoint with:
  - `response_type=code`
  - `client_id`
  - `redirect_uri` (your fixed HTTPS callback URL)
  - `scope=mcp`
  - `code_challenge` and `code_challenge_method=S256`
  - `state` (recommended)
3. Receive authorization `code` on your callback URL.
4. Exchange code for token:
  - `POST /oauth/token`
  - form fields: `grant_type=authorization_code`, `client_id`, `code`, `redirect_uri`, `code_verifier`
5. Call MCP using:
  - `Authorization: Bearer oat_...`
  - `POST /api/v1/mcp`

Protocol:
- JSON-RPC `2.0`
- methods:
  - `initialize`
  - `notifications/poll`
  - `resources/list`
  - `resources/templates/list`
  - `resources/read`
  - `tools/list`
  - `tools/call`

## Notes On Scope
- MCP currently targets assistant-loop operations.
- It is not a full 1:1 mirror of every OpenAPI operation.
- Compatibility flat routes are intentionally not modeled as MCP tools.
- MCP always uses the current API version; `X-Minor-Version` is ignored.

## Confirmation

These tools take a required `confirmed` boolean and do nothing unless it is `true`:

- `messages_create`
- `threads_create`
- `scheduled_messages_send`
- `integrations_create`
- `integrations_update`
- `workspaces_create`
- `workspaces_users_add`

Without it they return a tool-result error (`type: bad_request`, `code: confirmation_required`) and change nothing. `confirmed: false` is treated the same as omitting it.

`confirmed` stands for the user having agreed to that exact call — those arguments, those recipients. Set it only after they have, and never on your own initiative.

## Tool Catalog

### Pagination
List tools (`threads_list`, `messages_list`) return, alongside `data`:
- `has_more`: `true` when more items exist beyond the returned page
- `next_cursor`: prefixed id to pass back as `before_id` to fetch the next page, or `null` on the last page
- `prev_cursor`: prefixed id of the first item in the page, or `null`

Page through results by passing the previous response's `next_cursor` as `before_id` on the next call. Default page size is `20` (max `100`).

### Utility
- `ping`
- `capabilities_thread_types`
  - returns one-on-one vs group behavior matrix, group-only tools, and thread `settings` key semantics (`thread_settings`)

### Threads
- `threads_list`
  - supports: `channel_id`, `parent_thread_id`, `limit`, `before_id`, `participant_ids`, `one_on_one_with`
  - pass a workspace `channel_id` to browse that workspace: it lists its threads including public ones you never joined, which is how you find threads to `threads_join`. Private threads appear only to their participants
  - pass `parent_thread_id` to list sub-threads of a given thread (mutually exclusive with `channel_id`)
  - `participant_ids` narrows the listed channel to threads that include every given user; your own id is neither needed nor implied, so it also finds workspace threads you never joined. In a thread that hides its participants, only the members you can see there match, and sub-threads never match
  - `one_on_one_with` narrows the listed channel to your one-on-one thread with that user; an archived one needs that channel's `channel_id`
  - neither filter combines with `parent_thread_id`: sub-threads don't expose their participants
  - defaults: `limit = 20`
- `threads_get`
  - also works with sub-thread IDs you haven't joined (see "Sub-thread access" below)
- `threads_create`
  - `message` is optional for regular threads, required for sub-threads
  - optional: `message.attachments` (see "Sending files" below)
  - supports sub-thread creation via `parent_thread_id` + `parent_message_id`
  - in a workspace, `recipient_emails: null` adds every workspace member and `[]` leaves you as the sole participant; outside one, `null` behaves like `[]`
  - `thread.workspace_visibility` is `public` (the default) or `private`, and only applies in a workspace; a private thread is reachable only by its participants. Change it afterwards with `threads_visibility_update`
  - `thread.settings` sets initial settings at creation (group threads only; sharing isn't supported here, and isn't supported over MCP at all — see `is_sharing_enabled` below; threads created in a workspace allow only `is_email_digests_disabled`, `disable_participant_messaging`, `disable_participant_sub_thread_messaging` and `is_participant_notifications_disabled`)
- `threads_update`
  - updates a group thread's `thread.name` / `thread.description`
  - requires the owner role in the thread
  - group threads only; one-on-one threads and sub-threads return a tool-result error (`isError`, `type: bad_request`)
- `threads_settings_update`
  - updates the thread `settings` object; only the provided keys are changed
  - `is_sharing_enabled` can't be set here — see the Thread Settings table
  - settings values must be literal booleans; other values (e.g. `"false"` as a string) return a tool-result error (`isError`, `type: bad_request`, `code: invalid_params`)
  - requires the owner role in the thread
  - group threads only; one-on-one threads and sub-threads return a tool-result error (`isError`, `type: bad_request`)
  - see `capabilities_thread_types` for the meaning of each settings key
- `threads_visibility_update`
  - workspace threads only; `workspace_visibility` is required, with no default
  - requires being a participant who is a thread admin or a workspace admin — a workspace admin outside the thread can't, since privatising it would revoke their own access
  - turning a thread private retracts it from every member who hadn't joined, messages included; turning it public announces it to the workspace
- `threads_delete`
  - deletes a group thread for everyone, messages included; one-on-one threads and sub-threads are rejected
  - requires the thread owner role, or workspace admin on a thread in that workspace
- `threads_share_get`
  - resolves a thread share link to what it leads to, without being a participant; returns the thread's name, member count and image
- `threads_join`
  - pass `share_key` to join from a thread's share link; resolve the link with `threads_share_get` first to see what it leads to
  - omit `share_key` to join a public workspace thread, or a sub-thread you can already read; an empty string is a malformed request rather than a member join
  - a private workspace thread can't be joined — the only way in is to be added
- `threads_leave`
  - a public workspace thread stays browsable and can be rejoined; leaving a private one, or leaving as an external participant, severs access entirely
- `threads_users_add`
- `threads_users_remove`
- `threads_users_roles_add`
- `threads_users_roles_remove`
- `threads_archive`
  - moves chats from Inbox or Snoozed to Done and cancels the scheduled wake-up
  - skipped chats return their current Inbox, Done and Snoozed placements
  - returned placement timestamps may be later than `archived_at` to supersede the current source placement
- `threads_snooze`
- `threads_move`
  - moves threads between your own channels; to move one *into* a workspace use `threads_workspace_move`
  - when `to_channel_id` is `null`, `from_channel_id` must also be `null`
- `threads_workspace_move`
  - moves a thread into a workspace, one-directional — there's no move back out
  - requires owning both the thread and the workspace
  - participants who aren't workspace members are dropped unless named in `external_emails`, which keeps them as external participants of that one thread; workspace members aren't added, they only gain browse access while the thread is public
  - `workspace_visibility` defaults to `public`; `private` moves the thread in without announcing it to anyone
- `threads_mark_read`

## Sub-thread access

Reading a sub-thread doesn't require joining it. You can read a sub-thread (`threads_get`, `messages_list`, `messages_get`, and `resources/read` for its thread and message URIs) when you can read its parent thread:
- you participate in the parent thread, or
- the parent thread is a public thread in a workspace channel you're a member of.

Sub-threads of a private workspace thread are readable only through participation. Reading doesn't join the sub-thread: it doesn't appear in your inbox and doesn't notify you. Join it, or reply in it, to follow it.

## Thread Type Rules
- `threads_create`
  - one recipient + no `thread.name` → one-on-one thread (DM)
  - your own email as single recipient + no `thread.name` → self-DM (one-on-one thread with yourself)
  - if a one-on-one thread already exists for the user pair, the existing thread is returned (with any supplied message posted into it) instead of creating a duplicate
  - multiple recipients or any `thread.name` → group thread
  - use `message.body` for initial message text
  - pass `parent_thread_id` + `parent_message_id` (instead of `recipient_emails`) to create a sub-thread
  - returns a tool-result error (`isError`, `type: conflict`) carrying the existing sub-thread `thread_id` if a sub-thread already exists for that message
- `threads_users_add/remove`
  - group threads only
  - one-on-one threads and sub-threads return a tool-result error (`isError`, `type: bad_request`, `code: not_group_thread`)
- `threads_users_roles_add/remove`
  - group threads only
  - current supported role: `owner`
  - one-on-one threads and sub-threads return a tool-result error (`isError`, `type: bad_request`, `code: not_group_thread`)
- `threads_update` / `threads_settings_update`
  - group threads only
  - one-on-one threads and sub-threads return a tool-result error (`isError`, `type: bad_request`, `code: not_group_thread`)
  - non-workspace threads require the thread owner role; threads in a workspace require the thread owner role or workspace management permission (`type: bad_request`, `code: permission_denied` otherwise)

### Messages
WhatsApp interoperability messages are not available through MCP. They are stored only on the user's mobile device (iPhone or Android, one device per user) and never reach Balsio servers, so no message tool can read them.

- `messages_list`
  - supports: `thread_id`, `limit`, `before_id`
  - defaults: `limit = 20`
  - also works with sub-thread IDs you haven't joined (see "Sub-thread access" below)
- `messages_get`
  - also works for messages in sub-threads you haven't joined
- `messages_create`
  - also works with sub-thread IDs
  - optional: `message.reply_to` (prefixed message id, e.g. `m_abc...`) for threaded replies
  - optional: `message.attachments` (see "Sending files" below)
  - to @-mention a user in `message.body`, use a markdown link with the `birdy://` scheme: `[@DisplayName](birdy://users/<user_id>)`
- `messages_update`
- `messages_patch`
- `messages_delete`
- `messages_reactions_create`
- `messages_reactions_delete`

### Scheduled Messages
- `scheduled_messages_list`
  - supports: `thread_id` (optional filter)
- `scheduled_messages_get`
  - required: `scheduled_message_id`
- `scheduled_messages_create`
  - required: `thread_id`, `scheduled_at`, `message`
  - `scheduled_at`: ISO 8601 datetime, 1 minute to 30 days in the future
  - `message.body`: message text (optional when attachments are provided)
  - optional: `message.attachments` (see "Sending files" below), `idempotency_key`
- `scheduled_messages_update`
  - required: `scheduled_message_id`
  - optional: `scheduled_at`, `message`
  - at least one of `scheduled_at` or `message` must be provided
  - `message` replaces the whole message, so resend every field to keep, such as `body`; omitting `message.attachments` keeps the existing attachments
- `scheduled_messages_delete`
  - required: `scheduled_message_id`
- `scheduled_messages_send`
  - required: `scheduled_message_id`
  - sends the scheduled message immediately

### Channels
Reading is universal — a channel is personal, a system bucket (`inbox`, `snoozed`, `archive`) or a workspace, and the same two tools return all three. Writing is not: these three act on personal channels only, and a workspace id returns `not_found` from them because they resolve a channel by its owner, which an ownerless workspace never matches. Workspaces have their own tools below.

- `channels_list`
- `channels_get`
- `channels_create`
- `channels_update`
- `channels_delete`

### Workspaces
A workspace is a channel with `role: "workspace"`. It carries three fields the other roles omit: `users` (the member roster with workspace `roles`), `share_link` (`null` when sharing is off) and `settings.is_sharing_enabled`. Those are workspace-level roles — a thread's own participants and their thread roles are a separate list, in the thread payload's `users`.

- `workspaces_create`
  - the caller becomes the workspace owner
  - `member_emails` is required — it adds members straight away and invites unknown addresses as new users, so it reaches people outside Balsio; pass `[]` to start alone
- `workspaces_update`
  - owner-only; renames the workspace or changes its `icon`
- `workspaces_settings_update`
  - owner-only; turns the join link on or off
  - turning it off clears the key, so a link already shared stops working; turning it back on mints a new one
- `workspaces_users_add`
  - owner-only; adds members by email, inviting unknown addresses as new users
  - new members get browse access to the workspace's public threads; nothing lands in their inbox and existing threads aren't backfilled
  - an added member who was an external participant on one of the workspace's threads becomes a normal participant there
- `workspaces_users_remove`
  - owner-only; you can't remove yourself — use `workspaces_leave`
  - drops them from every thread in the workspace at once, silently
- `workspaces_users_roles_add` / `workspaces_users_roles_remove`
  - owner-only; `owner` is the only role today
  - an owner manages the workspace and every thread in it, including ones they haven't joined — but not private threads they're not in
- `workspaces_share_get`
  - resolves a workspace join link to the workspace it leads to, without being a member; returns its name, member count and icon
- `workspaces_join`
  - joins a workspace from its join link; resolve the link with `workspaces_share_get` first to see which workspace it leads to
  - membership grants browse access to the workspace's public threads and adds nothing to your inbox — join the ones you want with `threads_join`
- `workspaces_leave`
  - drops every thread in the workspace from your inbox at once, silently: no thread posts a leave message

### Attachments
- `attachments_create`
  - required: `filename`, `size`, `content_type`
  - returns a signed `upload_url` — upload the file (max 10 MB) by POSTing multipart/form-data with a `file` field
  - upload the file as is: the server encrypts it, so other thread members can open it
- `attachments_get`
  - required: `attachment_id`; works for attachments in threads you can read, and for your own uploads not yet attached to a thread
  - returns the attachment with a signed `download_url` once `status` is `finished`, plus `preview_download_url` once its preview is ready; both expire after 1 hour
  - a preview image of at most 800 px and 256 KB is also returned inline as an `image` content block

#### Sending files
Upload the file with `attachments_create` as above. The upload happens over plain HTTP, outside MCP, so it needs a client that can make HTTP requests, such as Claude Code or Codex. Then pass the returned `id` in `message.attachments` to `messages_create`, `threads_create`, `scheduled_messages_create` or `scheduled_messages_update`, e.g. `"attachments": [{"id": "att_DT7QcSFMRe5mlz"}]`.

An `att_` id that doesn't exist, isn't yours, or is already attached elsewhere is skipped without an error, so check the `attachments` in the returned message.

### Users
- `users_list`
  - pass `user_ids` to fetch users by id, or `query` to search by a case-insensitive fragment of a name or email — not both
  - a search only matches users you have shared a thread or workspace with, mentioned, or looked up by email, never the wider user base; deleted and suspended users, and users who blocked you, are left out
  - a search returns at most 25 users; `has_more: true` means narrow the query
- `users_get`
- `users_me`
  - returns the user this integration acts as
  - the `initialize` response's `instructions` already name that user with their email and id, so clients that pass instructions to the model rarely need this call

### Integrations
- `integrations_list`
- `integrations_get`
- `integrations_create`
  - `type` defaults to `personal_token`; a bot caller can't create a `personal_token`
  - returns `token` once (and `webhook_signing_secret` when `webhook_url` is set); neither can be retrieved later
  - the returned `token` is independent of the MCP connection: disconnecting an OAuth MCP client does not revoke keys created through it, so revoke them separately via `integrations_revoke`
  - a bot also takes `supports` and `profile`, the two things below
  - `webhook_minor_version` (`YYYY-MM-DD-XX`) sets the API version webhook events are delivered at. A new integration is pinned to the current version when it's omitted; on update, omitting it keeps the stored version
- `integrations_update`
  - a `webhook_signing_secret` is returned only when setting a `webhook_url` on an integration that has none yet; an existing secret is never rotated
  - `supports` lists the thread types **other people** may add the bot to; a bot can always start threads of its own, so `[]` means only it can. Defaults to both, so send it only to narrow it
  - `profile` is the bot's card — `about_me`, `company`, `title`, `website` and a `links` map of `terms` and `privacy_policy`. Links must be `https`
- `integrations_revoke`
- `integrations_avatar_delete`
  - removes a bot integration's avatar

## Thread Settings

Every thread returned by `threads_list` and `threads_get` includes a `settings` object.

Reading rules:

- `is_sharing_enabled` is always present. **Every other key is omitted when false** — treat a missing key as `false`.
- All keys are booleans and default to `false`, except `participants_can_add_users`, which defaults to `true` on new non-workspace threads, and `is_participant_notifications_disabled`, which defaults to `true` on every new thread.
- The same reference is available at runtime under `thread_settings` in the `capabilities_thread_types` response.

| Key | Effect |
|---|---|
| `is_sharing_enabled` | `true` when the thread has an active public share link (see the thread's `share_link` field). Computed from the share key. Only group threads can enable sharing. **Read-only over MCP** — a share link exposes the conversation, including other members' messages, to anyone holding it, so turning it on or off is a person's action in the Balsio app. It is absent from the `threads_settings_update` schema, and passing it returns a tool-result error (`type: bad_request`, `code: sharing_unavailable`). |
| `is_email_digests_disabled` | Controls email digest cadence. `false` (default): thread activity is emailed in batched digests roughly every 5 minutes. `true`: those per-message digest emails stop; group-thread activity is instead summarized in a weekly email (one-on-one threads have no weekly digest, so they get no digest emails while this is enabled). Digest emails only go to members who were not reached by a push notification (typically members without the mobile app). Has **no effect on push notifications** — @mentions and regular messages still push immediately. |
| `is_participant_notifications_disabled` | When `true`, membership system messages in the thread ("X joined", "X left", "X added/removed Y") are suppressed. The "added you to this chat" push is sent either way. No system message produces a push or an email digest entry whatever this setting holds; notifications for regular user messages are **not** affected, and system messages that are not about membership — rename, description change, visibility flip, move into a workspace and group-thread creation — are still posted. Enabling `hide_participants` forces this setting to `true`, and it can't be set back to `false` while participants stay hidden (validation error). It stays `true` after `hide_participants` is turned off. `true` is the creation default for every new thread; pass `false` at creation to post membership messages. A `hide_participants: true` in the same request wins over a `false` sent alongside it. |
| `disable_participant_messaging` | When `true`, only thread owners can post messages in this thread; other members receive an error. On a public workspace thread the workspace's admins can post as well, since they can also change this setting. Does not restrict reading, reactions, editing, or deleting existing messages. The setting does not cascade to sub-threads — members can still reply there (use `disable_participant_sub_thread_messaging` to also restrict those). |
| `disable_participant_sub_thread_messaging` | When `true` on a parent thread, only its owners can create messages in its sub-threads (error code `sub_thread_messaging_disabled`). On a public workspace thread the workspace's admins can post as well. Non-owners can still read and join sub-threads. |
| `hide_participants` | Applies to regular top-level threads: when `true`, non-owner viewers see only thread owners in `users` and `user_ids`, while owners see the full participant list; `users_count` still reflects the true total. `read_receipts` is per-viewer the same way: owners get the full map, everyone else only their own entry — and when nothing remains, the key is omitted entirely (treat an absent map as "no change", not as "no receipts"). Sub-threads are governed by their parent thread's settings. Enabling it also sets `is_participant_notifications_disabled` to `true`. Sub-threads and workspace-channel threads always return empty `users`/`user_ids` and `users_count: 0` regardless of this setting. |
| `participants_can_add_users` | When `false`, only owners can add users to a group thread. When `true` (default for new non-workspace threads), any member can add users. Removing users and granting roles remain owner-only. Never applies to one-on-one threads or sub-threads. |

## Notifications
- `notifications/poll`
  - params:
    - `cursor` or `cursor_event_id` (optional, `e_...`)
    - `limit` (optional, `1..100`, default `20`)
  - returns:
    - `notifications`: list of MCP-style notification envelopes:
      - `method`: `notifications/events/<topic>`
      - `params.event_id`: prefixed event id (`e_...`)
      - `params.ids`: minimal ID payload extracted from event data (`thread_id`, `message_id`, etc.)
    - `next_cursor`: cursor to continue polling or `null`
  - topic examples:
    - `notifications/events/message.created`
    - `notifications/events/thread.updated`
    - `notifications/events/thread.moved`
    - `notifications/events/channel.created`
    - `notifications/events/scheduled_message.created`
    - `notifications/events/scheduled_message.updated`
    - `notifications/events/scheduled_message.deleted`

## Resources
- `resources/list`
  - returns currently visible JSON resources for the integration scope
- `resources/templates/list`
  - returns URI templates for supported typed resources
- `resources/read`
  - required: `uri`
  - input hardening:
    - `uri` max length: `512` bytes
  - supported URI schemes:
    - `balsio://threads/th_...`
    - `balsio://messages/m_...`
    - `balsio://channels/ch_...`
    - `balsio://users/u_...`
    - `balsio://events`
    - `balsio://events/latest`
    - `balsio://events/e_...` (events after cursor)
  - events resources:
    - max items per `resources/read` call: `100`
    - when a cursor is valid but no newer events exist, response returns `events: []` and `next_cursor: null`

## Error Mapping

`tools/call` errors use the two channels defined by the MCP spec.

**JSON-RPC errors** — the call doesn't conform to the tool contract, or the server failed. The client handles these; the model usually can't fix them by changing arguments.
- Unknown tool: `-32601` (`Method not found`)
- Invalid arguments / malformed ids: `-32602` (`Invalid params`), with actionable `error.data` (`field`, `expected`, `received`, `hint`)
- Execution/server faults: `-32000` (`Tool execution failed`)

**Tool-result errors** — the call is well-formed but the domain rejects it (invalid input data, business logic). Returned as a successful result with `isError: true` so the model sees and can self-correct:
- `content`: a text block with the human-readable message (and description, when present)
- `structuredContent.error`: the handler's error envelope — a machine-readable `type` (e.g. `bad_request`, `not_found`, `conflict`), a `message`, and, when the handler provides them, `description`, `code`, and any error-specific context

`resources/read` for a missing/invisible resource still returns JSON-RPC `-32004` (`Resource not found`) — the two-channel model applies to `tools/call`.

## LLM Usage Playbook
- Always call `tools/list` at session start and follow each tool `inputSchema.examples`.
- `messages_create`, `threads_create`, `scheduled_messages_send`, `integrations_create`, `integrations_update`, `workspaces_create` and `workspaces_users_add` do nothing unless `confirmed: true`. Set it only once the user has agreed to that exact call. See [Confirmation](#confirmation).
- For message text, always use `message.body` (not `message.text`).
- For thread creation:
  - one-on-one: one email in `recipient_emails`
    - do not set `thread_params.name` (setting a name creates a group thread)
  - group: two or more emails in `recipient_emails`
- Before membership/role changes, call `capabilities_thread_types`.
- Do not infer thread `settings` semantics from key names (`is_email_digests_disabled` changes email cadence only; `is_participant_notifications_disabled` suppresses membership system messages, not message notifications). Use the `thread_settings` section of `capabilities_thread_types` or the Thread Settings table above, and treat missing settings keys as `false`.
- Group-only tools:
  - `threads_users_add/remove`
  - `threads_users_roles_add/remove`
- For `threads_move`, when `to_channel_id` is `null`, set `from_channel_id` to `null`.
- For scheduled messages, use `message.body` for text. Body is optional when attachments are provided.
- `scheduled_at` must be ISO 8601, at least 1 minute and at most 30 days in the future.
- To retry after an error: on a JSON-RPC `-32602`, use `error.data.field` + `error.data.hint`; on a tool-result error (`isError: true`), read the `content` message and `structuredContent.error` for the corrected payload.
