MCP — interfaccia programmatica

Oltre a REST, GetMyBot offre un'interfaccia MCP (Model Context Protocol) pensata per agenti AI e assistenti che invocano strumenti anziché chiamare endpoint manualmente. REST rimane l'interfaccia principale; MCP è una comoda alternativa per scenari agentici. I nomi di strumenti, risorse e prompt elencati qui coincidono con quelli pubblicati dal server.

Indirizzo e autorizzazione

MCP è disponibile all'endpoint /mcp (trasporto Streamable HTTP, metodo POST). L'autorizzazione usa lo stesso token personale utilizzato per REST: header Authorization: Bearer mbp_…. Non è necessario creare token separati: un singolo PAT funziona sia per REST che per MCP. Ogni strumento richiede lo stesso scope del corrispondente endpoint REST; un token con scope * ha accesso completo. Se lo scope non è sufficiente, la chiamata viene rifiutata (fail-closed), come in REST.

Connessione a Claude Code / Cursor

Aggiungi GetMyBot come server MCP remoto. Esempio di configurazione (mcpServers) — sostituisci il tuo dominio e token:

{
  "mcpServers": {
    "mybot": {
      "url": "https://tuo-dominio/mcp",
      "headers": {
        "Authorization": "Bearer mbp_TUO_TOKEN"
      }
    }
  }
}

Claude Code: inserisci questo blocco nel file .mcp.json del progetto oppure aggiungi il server con il comando claude mcp add. Cursor: aggiungi lo stesso blocco nelle impostazioni MCP (Settings → MCP → Add server). Dopo la connessione, il client riceve automaticamente l'elenco di strumenti, risorse e prompt.

Strumenti per dominio

Il server pubblica 100 strumenti — copertura completa del REST accessibile tramite PAT. Di seguito trovi lo strumento e lo scope richiesto. I nomi seguono il formato verbo_sostantivo (snake_case).

Bot (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

Canali e template WhatsApp (bots)

Il supporto multicanale (Telegram + WhatsApp + VK) è disponibile anche via MCP. I canali e i template sono regolati dagli scope condivisi bots:read / bots:write — non esiste uno scope separato per i canali.

  • list_channels — bots:read — elenca i canali di un bot (platform tg/wa/vk, external_id, name, enabled, callback_url).
  • connect_channel — bots:write — collega un canale WhatsApp o VK (platform + creds).
  • delete_channel — bots:write — scollega un canale.
  • list_wa_templates — bots:read — il catalogo dei template WhatsApp del canale (name, language, status, category, body).
  • sync_wa_templates — bots:write — risincronizza il catalogo dei template da Meta.
  • create_wa_template — bots:write — crea un template WhatsApp e lo invia alla moderazione di Meta.
  • update_wa_template — bots:write — modifica un template (negli stati APPROVED/REJECTED/PAUSED).
  • delete_wa_template — bots:write — elimina un template.

I canali Telegram si collegano tramite connect_bot, non connect_channel — quest'ultimo gestisce solo wa e vk. Categorie dei template: MARKETING / UTILITY / AUTHENTICATION. create_wa_template invia subito la bozza alla moderazione di Meta; lo stato cambia in modo asincrono — rileggilo tramite list_wa_templates (aggiornando il catalogo con sync_wa_templates se necessario).

Il caricamento dell'header multimediale di un template (immagine/video/documento) via MCP non è ancora supportato — usa l'interfaccia web o il REST POST /api/bots/{botID}/channels/{channelID}/templates/media.

Reazioni (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

L'importazione tramite import_reactions crea le reazioni ma salta i media: nel contesto MCP non è disponibile la verifica premium né il ricevitore Telegram per i file. Se il bundle SamBot contiene immagini, video o documenti, usa l'importazione REST completa (POST /api/bots/{botID}/reactions/import), che trasferisce anche i media.

Trasmissioni (broadcasts)

  • start_broadcast — broadcasts:write (opz. paid, opz. segmento per etichette)
  • get_broadcast — broadcasts:write
  • pause_broadcast — broadcasts:write
  • resume_broadcast — broadcasts:write
  • cancel_broadcast — broadcasts:write

Etichette (labels)

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

Raccolte e record (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

Scenari (flows)

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

Integrazioni, connessioni, credenziali (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

Media (media)

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

Template (templates)

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

Iscritti, chat, dialoghi — lettura (subscribers)

  • list_subscribers — subscribers:read (paginazione offset/limit, filtri per etichette)
  • 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

Statistiche e analisi (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

Fatturazione — lettura (billing)

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

Invio messaggi

  • send_message — broadcasts:write — invia un messaggio a nome del bot; il consumo del saldo viene calcolato automaticamente in base al proprietario del token.

Risorse

Oltre agli strumenti, il server espone risorse che puoi leggere per non dover indovinare la struttura:

  • mybot://openapi.yaml — specifica OpenAPI completa (la stessa restituita da /openapi.yaml).
  • mybot://reference — riferimento compatto: elenco degli strumenti con i relativi scope e convenzioni (URL base, paginazione, formato degli errori, limiti).
  • mybot://schemas/reaction, mybot://schemas/trigger, mybot://schemas/action, mybot://schemas/flow, mybot://schemas/collection — schemi JSON delle configurazioni. Particolarmente utili per generare correttamente reazioni (trigger, condizioni, chat, azioni), scenari e raccolte.
  • mybot://bots — elenco dinamico dei tuoi bot (contesto rapido senza chiamare uno strumento).

Prompt

Scenari pronti all'uso (slash-command nel client MCP):

  • setup_autoresponder — configura un bot di risposta automatica (argomenti: bot, tema/insieme di domande).
  • segment_broadcast — trasmissione per segmento di etichette (argomenti: bot, etichette, reazione/testo).
  • diagnose_reaction — analizza perché una reazione non si attiva (legge la reazione, la reaction-health e l'ordine).
  • import_from_sambot — esegui l'importazione di un bundle SamBot e verifica il risultato.
  • weekly_report — riepilogo di statistiche e analisi del bot per un periodo.

Quando scegliere MCP e quando REST

  • Stai scrivendo un'integrazione, una sincronizzazione, uno script o un pannello personalizzato — usa REST.
  • Stai collegando GetMyBot a un assistente AI o a un agente che supporta MCP — usa /mcp.

Entrambe le interfacce funzionano con lo stesso token e rispettano gli stessi permessi del proprietario. Se non trovi uno strumento adatto, il corrispondente endpoint REST è sempre disponibile nel riferimento interattivo.

Prossimi passi