MCP: Programmatic Interface

In addition to REST, GetMyBot provides an MCP (Model Context Protocol) interface designed for AI agents and assistants that invoke tools rather than calling endpoints manually. REST remains the primary interface; MCP is a convenient alternative for agentic scenarios. The tool, resource, and prompt names listed below match what the server publishes.

Address and authorization

MCP is available at the /mcp endpoint (Streamable HTTP transport, POST method). Authorization uses the same personal token as REST: the Authorization: Bearer mbp_… header. No separate tokens are needed: a single PAT works for both REST and MCP. A token belongs to one account: list_bots and the other tools see that account's bots only, and get_balance, get_transactions and connect_bot apply to it as well (see The token's account). Each tool requires the same scope as the corresponding REST endpoint; a token with scope * has full access. If a scope is missing, the call is rejected (fail-closed), just as with REST.

When the token is minted for somebody else's account, account-level tools also check the token holder's account rights: connect_bot needs bots.create, billing tools need billing.read or billing.write. The * scope does not grant account rights. Without them the tool returns the error permission denied: missing cabinet right (you are not a member of the account and reach it only through a shared bot) or permission denied: missing cabinet right: <right> (the membership lacks that specific right). Rights are granted by the account owner in the "Cabinet access" card; access management itself is not available via MCP.

Connecting to Claude Code / Cursor

Add GetMyBot as a remote MCP server. Example configuration (mcpServers): substitute your domain and token:

{
  "mcpServers": {
    "mybot": {
      "url": "https://your-domain/mcp",
      "headers": {
        "Authorization": "Bearer mbp_YOUR_TOKEN"
      }
    }
  }
}

Claude Code: place this block in your project's .mcp.json or add the server with claude mcp add. Cursor: add the same block to MCP settings (Settings → MCP → Add server). After connecting, the client will automatically receive the list of tools, resources, and prompts.

Tools by domain

The server publishes a tool for every PAT-accessible REST operation: full coverage, not a subset. Below is each tool and its required scope. Names follow the verb_noun format (snake_case).

Bots (bots)

• list_bots: bots:read
• get_bot: bots:read
• validate_bot_token: bots:write
• connect_bot: bots:write
• update_bot: bots:write
• delete_bot: bots:write
• sync_bot: bots:write
• change_bot_token: bots:write
• transfer_bot: bots:write
• get_bot_settings: settings:read
• update_bot_settings: settings:write
• get_widget_settings: settings:read
• update_widget_settings: settings:write

get_widget_settings returns the web widget's brand/launcher/panel/welcome/prechat/availability/ behavior settings, its origins, widgetKey and revision. update_widget_settings requires the expected_revision from that snapshot and refuses the save if the revision has moved since. update_bot_settings can also overwrite widget_experience wholesale, but it skips that validation, the avatar-ownership check, and the revision lock — for the widget, that is not the path to use.

Channels & WhatsApp templates (bots)

Multichannel support (Telegram + WhatsApp + VK + web widget) is available over MCP too. Channels and templates are gated by the shared scopes bots:read / bots:write: there is no separate channel scope.

• list_channels: bots:read: list a bot's channels (platform tg/wa/vk/web, external_id, name, enabled, callback_url).
• connect_channel: bots:write: connect a WhatsApp channel, a VK channel, or a web widget (platform + creds; for platform: "web" no creds are needed, only a required non-empty origins).
• delete_channel: bots:write: disconnect a channel.
• list_wa_templates: bots:read: the channel's WhatsApp template catalog (name, language, status, category, body).
• sync_wa_templates: bots:write: re-sync the template catalog from Meta.
• create_wa_template: bots:write: create a WhatsApp template and submit it to Meta for review.
• update_wa_template: bots:write: edit a template (in APPROVED/REJECTED/PAUSED status).
• delete_wa_template: bots:write: delete a template.

Telegram channels are connected via connect_bot, not connect_channel: the latter handles wa, vk, and web. Template categories: MARKETING / UTILITY / AUTHENTICATION. create_wa_template immediately submits the draft to Meta for review; the status changes asynchronously: read it back via list_wa_templates (refreshing the catalog with sync_wa_templates if needed).

connect_channel's response for platform: "web" differs from the other platforms: {"widget_key": "…"}, not {"id": …}. The call is idempotent: connecting the same bot again returns the same key rather than creating a second widget. Configuring the widget's look and behavior is the separate get_widget_settings/update_widget_settings pair above, not connect_channel.

Uploading a template's media header (image/video/document) over MCP is not supported yet: use the web UI or REST POST /api/bots/{botID}/channels/{channelID}/templates/media.

