Telerivet MCP

npx add-mcp 'https://api.telerivet.com/mcp'

Telerivet fornece um servidor do Model Context Protocol (MCP) que permite que agentes de IA e ferramentas baseadas em LLM, como Claude e ChatGPT, interajam com a API REST do Telerivet usando a interface padrão do MCP.

O servidor MCP do Telerivet permite que agentes de IA realizem uma ampla variedade de ações no Telerivet, incluindo enviar e agendar mensagens, recuperar dados e estatísticas de uso, importar contatos e configurar projetos, rotas e serviços automatizados.

O endpoint MCP está disponível em:

https://api.telerivet.com/mcp

Os clientes MCP se conectam por meio do transporte Streamable HTTP, usando mensagens JSON-RPC 2.0 em solicitações HTTP POST.

Configuração do cliente

O endpoint MCP exige autenticação via OAuth 2.0.

Os clientes MCP compatíveis com OAuth Client ID Metadata Documents (CIMD) podem se conectar sem nenhuma configuração manual: o Telerivet os registra automaticamente na primeira vez que um usuário os autoriza. O Telerivet não oferece suporte ao Dynamic Client Registration.

As instruções de configuração estão disponíveis para os seguintes clientes MCP:

• Claude (claude.ai e Claude Desktop)
• Claude Code
• ChatGPT
• Codex
• Antigravity CLI
• Hermes Agent

Para clientes MCP que não oferecem suporte a Client ID Metadata Documents, é necessário configurar manualmente um OAuth Client. Para permitir o uso de outro cliente MCP que não ofereça suporte a CIMD, você pode adicionar um novo OAuth Client à sua organização Telerivet e configurar as URLs de callback OAuth exigidas pelo cliente MCP. (O serviço que fornece o cliente MCP pode especificar as URLs de callback OAuth na documentação.) Quando um OAuth Client é configurado manualmente dessa forma, ele só fica acessível aos usuários da sua própria organização Telerivet.

Autorizar um cliente MCP

Ao conectar um cliente MCP, ele redireciona você ao Telerivet para autorizar o acesso. Nesta página, você escolhe:

• Permissões – quais tipos de dados e ações o aplicativo pode acessar (por exemplo, Visualizar mensagens, Enviar mensagens ou Editar serviços automatizados). Desmarque qualquer permissão que não queira conceder ao aplicativo. O aplicativo nunca pode fazer mais do que o permitido pela sua própria conta de usuário, e os métodos da API que exigem uma permissão não concedida ficam ocultos para o cliente MCP.
• Organização – qual das suas organizações o aplicativo pode acessar. Cada autorização abrange uma única organização; para usar o aplicativo com outra organização, conecte-o novamente.

Aprovar aplicativos para sua organização. Cada cliente MCP (como Claude ou ChatGPT) precisa ser aprovado por um administrador da organização antes de poder ser usado nela. Se você for administrador da organização, a página de autorização permitirá aprovar o aplicativo para sua organização e escolher Quem pode usar este aplicativo?: todos os usuários da organização, somente administradores da organização ou somente administradores da organização e dos projetos. Outros usuários verão uma mensagem solicitando que entrem em contato com um administrador da organização para aprovar o aplicativo.

Revogar acesso. Você pode revogar a qualquer momento o acesso de um aplicativo à sua própria conta na seção Aplicativos autorizados das configurações de Segurança da conta. Os administradores da organização podem revisar e revogar os tokens de acesso de todos os usuários na página Tokens de acesso OAuth ou revogar completamente um aplicativo na página Aplicativos conectados.

Controles da organização

Os administradores da organização podem controlar o que cada cliente MCP aprovado pode fazer na organização na página Aplicativos conectados (também vinculada à página Developer API da organização). Clique em um aplicativo para visualizar ou alterar suas configurações. Essas configurações se aplicam ao acesso de todos os usuários a esse aplicativo na organização, independentemente das permissões concedidas pelos usuários ao conectá-lo.

Permissão necessária – quais usuários da organização podem autorizar o aplicativo (todos os usuários, somente administradores da organização ou somente administradores da organização e dos projetos).

Ações permitidas – para cada categoria de ação, se o aplicativo pode executá-la por conta própria, se um usuário precisa aprovar cada ação ou se ela não é permitida:

Ação	Descrição	Opções	Padrão
Leitura de dados	Consultar contatos, mensagens, estatísticas e outros dados do projeto.	Permitido, Não permitido	Permitido
Criação e atualização de dados	Criar e editar contatos, grupos, serviços, campanhas em rascunho, rotas e outros dados do projeto.	Permitido, Exigir aprovação, Não permitido	Permitido
Envio de mensagens e acionamento de serviços	Enviar ou agendar mensagens e chamadas para contatos, acionar serviços automatizados e executar scripts.	Permitido, Exigir aprovação, Não permitido	Exigir aprovação
Exclusão de dados	Excluir contatos, mensagens, serviços e outros dados do projeto.	Permitido, Exigir aprovação, Não permitido	Exigir aprovação
Fazer solicitações web externas	Fazer solicitações a sites externos e APIs de terceiros a partir de scripts executados por este aplicativo.	Permitido, Não permitido	Permitido

Quando uma categoria está definida como Não permitido, a ferramenta MCP correspondente (como send_api ou delete_api) fica oculta para o cliente MCP, e qualquer solicitação da API nessa categoria é recusada. A ferramenta run_script segue a configuração mais restritiva entre envio, criação/atualização e exclusão de dados.

Alguns aplicativos especificam seus próprios padrões – por exemplo, um agente autônomo que precisa enviar mensagens sem a presença de um usuário. Quando o padrão de um aplicativo difere do padrão geral, a página Aplicativos conectados indica o padrão do aplicativo ao lado da configuração. A configuração da sua organização sempre prevalece.

Permissões permitidas – os tipos de dados e ações que o aplicativo pode acessar nesta organização. Desmarcar uma permissão bloqueia as ações correspondentes da API para todos os usuários do aplicativo na organização, mesmo que um usuário tenha concedido essa permissão ao conectá-lo.

Revogar acesso – remove o aplicativo da lista de aplicativos aprovados da sua organização e revoga todos os tokens de acesso existentes para ele na organização.

Os aplicativos pertencentes à sua própria organização (adicionados por meio de Adicionar OAuth Client) não precisam de aprovação, e suas ações permitidas são configuradas na própria página de configurações do aplicativo.

Confirmação com intervenção humana

Quando uma categoria de ação está definida como Exigir aprovação na página Aplicativos conectados, o cliente MCP não pode executar essas ações até que um usuário aprove explicitamente cada uma delas. Por padrão, isso se aplica ao envio de mensagens e ao acionamento de serviços, bem como à exclusão de dados.

As ações da categoria de envio incluem enviar ou agendar mensagens e chamadas, reenviar mensagens, acionar serviços automatizados, criar tarefas em lote, simular mensagens recebidas, editar mensagens ou campanhas agendadas, ativar um serviço automatizado ou alterar a configuração de um serviço ativo, criar webhooks ou alterar URLs de webhooks, alterar o número de telefone ou as configurações do provedor de uma rota, alterar a rota padrão do projeto e executar scripts com a ferramenta run_script. A categoria de exclusão inclui todos os métodos de exclusão, bem como a redução do período de retenção de mensagens de um projeto.

Dependendo do cliente MCP, você pode aprovar uma ação de uma das seguintes maneiras:

Solicitação de aprovação no cliente MCP

Se o cliente MCP oferecer suporte a MCP elicitation (usando a versão 2026-07-28 ou posterior do protocolo MCP), ele solicitará que você aprove a ação diretamente, com uma descrição em linguagem simples do que ela fará e de qual projeto será afetado. Se você aprovar, a ação será executada imediatamente. Se você recusar, a ação não será executada e o modelo de IA será instruído a não tentar novamente.

Rascunhos de mensagens

Se o cliente MCP oferecer suporte à extensão MCP Apps, o modelo de IA poderá usar a ferramenta draft_message para mostrar um rascunho editável de uma mensagem de texto, incluindo os destinatários. Clicar em Enviar aprova o envio exato dessa mensagem para esses destinatários.

Link de aprovação

Se o cliente MCP não oferecer suporte a nenhuma das opções acima, ou se a ação não puder ser aprovada dessa forma, o modelo de IA receberá um link para uma página Aprovar ação no aplicativo web do Telerivet e deverá pedir que você a abra. Essa página mostra o aplicativo, o projeto, uma descrição da ação e os detalhes completos da solicitação. Depois de clicar em Aprovar, volte ao cliente MCP e peça que ele tente novamente.

Para aprovar uma ação, você precisa ter a permissão exigida pela própria ação (por exemplo, permissão para enviar mensagens no projeto). Aprovar uma ação não concede permissões adicionais ao aplicativo.

Como as aprovações funcionam

