Collega gli agenti IA a BroadNet con MCP.

Che cos'è il server MCP

Il Model Context Protocol (MCP) è uno standard aperto che permette agli assistenti IA di individuare e invocare strumenti esterni. Il server MCP di BroadNet è un server remoto: il tuo client si collega via HTTPS, elenca gli strumenti disponibili e li invoca per tuo conto.

Gli strumenti corrispondono alla stessa API di BroadNet documentata nel riferimento API e nella specifica OpenAPI: invio di messaggi, modelli WhatsApp, report di consegna. L'agente agisce con i permessi del token che gli fornisci, esattamente come farebbe il tuo codice.

Due server MCP: conoscenza e messaggistica

BroadNet gestisce due server MCP. Il server di messaggistica descritto in questa pagina agisce sul tuo account. Il server di conoscenza è pubblico: un agente può interrogarlo su copertura di BroadNet, regole dei Sender ID, tariffe di listino pubblicate, normative e dati aziendali senza login.

Prova il server di conoscenza da terminale: prima l'handshake initialize, poi una chiamata a uno strumento.

curl -X POST https://www.broadnet.me/mcp \
  -H "Content-Type: application/json" \
  -H "Accept: application/json, text/event-stream" \
  -d '{"jsonrpc":"2.0","id":1,"method":"initialize",
       "params":{"protocolVersion":"2025-06-18","capabilities":{},
                 "clientInfo":{"name":"curl","version":"1.0"}}}'

curl -X POST https://www.broadnet.me/mcp \
  -H "Content-Type: application/json" \
  -H "Accept: application/json, text/event-stream" \
  -H "MCP-Protocol-Version: 2025-06-18" \
  -d '{"jsonrpc":"2.0","id":2,"method":"tools/call",
       "params":{"name":"sender_id_rules","arguments":{"country":"ae"}}}'

Endpoint e autenticazione

Esiste un unico endpoint per tutti gli account: https://mcp.broadnet.me/mcp. Ogni richiesta deve includere il tuo token BroadNet in un'intestazione Authorization.

Il token si ottiene dal tuo account BroadNet. Nella demo viene generato nel portale BroadAdmin, in Integrations → MCP Integration, con «Get temporary key»; il portale precisa che una chiave permanente viene emessa dall'amministratore del tuo account o dall'account principale.

Una richiesta senza l'intestazione viene rifiutata a livello di protocollo: questa è la risposta reale del server a una chiamata initialize non autenticata:

event: message
data: {"jsonrpc":"2.0","id":1,"error":{"code":-32001,
  "message":"Authorization bearer token is required. Connect with an
  'Authorization: Bearer <BroadNet token>' header."}}

Collegare un client MCP

La maggior parte dei client MCP accetta una configurazione JSON con l'URL del server e le intestazioni della richiesta. Una voce tipica è questa:

{
  "mcpServers": {
    "broadnet": {
      "type": "http",
      "url": "https://mcp.broadnet.me/mcp",
      "headers": {
        "Authorization": "Bearer ${BROADNET_TOKEN}"
      }
    }
  }
}

Per provare la connessione senza un client, invia tu stesso la richiesta MCP initialize:

curl -X POST https://mcp.broadnet.me/mcp \
  -H "Authorization: Bearer $BROADNET_TOKEN" \
  -H "Content-Type: application/json" \
  -H "Accept: application/json, text/event-stream" \
  -d '{"jsonrpc":"2.0","id":1,"method":"initialize",
       "params":{"protocolVersion":"2025-06-18","capabilities":{},
                 "clientInfo":{"name":"curl","version":"1.0"}}}'

Cosa mostra la demo

La registrazione del team di prodotto illustra l'intero flusso in cinque passaggi, con Cursor come client MCP:

1. 1
   Accedi

   Entra nel portale BroadAdmin con il tuo account BroadNet.

2. 2
   Ottieni una chiave e la configurazione

   Apri Integrations → MCP Integration, genera una chiave temporanea e copia la configurazione del client già pronta.

3. 3
   Aggiungi il server al client

   Nel client MCP, aggiungi un nuovo server MCP e incolla la configurazione in mcp.json: URL https://mcp.broadnet.me/mcp con l'intestazione Bearer.

4. 4
   Controlla gli strumenti

   Il client si collega ed elenca gli strumenti BroadNet, ognuno dei quali può essere attivato o disattivato.

5. 5
   Chiedi in linguaggio naturale

   L'utente chiede all'agente di inviare un messaggio WhatsApp a un numero. L'agente sceglie lo strumento di invio WhatsApp, l'API risponde HTTP 200 con il messaggio accettato e il messaggio arriva su WhatsApp dall'account aziendale.

Nella registrazione il client riporta 380 strumenti BroadNet, tra cui send_message, post_sms_send, post_whatsapp_message_send, get_whatsapp_template_list, post_whatsapp_template_send, post_rcs_message_send, post_telegram_message_send, post_instagram_message_send, post_messenger_message_send, post_push_message_send e get_report_delivery. L'elenco esatto dipende dalla versione del server e dal tuo account.

Una versione commentata della stessa registrazione aggiunge una scheda di panoramica: un solo endpoint MCP, gli stessi passaggi di copia e incolla per ogni agente.

Note di sicurezza

• Il token è una credenziale di invio

  Chiunque lo possieda può inviare messaggi dal tuo account. Conservalo come una password, mai in un file condiviso o versionato.

• Per le prove usa chiavi temporanee

  Usa una chiave temporanea mentre fai prove e chiedi una chiave permanente all'amministratore del tuo account solo per un agente in produzione.

• Attiva solo gli strumenti necessari

  I client MCP consentono di disattivare i singoli strumenti. Un agente che invia solo SMS non ha bisogno degli strumenti per modelli, onboarding o account.

• Mantieni una persona nel processo

  Gli agenti agiscono su istruzioni in linguaggio naturale. Fai chiedere al client una conferma prima degli strumenti che inviano messaggi, soprattutto verso molti destinatari.

• Revoca un token compromesso

  Se un token viene esposto, contatta l'amministratore del tuo account o il supporto BroadNet per revocarlo ed emetterne uno nuovo.

Approfondimenti

Domande