Reactions (reactions)

• list_reactions: reactions:read
• get_reaction: reactions:read
• create_reaction: reactions:write
• update_reaction: reactions:write
• delete_reaction: reactions:write
• import_reactions: reactions:write
• test_formula: reactions:write: test an advanced formula against sample text. Fields: bot_id, formula, sample (in REST the same field is called sample_text). The context is empty: ctx and parameters are not substituted, the sample text is available as {text} / {answer}.
• reorder_reaction: reactions:write
• get_reaction_links: reactions:read
• list_reaction_folders: reactions:read
• create_reaction_folder: reactions:write
• update_reaction_folder: reactions:write
• delete_reaction_folder: reactions:write
• add_reaction_to_folder: reactions:write
• remove_reaction_from_folder: reactions:write
• add_reactions_to_folder: reactions:write

Import via import_reactions creates reactions but skips media: there is no premium check or Telegram file receiver in the MCP context. If the SamBot bundle contains images, videos, or documents, use the full-featured REST import (POST /api/bots/{botID}/reactions/import): it transfers media as well.

Broadcasts (broadcasts)

• start_broadcast: broadcasts:write (optional paid, optional segment by labels)
• get_broadcast: broadcasts:write: for broadcasts started from a reaction via start_broadcast, the report includes blocked – block events attributed within 24 hours after delivery.
• pause_broadcast: broadcasts:write
• resume_broadcast: broadcasts:write
• cancel_broadcast: broadcasts:write

Labels (labels)

• list_labels: labels:read
• create_label: labels:write
• delete_label: labels:write
• set_label_favorite: labels:write

Collections and records (collections)

• list_collections: collections:read
• create_collection: collections:write
• update_collection: collections:write
• delete_collection: collections:write
• list_records: collections:read
• create_record: collections:write
• update_record: collections:write
• delete_record: collections:write

Scenarios (flows)

• list_flows: flows:read
• get_flow: flows:read
• create_flow: flows:write
• update_flow: flows:write
• delete_flow: flows:write

Integrations, connections, credentials (integrations)

• list_integrations: integrations:read
• get_integration_sheets: integrations:read
• get_integration_status: integrations:read
• create_integration: integrations:write
• update_integration: integrations:write
• delete_integration: integrations:write
• rotate_integration_token: integrations:write
• list_connections: integrations:read
• create_connection: integrations:write
• test_connection: integrations:write
• update_connection: integrations:write
• delete_connection: integrations:write
• list_credentials: integrations:read
• create_credential: integrations:write
• update_credential: integrations:write
• delete_credential: integrations:write

CRM (crm): read-only

CRM connections are their own scope pair, and only the reads are published as tools. Connecting, syncing, retrying a job and resolving a conflict stay REST-only, so an agent can observe a CRM integration but cannot change what it does. None of these tools ever returns credentials.

• list_crm_connections: crm:read: a bot's connections with provider, status and capabilities.
• get_crm_connection: crm:read: one connection's safe summary.
• get_crm_mapping: crm:read: the connection's current mapping revision.
• list_crm_operations: crm:read: recent sync operations, newest first, optionally scoped to one connection.
• get_crm_operation: crm:read: one operation with its jobs; never a job's raw request payload.
• list_crm_conflicts: crm:read: jobs waiting for manual conflict resolution.

See CRM integrations for what a connection, mapping and operation mean.

Browser push and customer SDK (web_push, customer_sdk): read-only

Both verticals are published as reads only. Enabling a project, rotating VAPID keys or an identity secret, sending a test notification and revoking a device stay REST-only on purpose, so an agent can report on these channels but cannot change or trigger them. No tool ever returns a VAPID private key, a push endpoint, an identity secret or a device push token.

• get_web_push_config: web_push:read: the redacted Web Push configuration for a bot.
• get_web_push_status: web_push:read: whether browser push is enabled.
• get_web_push_report: web_push:read: subscription and receipt counters.
• get_customer_sdk_status: customer_sdk:read: whether the mobile SDK project is enabled.
• get_customer_sdk_report: customer_sdk:read: installation and push-token counters.

See Browser push and Customer SDK for what these numbers mean.

Media (media)

• upload_media: media:write
• get_media: media:write
• download_media: media:write: download a media asset's bytes as base64 ({mime, size_bytes, data_base64}), e.g. to re-upload it to another bot with upload_media. Refuses assets larger than 2 MB.

Templates (templates)

• list_templates: templates:read
• delete_template: templates:write
• create_template_from_bot: templates:write
• apply_template: templates:write