• Cada aprovação se aplica a uma solicitação exata – o mesmo método da API com os mesmos parâmetros – e só pode ser usada uma vez. Se o modelo de IA alterar qualquer aspecto da solicitação, será necessário aprová-la novamente.
• As aprovações expiram após 1 hora.
• As solicitações da API feitas por um script aprovado por você por meio de run_script não exigem aprovação separada.
• Se o aplicativo chamar a API REST diretamente com seu token de acesso (em vez de usar o MCP), as solicitações que exigem aprovação falharão com o código de erro confirmation_required, e a mensagem de erro incluirá um link de aprovação. Aplicativos que precisam executar essas ações sem a presença de um usuário (como integrações do lado do servidor ou agentes autônomos) exigem que um administrador da organização defina a categoria como Permitido.

Revisão de mensagens. Independentemente do que foi descrito acima, se a Revisão de mensagens estiver ativada nas configurações de mensagens de um projeto, as mensagens enviadas pela API (inclusive pelo MCP) que excederem os limites configurados ficarão retidas como mensagens pendentes até que um revisor as aprove, assim como as mensagens enviadas pelo aplicativo web.

Ferramentas

Atualmente, o servidor MCP disponibiliza as seguintes ferramentas:

• list_api_methods – Lista os métodos de API disponíveis com nome, descrição e resumo dos parâmetros. Permite filtrar por categoria.
• get_method_schema – Retorna o esquema completo dos parâmetros e as descrições dos campos de resposta de um método de API específico.
• read_api – Executa um método de API somente leitura para recuperar dados.
• modify_api – Executa um método de API que cria ou atualiza dados.
• delete_api – Executa um método de API que exclui dados.
• send_api – Executa um método de API que envia, agenda ou recebe mensagens, invoca serviços automatizados ou realiza tarefas em lote.
• run_analysis_script – Executa JavaScript somente leitura no sandbox da Cloud Script API da Telerivet para analisar dados do projeto – útil para agregações, junções entre tipos de entidade ou para percorrer muitos registros sem paginá-los todos pelo modelo. O acesso à API é somente leitura e as solicitações HTTP de saída estão desativadas.
• run_script – Executa JavaScript com acesso à Cloud Script API (leituras, gravações, envios e solicitações HTTP), para operações em lote que, de outra forma, exigiriam muitas chamadas individuais à API. As solicitações à API feitas por scripts são verificadas em relação aos escopos do token OAuth, portanto, os scripts nunca podem fazer mais do que o token que os executou permite.
• get_web_app_urls – Retorna informações sobre a funcionalidade do aplicativo web e os padrões de URL. Permite que agentes de IA gerem links para funcionalidades que não estão disponíveis diretamente pela API. Sem uma consulta, retorna um índice compacto de todas as páginas; a busca por palavras-chave ou caminho de URL retorna detalhes completos das páginas correspondentes.
• draft_message – Cria um rascunho de mensagem de texto simples para um ou mais números de telefone (ou um grupo de contatos) e solicita a aprovação do usuário antes do envio (consulte Rascunhos de mensagens). Disponível somente se o cliente MCP oferecer suporte à extensão MCP Apps.
• get_route_options – Retorna informações sobre as opções disponíveis de rota/canal de mensagens. Filtrar por país, tipo de canal ou caso de uso (ou consultar um tipo de rota específico) retorna detalhes completos, incluindo disponibilidade geográfica, requisitos de conformidade, processo de registro, modalidades de cobrança (gerenciada internamente/pela Telerivet ou externa/BYOC), prazos de configuração e preços.
• skillbook_search / skillbook_get – Retorna informações sobre padrões de solução comuns, serviços, tipos de campanha, recursos da plataforma e modelos de mensagem que correspondem a uma intenção ou caso de uso.
• search_documentation / get_documentation – Pesquisa e recupera entradas do acervo de documentação da Telerivet, incluindo artigos de ajuda do Guia do Usuário, páginas jurídicas/de políticas, documentação da API para desenvolvedores e conteúdo de marketing/empresa em www.telerivet.com.

As ferramentas e os métodos de API disponibilizados pelo servidor MCP podem mudar com o tempo.

Os links abaixo mostram o JSON retornado pelo servidor MCP, o que pode ajudar a entender as ferramentas e os métodos de API disponíveis:

• Definições das ferramentas
• Saída da ferramenta list_api_methods
• Saída da ferramenta get_method_schema para o método Project_queryContacts (substitua o último componente da URL para ver o esquema de outros métodos de API)
• Saída da ferramenta get_documentation para a referência da Cloud Script API (substitua o último componente para ver outras entradas da documentação)

Os escopos concedidos ao seu token OAuth, juntamente com os controles da sua organização para o aplicativo, determinam quais ferramentas e métodos de API estão disponíveis. Métodos que exigem um escopo que seu token não possui, ou que sua organização não permite para o aplicativo, serão excluídos da lista.