Como conectar um agente de IA ao Telegram via MCP: guia

Resumo. Antes de qualquer cliente se conectar, três coisas precisam ser verdade: o workspace tem um bot próprio, esse bot é administrador do canal, e o dono apertou Start na conversa privada com ele. Aí você escolhe o caminho — o endereço do servidor https://backend-git-production-cb93.up.railway.app/mcp como conector personalizado com login pelo Telegram, ou uma chave no cabeçalho Authorization vinda de Configurações → Agentes de IA (MCP). Depois vêm catorze ferramentas: cinco leem o canal, sete trabalham com posts, duas leem o público. Nada de produtos, pedidos ou conversas privadas, e nada de nada sem bot. Passos dos clientes verificados em 8 de setembro de 2026.

Esta é a metade prática da comparação de servidores MCP de Telegram: lá se decide se o caminho pelo bot é o que você quer, aqui você conecta e vê o que fazer quando não dá certo.

Antes de conectar

Quase toda recusa acontece aqui, antes da primeira chamada de ferramenta.

O workspace precisa de um bot próprio. O servidor MCP do AdminHub publica pelo bot que o dono do canal criou para o próprio canal — nunca por um bot compartilhado do AdminHub e nunca pela sua conta pessoal. Sem bot as ferramentas não degradam em silêncio: elas recusam com bot_required e um link que cria o bot em um toque, telegram.me/tg_adminhub_bot?startapp=bot. O get_workspace é a exceção e responde mesmo assim, para que um agente consiga descobrir o que está faltando.

O bot tem que ser administrador do canal. Um bot que é apenas membro não consegue publicar, e o Telegram não diz nada sobre isso até um envio falhar. É exatamente por isso que o list_channels traz a marca bot_is_admin em cada canal, e que o create_post rejeita um canal onde ela está desligada, com channel_not_postable, em vez de aceitar um post que se perderia depois.

A conversa privada do dono com o bot tem que estar aberta. Isso vale só para imagens, e a regra é do Telegram, não nossa: um bot só consegue obter um file id de um arquivo que ele mesmo enviou. Por isso o add_post_image baixa a imagem, repassa ela uma vez pela conversa do dono com o bot para pegar esse id, anexa ao post e apaga a mensagem repassada. Se o dono nunca apertou Start ali, a ferramenta recusa antes de baixar qualquer coisa, com owner_bot_not_started.

O efeito colateral merece ser dito em voz alta: toda imagem que um agente anexa chega, por pouco tempo e com notificação, na conversa do dono com o bot dele mesmo. Ela é apagada depois, mas foi entregue, e quem não pediu imagem nenhuma vai se perguntar de onde ela veio. O get_workspace informa owner_dm_open, então dá para checar isso antes de uma chamada falhar.

Duas formas de conectar

Pelo endereço do servidor, sem chave. Para claude.ai, ChatGPT, Claude Desktop e Claude Code. Você adiciona um conector personalizado apontando para https://backend-git-production-cb93.up.railway.app/mcp, abre uma página do AdminHub, e aí você entra com o Telegram, escolhe um workspace e aperta Permitir. Um workspace sem bot aparece na lista mas não pode ser escolhido — não haveria por onde publicar. O acesso cobre as três permissões de uma vez: channel:read, posts:write e audience:read.

Por chave no cabeçalho. Para Claude Code, Cursor e tudo mais que envie um cabeçalho Authorization. Abra Configurações → Agentes de IA (MCP) → Criar chave. Ela aparece exatamente uma vez e não tem segunda olhada: o banco guarda só um hash. Os dois caminhos se revogam no mesmo lugar, e uma conexão revogada para de funcionar na hora.

Uma coisa vale planejar antes: uma chave e uma conexão por endereço contam as duas como conexões, e o Free permite uma.

claude.ai

Customize → Connectors → Add custom connector → cole o endereço → Add. Os padrões de autenticação servem: o servidor aceita tanto os metadados de cliente hospedados pela Anthropic quanto o registro dinâmico, então não há nada para preencher à mão. Depois é só conectar, fazer o login pelo Telegram e ligar o conector no chat onde você quer usá-lo.

Conectores personalizados funcionam no Free, Pro, Max, Team e Enterprise, com o Free limitado a um. No Team e no Enterprise só um Owner adiciona, em Organization settings → Connectors; todo mundo mais se conecta a ele depois, pela própria página de Connectors.

ChatGPT

Os conectores viraram Apps em julho de 2026, e um servidor MCP personalizado ainda precisa do modo de desenvolvedor: Settings → Security and login → Developer mode, e aí você cria o app a partir de Apps, dando a ele o endereço do servidor com OAuth como mecanismo de autenticação. Num workspace, um admin liga o modo de desenvolvedor em Permissions & Roles e publica o app pelas configurações do workspace.

Dois limites para saber antes: isto é um recurso da web e não tem suporte no celular; e o MCP completo — a metade que escreve — está hoje disponível para contas Business e Enterprise/Edu, enquanto uma conta Pro conecta um servidor só com permissões de leitura e fetch. No Pro, espere que as ferramentas de leitura funcionem e as de publicação não.

Claude Desktop

O mesmo fluxo de conectores do claude.ai, não um arquivo de configuração — o claude_desktop_config.json é para servidores stdio locais, e este não é um deles. O Claude alcança um conector remoto pela infraestrutura da própria Anthropic e não pela sua máquina, o que aqui não muda nada, porque este endereço é público.

Claude Code

O Claude Code faz dos dois jeitos, e vale saber disso antes de criar uma chave da qual você talvez nem precise. Com uma:

claude mcp add --transport http adminhub https://backend-git-production-cb93.up.railway.app/mcp --header "Authorization: Bearer <chave>"

Sem chave, adicione o mesmo servidor sem cabeçalho e deixe o Claude Code conduzir o login sozinho:

claude mcp add --transport http adminhub https://backend-git-production-cb93.up.railway.app/mcp

depois rode /mcp e siga o fluxo no navegador. Fique com a chave se a conexão precisa durar mais que uma sessão de navegador; fique com o login se você não quer um segredo dentro de um arquivo de configuração.

Cursor e outros clientes de cabeçalho

O Cursor lê ~/.cursor/mcp.json para todos os projetos e .cursor/mcp.json para um só. Um servidor remoto é uma entrada com url e headers — não existe campo de transporte; é a url que a torna remota:

{
  "mcpServers": {
    "adminhub": {
      "url": "https://backend-git-production-cb93.up.railway.app/mcp",
      "headers": {
        "Authorization": "Bearer ${env:ADMINHUB_MCP_KEY}"
      }
    }
  }
}

O Cursor interpola ${env:...} dentro de url e de headers, então a chave pode morar no ambiente e não num arquivo que você pode acabar comitando. Qualquer outra coisa que fale Streamable HTTP conecta igual: o endereço, mais a chave como bearer token.

As catorze ferramentas

Ferramenta	O que faz
get_workspace	Workspace, plano, status do bot, owner_dm_open, posts via MCP usados no mês
list_channels	Todos os canais, com número de inscritos, bot_is_admin e is_active
get_channel_stats	Totais e entradas e saídas dia a dia, janela de até 90 dias
list_posts	Posts recentes, filtráveis por canal ou status
get_post	O texto de um post, o status de entrega e o erro por canal
create_post	Texto para um ou mais canais: rascunho, agendado ou já enviado
publish_post	Envia um rascunho salvo
update_post	Reescreve texto, título ou horário de um post em rascunho, agendado ou falhado
edit_published_post	Reescreve um post que já está no canal
cancel_post	Apaga um post em rascunho, agendado ou falhado — os publicados ficam
retry_post_delivery	Repete o envio nos canais onde a entrega falhou ou foi cancelada
add_post_image	Anexa uma imagem a partir de uma URL, repassada pela conversa do dono
list_subscribers	Os inscritos de um canal por nome, username e id do Telegram
get_subscriber	O mesmo para uma pessoa

O texto do post é HTML do Telegram, nunca Markdown, e horários agendados têm que trazer um deslocamento UTC. A publicação vai por fila: as ferramentas de escrita retornam na hora e a entrega vem em até um minuto, então o resultado se lê de volta pelo get_post.

O que ele não faz

Nada de produtos, nada de pedidos, nada de mini-CRM, nada de base de conhecimento — as metades de comércio e de suporte com IA do AdminHub simplesmente não são expostas pelo MCP. Nada de conversas privadas, nada de chats arbitrários, nada de histórico de mensagens: nenhuma ferramenta aqui encosta numa conversa, e é essa a diferença inteira entre isto e um servidor userbot.

Os dados de público merecem linha própria, porque a fronteira dentro deles é fácil de não notar. Nomes, usernames e ids do Telegram voltam sob audience:read; gasto e valor de vida não vêm junto, aparecendo só quando o agente passa include_spend naquela chamada. É uma fronteira proposital, e a hora de pesá-la é antes de conectar, não depois que um agente resumiu os seus melhores clientes.

Quando não funciona

Todas as ferramentas recusam com bot_required. O workspace não tem bot. O erro já traz o link, e nada mais funciona enquanto o bot não existir.

Um post foi criado mas nunca chegou. Espere um minuto — a entrega vai por fila — e chame o get_post para ler o status e o error de cada canal. A causa de sempre é um bot que não é mais administrador ali. Devolva os direitos e depois retry_post_delivery.

Uma imagem não anexa. owner_bot_not_started significa que o dono nunca abriu uma conversa privada com o bot do workspace. Peça para ele abrir e apertar Start; o owner_dm_open no get_workspace confirma. O owner_unreachable é o caso vizinho — a conversa estava aberta e o bot foi bloqueado desde então.

plan_limit_reached. O Free permite uma conexão e trinta posts criados via MCP por mês. O contador conta a criação, então rascunhos também contam; posts cuja entrega falhou, não. O limite de conexões vale para os dois caminhos — uma chave e uma conexão por endereço ocupam igualmente a única vaga — e a segunda é recusada na criação, não na hora da chamada. O Pro não tem nenhum dos dois limites.

O agente não consegue ver os inscritos. Ou a conexão não tem audience:read — chaves emitidas antes dessa permissão existir carregam só as duas antigas, e a correção é uma chave nova — ou o cliente pediu um conjunto parcial de permissões durante o login, o que este servidor recusa por inteiro em vez de conceder um acesso silenciosamente estreitado. Reconecte pedindo as três.

A página do MCP traz o endereço, a lista de ferramentas e as perguntas frequentes; a chave está a dois toques nas configurações.

Fontes

Passos dos clientes verificados em 8 de setembro de 2026 na documentação dos próprios fornecedores: a central de ajuda e a documentação de conectores da Anthropic para claude.ai e Claude Desktop, a documentação de MCP do Claude Code para o claude mcp add, o guia de modo de desenvolvedor e a central de ajuda da OpenAI para os apps do ChatGPT, e a documentação de MCP do Cursor para o formato do mcp.json. O comportamento do próprio AdminHub — as catorze ferramentas, as recusas citadas acima, as permissões e os limites do Free — vem da página do MCP.