Subscribers, chats, dialogs (subscribers)

• list_subscribers: subscribers:read (offset/limit pagination, search, label and is_blocked=true|false filters; each item carries is_blocked and blocked_at when the subscriber blocked the bot)
• list_chats: subscribers:read
• list_dialogs: subscribers:read: operator-inbox threads: subscriber, platform, last-message preview, last_seen; keyset pagination via cursor/next_cursor.
• read_dialog: subscribers:read: dialog messages, older pages via before_id; transcribed audio/video messages carry transcript_status/transcript/transcript_error in meta.
• send_dialog_message: subscribers:write: operator text send to a subscriber: WhatsApp 24h window and channel routing enforced, delivery metered to the token owner.
• send_dialog_reaction: subscribers:write: send one of the bot's ready-made reactions to a subscriber (like the operator console's "send reaction" button).
• transcribe_dialog_message: subscribers:write: start or fetch a speech-to-text transcription of an audio/video message. Idempotent: the first call enqueues a background job ({"status":"pending"}), poll by calling again until {"status":"done","text":…}; a failed transcription is restarted automatically. Requires the bot's "Speech recognition" integration.

Stats and analytics (stats)

• get_stats: stats:read
• get_stats_summary: stats:read
• get_stats_recent: stats:read
• get_stats_log: stats:read
• get_reaction_health: stats:read
• get_analytics: stats:read
• get_analytics_chats: stats:read
• get_funnel: stats:read

Shared experiments (experiments)

• list_experiments: experiments:read
• get_experiment: experiments:read
• get_experiment_report: experiments:read

These tools are read-only. They return the immutable experiment definition or the report for one version. The report keeps currencies separate and carries the selected attribution model; it does not create assignments, record facts, change a lifecycle state, or select a winner.

{
  "name": "get_experiment_report",
  "arguments": { "bot_id": "<bot-id>", "experiment_id": "<experiment-id>", "version": 2 }
}

Saved event funnels currently use REST only. Do not confuse the legacy get_funnel tool above, which returns the auto-derived stats funnel, with a saved event funnel definition or its cohort. Use the bounded REST endpoints in Saved event funnels for those workflows.

Billing: read (billing)

• get_balance: billing:read
• list_tariffs: billing:read
• get_transactions: billing:read

In somebody else's account all three require the account right billing.read, otherwise: permission denied: missing cabinet right.

Sending messages

• send_message: broadcasts:write: send a message on behalf of the bot; balance charges are tracked automatically by the token owner.

Resources

In addition to tools, the server exposes resources you can read to avoid guessing structure:

• mybot://openapi.yaml: the full OpenAPI spec (same as served at /openapi.yaml).
• mybot://reference: a compact reference: tool list with scopes and conventions (base URL, pagination, error format, limits).
• mybot://schemas/reaction, mybot://schemas/trigger, mybot://schemas/action, mybot://schemas/flow, mybot://schemas/collection: JSON schemas for configs. Most useful for correctly generating reactions (trigger, conditions, chats, actions), scenarios, and collections.
• mybot://bots: a dynamic list of your bots (quick context without calling a tool).

Prompts

Ready-made scenarios (slash commands in MCP clients):

• setup_autoresponder: build an autoresponder bot (arguments: bot, topic/question set).
• segment_broadcast: broadcast to a label segment (arguments: bot, labels, reaction/text).
• diagnose_reaction: figure out why a reaction is not triggering (reads the reaction, reaction health, and order).
• import_from_sambot: run a SamBot bundle import and verify the result.
• weekly_report: summary of bot stats/analytics for a period.

When to use MCP vs. REST

• Building an integration, sync job, script, or custom dashboard: use REST.
• Connecting GetMyBot to an AI assistant or agent that supports MCP: use /mcp.

Both interfaces work under the same token and are subject to the same owner permissions. If no tool covers your use case, the corresponding REST endpoint is always available in the interactive reference.

Feature rollout gates are identical on both surfaces. Copilot, Flow Intelligence, Explainable Replay, and Vertical Playbooks fail closed when the account is not included in the rollout.

Customer AI and workflow tools

Mutations are audited with the MCP surface and PAT token id. OAuth returns a browser handoff URL; the callback and webhooks are never tools. Provider keyring, routing, and reconciliation are not published to customer agents.

What's next

• Skills for AI agents: ready-made GetMyBot wrappers for Claude Code and other agents.
• Authorization and tokens: create a PAT for MCP.
• API quickstart: the REST alternative.
• Interactive reference: full REST endpoints.