Connect an external assistant
Authorise an MCP assistant, restrict its permissions, and revoke its access.
The MCP server allows a compatible assistant to view information accessible to your BeAI account and, if you authorise it, to modify its configuration. It is distinct from the skill that allows a bot to query an external MCP server.
Connection
- Open your avatar, then MCP access.
- Copy the displayed address, ending in
/mcp, into your assistant’s remote MCP server configuration. Choose the Streamable HTTP transport. - Start the OAuth connection, log in to BeAI, and verify the client name and displayed account.
- Authorise read-only access. If the client requests control, a separate checkbox allows granting it; it is unticked by default.
Your assistant must support OAuth with PKCE S256 and public client registration. Redirect URIs use HTTPS; desktop clients may use HTTP on their local loopback. The exact redirect URI must be registered. A standard REST API key is not an MCP token and does not bypass this consent.
View (beai:read) allows reading permitted information.
Management (beai:read beai:write) additionally allows the modifications described
below, always within the limits of your role and your organisations.
A role removed in BeAI is also removed for subsequent requests from
the assistant. The assistant can read instructions, documents, and transcripts:
only authorise an assistant you trust.
Read-only catalogue
| Operation | Tools |
|---|---|
| Account and permissions | beai_get_account_context |
| Organisations | beai_list_organisations, beai_get_organisation |
| Bots and targeted sections | beai_list_bots, beai_get_bot_section, beai_get_bot_skill |
| Bot templates distinct from standard bots | beai_list_bot_templates, beai_get_bot_template |
| Conversations | beai_list_conversations, beai_get_conversation |
| Balances | beai_get_credit_summary |
| Actions taken | beai_get_action_statistics |
| Campaigns and outbound calls | beai_list_outbound_campaigns, beai_get_outbound_campaign, beai_get_outbound_call_status |
| Documents | beai_list_documents, beai_get_document |
| Modification outcome | beai_get_operation |
Searches and lists provide page, limit (maximum 25), and the filters
indicated in their schema. Conversation lists do not include their
transcript; it is loaded upon an explicit detail request.
Available bot sections are identity, instructions, voice, telephony,
conversation, and skills. Configuration secrets remain hidden.
Action statistics count observed actions; they are not a token summary or an estimate of purchase costs. An aggregated consumption metric absent from the API is not invented by the connector.
Control catalogue
When telephony configuration is available,
beai_get_telephone_policy and beai_update_telephone_policy consult and modify
the schedule and caps; beai_activate_announcement activates an existing
audio version, without paid generation.
beai_update_bot_identity,beai_update_bot_instructions,beai_update_bot_voice,beai_update_bot_skill,beai_update_conversation_settings: modify the targeted section or skill, preserving omitted fields.beai_create_bot,beai_duplicate_bot: create or duplicate an authorised bot.beai_create_bot_template,beai_update_bot_template: manage a bot template.beai_update_document: modify the name or refresh settings of a document.beai_create_outbound_campaign,beai_update_outbound_campaign: prepare a campaign without starting or scheduling it.
The fields in changes use the same names, constraints, and permissions as
the corresponding REST operation, available in your account's API documentation.
Each modification requires operation_key, a unique key of 8 to 100
characters (letters, digits, dot, hyphen, colon, or underscore).
A lost response does not warrant a new key: reuse the same
operation and its identical parameters, or consult beai_get_operation. A key
already used with different parameters is rejected. If the outcome remains
uncertain, the connector refuses to re-execute the action. Enqueuing a
synchronisation is not presented as its final success.
Payments, top-ups, deletions, SMS messages, and call initiations are excluded from this catalogue. Binary files are uploaded in BeAI or via the REST API; uploading them is not yet offered as an MCP tool. Connection and discovery do not trigger any calls or send any messages.
Monitor and revoke
MCP access displays authorised assistants, their profile, expiry, and their last use. Revoke this access immediately blocks subsequent calls and renewals. Each access token lasts one hour; a rotating refresh token allows continuing for up to 30 days. Thereafter, or after revocation, a new authorisation is required. A rejected assistant receives no access. A maximum of twenty active accesses are allowed per account.
The equivalent operations are GET /api/v1/mcp/access and
DELETE /api/v1/mcp/access/{id}, with your REST API key. They apply to your
own access; an administrator cannot revoke someone else's access by
simply changing the identifier.
Compatibility and diagnostics
The server accepts MCP revisions 2026-07-28 (sessionless discovery, metadata per request) and 2025-11-25 (classic initialisation, without GET stream). It returns JSON responses and advertises neither unimplemented resources, nor prompts, nor change notifications. Browser origins external to BeAI are rejected; remote clients running server-side normally do not send an Origin header. A web client calling BeAI directly from another origin is not supported in this first version.
The compatibility of each assistant depends on its versions and its OAuth flow. The existence of the endpoint does not guarantee compatibility with all clients. If rejected, check the version, server address, account, permissions, expiry, and client redirect URIs.
The DEV private address and the DEV public address are separate resources: access granted on one address must be used on that same address.
A network disconnection does not necessarily cancel a modification already underway: check its result using the same operation key.
Requests are limited to 256 KB, results to 1 MB, and rate to 120 requests per minute per account. A validation error does not permit ignoring a required field. Errors include a correlation ID when a business operation has been initiated. Provide this ID to support, without sharing any token, password, or authorisation code.
Saving and synchronization
Revisions 2025-06-18, 2025-11-25 and 2026-07-28 are supported through their respective lifecycles. The first two negotiate a version with initialize; the last uses metadata on each request. Actual tool availability in your assistant’s chat must still be checked with that client.
persisted: true confirms saved data; operational: true also confirms required synchronization. A partial result preserves the saved configuration but indicates unconfirmed synchronization. pending means it awaits an attempt; a lost network response does not justify saving the bot again. Historical stored results with failed synchronization are also presented as partial.
In Bot → Tools → Synchronization, check the state and retry synchronization only. An identity change without a connection change does not trigger telephone registration. Each attempt is limited to 90 seconds; during its 120-second lease, another attempt on the same bot waits. No automatic retry follows an uncertain result.
The same permissions apply to beai_get_runtime_synchronization, beai_retry_runtime_synchronization, GET /api/v1/bots/{id}/runtime/synchronization and POST /api/v1/bots/{id}/runtime/synchronization/{syncId}/retry. A retry accepts only operation_key, never bot fields. Keep this key after a lost response. Read the original operation with beai_get_operation to track its updated result without repeating the save.
To respect current permissions, replaying or reading an operation returns only its operational receipt (business_fields_omitted: true). Read business fields through the resource’s read tool. The stored historical receipt is not rewritten.