MCP — interface programática

Além do REST, o GetMyBot oferece uma interface MCP (Model Context Protocol) — voltada para agentes e assistentes de IA que invocam ferramentas em vez de chamar endpoints manualmente. O REST continua sendo a interface principal; o MCP é uma alternativa conveniente para cenários agênticos. Os nomes de ferramentas, recursos e prompts abaixo correspondem exatamente ao que o servidor publica.

Endereço e autorização

O MCP está disponível no endpoint /mcp (transporte Streamable HTTP, método POST). A autorização usa o mesmo token pessoal que o REST: cabeçalho Authorization: Bearer mbp_…. Não é necessário criar tokens separados — um único PAT funciona tanto para REST quanto para MCP. Cada ferramenta exige o mesmo scope que o endpoint REST correspondente; um token com scope * tem acesso completo. Se o scope for insuficiente, a chamada é rejeitada (fail-closed), assim como no REST.

Conexão com Claude Code / Cursor

Adicione o GetMyBot como servidor MCP remoto. Exemplo de configuração (mcpServers) — substitua seu domínio e token:

{
  "mcpServers": {
    "mybot": {
      "url": "https://seu-domínio/mcp",
      "headers": {
        "Authorization": "Bearer mbp_SEU_TOKEN"
      }
    }
  }
}

Claude Code: coloque este bloco no .mcp.json do projeto ou adicione o servidor com o comando claude mcp add. Cursor: adicione o mesmo bloco nas configurações MCP (Settings → MCP → Add server). Após a conexão, o cliente receberá automaticamente a lista de ferramentas, recursos e prompts.

Ferramentas por domínio

O servidor publica 100 ferramentas — cobertura completa do REST acessível via PAT. Abaixo: ferramenta e scope exigido. Nomes no formato verbo_substantivo (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

Canais e templates de WhatsApp (bots)

O suporte multicanal (Telegram + WhatsApp + VK) também está disponível via MCP. Canais e templates são controlados pelos scopes compartilhados bots:read / bots:write — não há um scope de canal separado.

  • list_channels — bots:read — lista os canais de um bot (plataforma tg/wa/vk, external_id, nome, enabled, callback_url).
  • connect_channel — bots:write — conecta um canal WhatsApp ou VK (platform + credenciais).
  • delete_channel — bots:write — desconecta um canal.
  • list_wa_templates — bots:read — o catálogo de templates de WhatsApp do canal (nome, idioma, status, categoria, corpo).
  • sync_wa_templates — bots:write — ressincroniza o catálogo de templates com a Meta.
  • create_wa_template — bots:write — cria um template de WhatsApp e o envia à Meta para revisão.
  • update_wa_template — bots:write — edita um template (nos status APPROVED/REJECTED/PAUSED).
  • delete_wa_template — bots:write — exclui um template.

Os canais do Telegram são conectados via connect_bot, não via connect_channel — este último trata apenas de wa e vk. Categorias de template: MARKETING / UTILITY / AUTHENTICATION. O create_wa_template envia o rascunho imediatamente à Meta para revisão; o status muda de forma assíncrona — releia-o via list_wa_templates (atualizando o catálogo com sync_wa_templates, se necessário).

O envio de mídia de cabeçalho de um template (imagem/vídeo/documento) via MCP ainda não é suportado — use a interface web ou o REST POST /api/bots/{botID}/channels/{channelID}/templates/media.

Reações (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
  • 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

A importação via import_reactions cria reações, mas ignora mídia: no contexto MCP não há verificação premium nem receptor Telegram para arquivos. Se o bundle SamBot contiver imagens, vídeos ou documentos, use a importação REST completa (POST /api/bots/{botID}/reactions/import), que também transfere a mídia.

Transmissões (broadcasts)

  • start_broadcast — broadcasts:write (opc. paid, opc. segmento por etiquetas)
  • get_broadcast — broadcasts:write
  • pause_broadcast — broadcasts:write
  • resume_broadcast — broadcasts:write
  • cancel_broadcast — broadcasts:write

Etiquetas (labels)

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

Coleções e registros (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

Cenários (flows)

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

Integrações, conexões e credenciais (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

Mídia (media)

  • upload_media — media:write
  • get_media — media:write

Templates (templates)

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

Assinantes, chats e diálogos — leitura (subscribers)

  • list_subscribers — subscribers:read (paginação offset/limit, filtros por etiquetas)
  • list_chats — subscribers:read
  • list_dialogs — subscribers:read
  • read_dialog — subscribers:read
  • send_dialog_message — subscribers:write
  • send_dialog_reaction — subscribers:write
  • transcribe_dialog_message — subscribers:write

Estatísticas e análises (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

Faturamento — leitura (billing)

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

Envio de mensagens

  • send_message — broadcasts:write — envia uma mensagem em nome do bot; o consumo de saldo é contabilizado automaticamente pelo dono do token.

Recursos

Além das ferramentas, o servidor oferece recursos — você pode lê-los para não precisar adivinhar a estrutura:

  • mybot://openapi.yaml — especificação OpenAPI completa (a mesma disponível em /openapi.yaml).
  • mybot://reference — referência compacta: lista de ferramentas com seus scopes e convenções (endereço base, paginação, formato de erros, limites).
  • mybot://schemas/reaction, mybot://schemas/trigger, mybot://schemas/action, mybot://schemas/flow, mybot://schemas/collection — esquemas JSON das configurações. Muito úteis para gerar reações (gatilho, condições, chats, ações), cenários e coleções de forma correta.
  • mybot://bots — lista dinâmica dos seus bots (contexto rápido sem chamar uma ferramenta).

Prompts

Cenários prontos (slash-comandos no cliente MCP):

  • setup_autoresponder — montar um bot autoresponder (argumentos: bot, tema/conjunto de perguntas).
  • segment_broadcast — transmissão para um segmento de etiquetas (argumentos: bot, etiquetas, reação/texto).
  • diagnose_reaction — descobrir por que uma reação não está disparando (lê a reação, o reaction-health e a ordem).
  • import_from_sambot — realizar a importação de um bundle SamBot e verificar o resultado.
  • weekly_report — resumo de estatísticas e análises do bot em um período.

Quando usar MCP e quando usar REST

  • Se você está construindo uma integração, sincronização, script ou painel próprio, use o REST.
  • Se você está conectando o GetMyBot a um assistente ou agente de IA compatível com MCP, use o /mcp.

Ambas as interfaces funcionam com o mesmo token e obedecem às mesmas permissões do dono. Se não encontrar uma ferramenta para determinada tarefa, o endpoint REST correspondente está sempre disponível na referência interativa.

Próximos passos