Servidor MCP do Telegram: dê aos agentes de IA toda a Telegram Bot API, com segurança

Por que agentes de IA precisam de uma camada para o Telegram

Os agentes de IA estão ficando bons em operar ferramentas reais. Eles leem um painel, decidem o que importa e dão o próximo passo. Mas, para agir dentro do Telegram, precisam de uma ponte: algo que transforme uma frase como "fixe o anúncio do AMA e abra um tópico de perguntas" nas chamadas certas da API do Telegram.

Essa ponte é um servidor MCP do Telegram.

O Model Context Protocol (MCP) é um padrão aberto que permite que clientes de IA como Claude, ChatGPT, Cursor e Codex descubram ferramentas e as chamem. Um servidor MCP do Telegram expõe ações do Telegram como essas ferramentas, com descrições claras e esquemas de entrada que o modelo consegue seguir.

A Metricgram agora mantém um para você, apoiado pelo bot que já gerencia seus grupos.

O que "adaptar a Telegram Bot API" realmente envolve

No papel, adaptar a Bot API para um agente parece fácil. Na prática, você precisa:

• Hospedar um bot, manter o token em segredo e mantê-lo no ar.
• Receber atualizações por webhooks ou polling.
• Escrever a definição de uma ferramenta para cada endpoint que o agente vai usar.
• Impedir que o agente publique em chats que ele nunca deveria tocar.
• Lidar com limites de taxa, supergrupos migrados e mensagens de erro do Telegram.
• Tornar as novas tentativas seguras, para que uma falha de rede pontual não publique a mesma mensagem duas vezes.
• Registrar o que o agente fez, caso você precise explicar depois.

A maioria das equipes para em "enviar uma mensagem", porque todo o resto exige muita infraestrutura. O resultado é um agente que sabe conversar, mas não consegue de fato gerenciar uma comunidade.

Como funciona o servidor MCP do Telegram da Metricgram

A Metricgram já está dentro dos seus grupos do Telegram como bot administrador (ou como seu próprio bot personalizado). O servidor MCP simplesmente deixa seu cliente de IA usar esse bot por meio de um endpoint hospedado:

1. Conecte seus grupos à Metricgram e dê permissões de administrador ao bot.
2. Adicione o endpoint https://metricgram.com/api/v1/mcp ao seu cliente de IA, por exemplo como conector personalizado no Claude.
3. Entre e aprove o acesso com OAuth. Pronto: sem servidores, webhooks ou tokens para gerenciar. Clientes sem OAuth podem usar uma chave de API, com a configuração abaixo.

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

Quem usa o Claude Desktop pode conectar o mesmo endpoint com o mcp-remote. Os trechos exatos para cada cliente estão na página MCP do seu Manager.

Mais de 70 métodos da Bot API, duas formas de chamá-los

O servidor expõe a Telegram Bot API em duas camadas.

Ferramentas tipadas para o dia a dia

As tarefas comuns têm ferramentas próprias com parâmetros descritivos, o que facilita o uso correto pelos modelos:

• send_telegram_message com tópicos, respostas e botões com URL
• send_telegram_media para fotos, vídeos, GIFs, documentos, áudio e figurinhas
• send_telegram_poll para enquetes e quizzes
• edit_telegram_message, delete_telegram_messages, react_to_telegram_message
• pin_telegram_message e forward_telegram_message
• manage_forum_topic para criar, renomear, fechar, reabrir ou excluir tópicos
• get_telegram_chat e get_telegram_chat_member para dados do chat em tempo real
• handle_telegram_join_request, create_telegram_invite_link e update_telegram_chat_settings

Um gateway completo para a Bot API

Todo o resto passa pelo telegram_bot_api. O agente envia o nome oficial de um método da Bot API e seus parâmetros, por exemplo setChatPermissions, banChatSenderChat, editMessageMedia, hideGeneralForumTopic ou revokeChatInviteLink. A ferramenta complementar telegram_api_methods lista todos os métodos que a chave atual pode usar, então o agente sempre sabe o que está disponível.

Segurança: por que o agente nunca escolhe um chat_id

A decisão de design mais importante é o que o agente não pode fazer.

• O chat é travado. O agente envia um group_id da Metricgram. O servidor obtém o chat_id do Telegram a partir de um grupo que pertence a você e rejeita qualquer outro chat.
• Encaminhamentos e citações são verificados. Uma mensagem só pode ser encaminhada, copiada ou citada a partir dos seus próprios grupos.
• Ações globais do bot ficam de fora. Webhooks, pagamentos, alterações no perfil do bot e sair de um grupo não são expostos.
• Os botões são seguros. Botões inline podem abrir URLs ou copiar texto, mas não podem disparar callbacks para o bot.
• Os escopos acompanham a confiança. telegram:read, telegram:write, telegram:moderate e telegram:admin são separados, e você pode ter várias chaves com poderes diferentes.
• As novas tentativas são idempotentes. As ferramentas de escrita aceitam uma idempotency_key, então uma chamada repetida devolve o primeiro resultado em vez de agir duas vezes.
• Cada chamada é registrada com a ferramenta e o método da Bot API usados.

O agente age como o bot pela Bot API oficial, nunca como sua conta pessoal do Telegram.

Contexto que um bot simples não tem

Um wrapper simples da Bot API consegue agir, mas enxerga pouco. O servidor MCP da Metricgram também expõe inteligência da comunidade:

• Visão geral de análises e séries temporais de atividade
• Membros ativos, histórico de membros e mensagens capturadas
• Rankings e recompensas de gamificação
• Resumos com IA do que aconteceu no grupo
• Saúde dos assinantes do Stripe e renovações em risco

Ou seja, um agente pode responder "quem parou de participar este mês?" e depois enviar a essas pessoas uma mensagem atenciosa, tudo na mesma conversa.

Exemplos de fluxos de trabalho

Anúncio semanal. "Publique o anúncio semanal do AMA no Crypto Talk, fixe sem notificar todo mundo, abra um tópico de perguntas para o AMA e crie um link de convite que expire na sexta-feira."

Varredura de moderação. "Verifique as últimas 200 mensagens em busca de links de spam, apague-as e restrinja os remetentes por 24 horas."

Relatório da comunidade. "Compare a atividade desta semana com a da semana passada, liste os cinco membros mais ativos e publique uma mensagem curta de agradecimento no tópico Geral."

Triagem de pedidos de entrada. "Aprove os pedidos de entrada pendentes de usuários que são assinantes ativos e recuse o restante."

Para quem é

• Donos de comunidades que querem um assistente para o trabalho administrativo rotineiro.
• Agências que gerenciam muitos grupos de clientes e querem um único agente para todos.
• Equipes de suporte e sucesso do cliente que mantêm comunidades de clientes no Telegram.
• Desenvolvedores que querem o Telegram no seu stack de agentes sem manter infraestrutura de bots.

Como começar

O servidor MCP está incluído em todos os planos da Metricgram e no teste grátis de 14 dias, então você pode conectar um agente antes de pagar. A maioria dos clientes se conecta com OAuth: cole a URL do servidor, entre e aprove o acesso. As chaves de API continuam disponíveis para clientes sem OAuth.

Saiba mais na página do servidor MCP do Telegram e na visão geral dos recursos MCP e, em seguida, crie sua primeira chave no Manager.