Server MCP di Telegram: dai ai tuoi agenti IA tutta la Telegram Bot API, in sicurezza

Perché gli agenti IA hanno bisogno di uno strato per Telegram

Gli agenti IA stanno diventando bravi a usare strumenti reali. Sanno leggere una dashboard, capire cosa conta e fare il passo successivo. Ma per agire dentro Telegram serve un ponte: qualcosa che trasformi una frase come "fissa l'annuncio dell'AMA e apri un topic per le domande" nelle chiamate giuste all'API di Telegram.

Quel ponte è un server MCP di Telegram.

Il Model Context Protocol (MCP) è uno standard aperto che permette a client IA come Claude, ChatGPT, Cursor e Codex di scoprire strumenti e chiamarli. Un server MCP di Telegram espone le azioni di Telegram come strumenti, con descrizioni chiare e schemi di input che il modello può seguire.

Metricgram ora ne gestisce uno per te, basato sul bot che già amministra i tuoi gruppi.

Cosa comporta davvero adattare la Telegram Bot API

Sulla carta, adattare la Bot API a un agente sembra semplice. In pratica devi:

• Ospitare un bot, tenere segreto il suo token e mantenerlo attivo.
• Ricevere gli aggiornamenti tramite webhook o polling.
• Scrivere la definizione di uno strumento per ogni endpoint che l'agente deve usare.
• Impedire all'agente di pubblicare in chat che non dovrebbe mai toccare.
• Gestire limiti di frequenza, supergruppi migrati e messaggi di errore di Telegram.
• Rendere sicuri i nuovi tentativi, così un problema di rete occasionale non pubblica due volte lo stesso messaggio.
• Registrare cosa ha fatto l'agente, nel caso tu debba spiegarlo in seguito.

La maggior parte dei team si ferma a "inviare un messaggio", perché tutto il resto richiede molta infrastruttura. Il risultato è un agente che sa parlare ma non riesce davvero a gestire una community.

Come funziona il server MCP di Telegram di Metricgram

Metricgram è già presente nei tuoi gruppi Telegram come bot amministratore (o come tuo bot personalizzato). Il server MCP permette semplicemente al tuo client IA di usare quel bot tramite un endpoint ospitato:

1. Collega i tuoi gruppi a Metricgram e dai al bot i permessi di amministratore.
2. Aggiungi l'endpoint https://metricgram.com/api/v1/mcp al tuo client IA, ad esempio come connettore personalizzato in Claude.
3. Accedi e approva l'accesso con OAuth. Fatto: nessun server, webhook o token da gestire. I client senza OAuth possono usare una chiave API, con la configurazione qui sotto.

{
  "mcpServers": {
    "metricgram": {
      "url": "https://metricgram.com/api/v1/mcp",
      "headers": { "Authorization": "Bearer YOUR_API_KEY" }
    }
  }
}

Chi usa Claude Desktop può collegare lo stesso endpoint con mcp-remote. Gli snippet esatti per ogni client si trovano nella pagina MCP del tuo Manager.

Oltre 70 metodi della Bot API, due modi per chiamarli

Il server espone la Telegram Bot API su due livelli.

Strumenti tipizzati per il lavoro quotidiano

Le attività comuni hanno strumenti dedicati con parametri descrittivi, che rendono facile per i modelli usarli correttamente:

• send_telegram_message con topic, risposte e pulsanti URL
• send_telegram_media per foto, video, GIF, documenti, audio e sticker
• send_telegram_poll per sondaggi e quiz
• edit_telegram_message, delete_telegram_messages, react_to_telegram_message
• pin_telegram_message e forward_telegram_message
• manage_forum_topic per creare, rinominare, chiudere, riaprire o eliminare topic
• get_telegram_chat e get_telegram_chat_member per i dati della chat in tempo reale
• handle_telegram_join_request, create_telegram_invite_link e update_telegram_chat_settings

Un gateway completo alla Bot API

Tutto il resto passa da telegram_bot_api. L'agente indica il nome ufficiale di un metodo della Bot API e i relativi parametri, per esempio setChatPermissions, banChatSenderChat, editMessageMedia, hideGeneralForumTopic o revokeChatInviteLink. Lo strumento complementare telegram_api_methods elenca tutti i metodi che la chiave corrente può usare, così l'agente sa sempre cosa ha a disposizione.

Sicurezza: perché l'agente non sceglie mai un chat_id

La scelta progettuale più importante riguarda ciò che l'agente non può fare.

• La chat è bloccata. L'agente passa un group_id di Metricgram. Il server ricava il chat_id di Telegram da un gruppo di tua proprietà e rifiuta qualsiasi altra chat.
• Inoltri e citazioni vengono verificati. Un messaggio può essere inoltrato, copiato o citato solo dai tuoi gruppi.
• Le azioni globali del bot sono escluse. Webhook, pagamenti, modifiche al profilo del bot e uscita da un gruppo non sono esposti.
• I pulsanti sono sicuri. I pulsanti inline possono aprire URL o copiare testo, ma non possono attivare callback verso il bot.
• I permessi rispecchiano la fiducia. telegram:read, telegram:write, telegram:moderate e telegram:admin sono separati, e puoi tenere più chiavi con poteri diversi.
• I nuovi tentativi sono idempotenti. Gli strumenti di scrittura accettano una idempotency_key, così una chiamata ripetuta restituisce il primo risultato invece di agire due volte.
• Ogni chiamata viene registrata con lo strumento e il metodo della Bot API utilizzati.

L'agente agisce come il bot tramite la Bot API ufficiale, mai come il tuo account Telegram personale.

Un contesto che un bot qualsiasi non ha

Un semplice wrapper della Bot API può agire, ma vede poco. Il server MCP di Metricgram espone anche l'intelligence della community:

• Panoramica delle analisi e serie temporali dell'attività
• Membri attivi, storico dei membri e messaggi acquisiti
• Classifiche e premi della gamification
• Riepiloghi IA di quanto accaduto nel gruppo
• Stato degli abbonati Stripe e rinnovi a rischio

Questo significa che un agente può rispondere a "chi ha smesso di partecipare questo mese?" e poi mandare loro un messaggio curato, tutto nella stessa conversazione.

Esempi di flussi di lavoro

Annuncio settimanale. "Pubblica l'annuncio settimanale dell'AMA in Crypto Talk, fissalo senza notificare tutti, apri un topic per le domande dell'AMA e crea un link di invito che scada venerdì."

Giro di moderazione. "Controlla gli ultimi 200 messaggi alla ricerca di link di spam, eliminali e limita i mittenti per 24 ore."

Report della community. "Confronta l'attività di questa settimana con quella della scorsa, elenca i cinque membri più attivi e pubblica un breve messaggio di ringraziamento nel topic Generale."

Smistamento delle richieste di accesso. "Approva le richieste di accesso in sospeso degli utenti che sono abbonati attivi e rifiuta le altre."

A chi è rivolto

• Proprietari di community che vogliono un assistente per il lavoro amministrativo di routine.
• Agenzie che gestiscono molti gruppi di clienti e vogliono un unico agente per tutti.
• Team di supporto e customer success che gestiscono community di clienti su Telegram.
• Sviluppatori che vogliono Telegram nel loro stack di agenti senza gestire infrastruttura per bot.

Come iniziare

Il server MCP è incluso in tutti i piani Metricgram e nella prova gratuita di 14 giorni, così puoi collegare un agente prima di pagare. La maggior parte dei client si collega con OAuth: incolla l'URL del server, accedi e approva l'accesso. Le chiavi API restano disponibili per i client senza OAuth.

Scopri di più nella pagina del server MCP di Telegram e nella panoramica delle funzioni MCP, poi crea la tua prima chiave dal Manager.