Servidor MCP de telefonia para IA agentiva e modelos de linguagem

Introdução ao MCP (Protocolo Modelo-Contexto)

O Protocolo Modelo-Contexto (MCP) é uma especificação que permite que grandes modelos de linguagem (LLMs) identifiquem e utilizem ferramentas e serviços externos. Pense nele como uma linguagem universal que permite que os LLMs se comuniquem com APIs, bancos de dados e outras Applications de maneira padronizada.

Neste tutorial, você aprenderá a criar ferramentas MCP que podem se integrar a qualquer aplicativo de IA da Agentic (como o Claude Desktop, o GitHub Copilot ou o Cursor) e que são capazes de fazer chamadas, enviar SMS e coletar as respostas para que sejam exibidas no aplicativo.

>> Resumo: Você pode encontrar o código completo e funcional no GitHub.

Animated view of Claude’s developer-friendly welcome screen asking, 'How was your day, Mr. Developer?' with contextual mode options like Code, Write, and Learn.

Por que o MCP é útil?

• Extensibilidade: O MCP permite que os desenvolvedores ampliem as capacidades dos LLMs além do conhecimento integrado. Ao criar ferramentas compatíveis com o MCP, é possível capacitar um modelo a acessar informações em tempo real (como previsões meteorológicas ou cotações de ações), interagir com bases de conhecimento privadas ou acionar ações em outros sistemas (como enviar um e-mail ou agendar uma reunião).

• Padronização: Ela proporciona uma maneira consistente para que os modelos interajam com as ferramentas, independentemente da implementação subjacente. Isso simplifica o processo de desenvolvimento tanto para os criadores de ferramentas quanto para os desenvolvedores de modelos.

• Segurança e Controle: O MCP permite um controle granular sobre quais ferramentas um modelo pode acessar, garantindo que o modelo execute apenas as ações para as quais está autorizado.

Pré-requisitos

• Conhecimento em Python: Conhecimento intermediário da linguagem de programação Python e Python v3.13+.

• Docker Desktop: O aplicativo será executado em um ambiente em contêineres e utiliza o Docker Compose.

• Claude Desktop Aplicativo: Este tutorial utiliza o Clause, mas qualquer aplicativo de IA agênica, como o Cursor, o Windsurf ou o GitHub Copilot, que vem com o VSCode, também pode ser usado.

• Account da API da Vonage: Para fazer chamadas e se comunicar por SMS, é necessária uma conta da Vonage. Isso inclui uma chave de API, um segredo de API, um número virtual longo e um aplicativo de voz que pode ser criado a partir do painel de controle da Vonage.

• Proxy reverso Ngrok: Para atuar como Webhook na coleta de eventos, como andamento de chamadas e SMS recebidos.

Como funciona o MCP: um exemplo de ferramenta meteorológica

Para entender como o MCP funciona, vamos considerar um exemplo simples: um servidor de previsão do tempo. A interação é gerenciada por um Cliente MCP, que é executado localmente como um plug-in do LLM ou do aplicativo de IA Agentic. Esse cliente é responsável pela comunicação com o servidor MCP remoto.

1. Solicitação do usuário: Um usuário pergunta ao LLM: “Como está o tempo em Londres?”

2. Do LLM para o MCP Client: O LLM compreende a intenção do usuário e utiliza seu plug-in local do MCP Client para encontrar uma ferramenta adequada.

3. Descoberta de ferramentas (Cliente → Servidor): O Cliente MCP envia uma solicitação ao Servidor MCP para descobrir as ferramentas disponíveis.

4. Seleção de ferramentas: O servidor MCP responde com uma lista de ferramentas, incluindo get_weather(location: str). O LLM, por meio do cliente, seleciona essa ferramenta.

5. Chamada da ferramenta (Cliente → Servidor): O Cliente MCP envia uma solicitação ao Servidor MCP para executar a função get_weather com o parâmetro location="Londres".

6. Execução: O servidor MCP recebe a solicitação, executa a função subjacente (que, por sua vez, chama uma API meteorológica) e obtém as condições meteorológicas atuais em Londres.

7. Resposta (Servidor → Cliente → LLM): O servidor envia o resultado (por exemplo, “O tempo em Londres está em 15 °C e nublado.”) de volta ao Cliente MCP, que, por sua vez, o repassa ao LLM.

8. Resposta final: O LLM organiza essas informações em uma resposta de fácil compreensão e a apresenta ao usuário.

Este fluxo de trabalho demonstra como o Cliente MCP atua como uma ponte local, enquanto o Servidor MCP fornece a funcionalidade real da ferramenta, criando uma conexão integrada entre o modelo de linguagem e os recursos externos.

Sequence diagram showing how a user query about London's weather flows through an LLM, MCP Client, MCP Server, and Weather API to return a response.

O que é um servidor MCP de telefonia?

O Telephony MCP Serveé um servidor baseado em Python que disponibiliza as funcionalidades de comunicação da Vonage como um conjunto de ferramentas por meio do Protocolo Modelo-Contexto. Ele atua como um intermediário, traduzindo solicitações de um modelo de linguagem em chamadas de API para a plataforma da Vonage e retornando os resultados.

Este servidor MCP utiliza o conjunto de APIs de comunicação da Vonage. Essas APIs permitem que você, por meio de programação, faça e receba chamadas telefônicas, envie mensagens como RCS, SMS e WhatsApp, desenvolva aplicativos de vídeo com WebRTC e muito mais.

O uso dessas APIs permite que um modelo de linguagem, como o Claude, realize ações de telefonia, como fazer chamadas e enviar mensagens de texto, simplesmente utilizando as ferramentas fornecidas pelo servidor.

Lista de ferramentas da Vonage no servidor MCP de telefonia

O Servidor MCP de Telefonia vem com um conjunto de ferramentas pré-configuradas para tarefas comuns de telefonia:

• voice_call(para: str, mensagem: str, de: str = "VONAGE_LVN"): Inicia uma chamada de voz para um número especificado e reproduz uma mensagem.

• send_sms(para: str, texto: str, de: str = "VONAGE_LVN"): Envia uma mensagem SMS para um número especificado.

• check_call_status(call_uuid: str = None): Verifica o status de uma chamada específica ou lista todas as chamadas ativas.

• voice_call_with_input(to: str, prompt_message: str, from_: str = "VONAGE_LVN", wait_for_result: bool = True): Realiza uma chamada de voz, reproduz uma mensagem de prompt e utiliza o reconhecimento de voz para capturar a resposta do destinatário.

• sms_with_input(para: str, texto: str, de: str = "VONAGE_LVN", aguardar_resultado: bool = True): Envia uma mensagem SMS e aguarda uma resposta do destinatário.

Como funciona a ferramenta send_sms

Vamos explicar passo a passo como usar o ferramenta send_sms com um modelo de linguagem como o Claude, que interage com o servidor por meio de um Cliente MCP.

1. Usuário: “Ei, Claude, você poderia mandar uma mensagem para meu amigo no número +1-202-555-0183 e avisar que vou me atrasar 10 minutos para a nossa reunião?”

2. Claude (LLM): Entende a intenção do usuário de enviar um SMS. Ele sabe, por meio de sua integração com o MCP, que um ferramenta send_sms está disponível.

3. Claude (Uso de ferramentas por meio do cliente MCP): Por meio de seu cliente MCP local, o Claude faz uma solicitação ao servidor MCP de telefonia, invocando o método ferramenta com os parâmetros:

   • para: “+12025550183”

   • texto: “Oi, vou me atrasar 10 minutos para a nossa reunião.”

4. Servidor MCP de Telefonia: Recebe a solicitação do Cliente MCP. Em seguida, cria e envia uma solicitação de API para a SMS API da Vonage com os detalhes fornecidos.

5. API da Vonage: Processa a solicitação e envia a mensagem SMS para o celular do destinatário. Em seguida, retorna um status de sucesso ao servidor MCP de telefonia.

6. Servidor MCP de telefonia para o cliente: O servidor formata o status de sucesso recebido da Vonage e o reenvia ao cliente MCP.

7. Claude (Resposta): O Cliente MCP repassa a confirmação de sucesso para Claude, que então informa ao usuário: “Ok, enviei a mensagem para o seu amigo.”

Sequence diagram illustrating how Claude uses MCP and the Vonage SMS API to send a message on behalf of a user.

Como configurar o servidor MCP de telefonia

Passo 1: Clonar o repositório

git clone https://github.com/Vonage-Community/telephony-mcp-server
cd telephony-mcp-server

Etapa 2: Abrir um túnel ngrok

Para receber webhooks da Vonage, seu servidor local precisa estar acessível pela internet. Use o ngrok para expor seu servidor, abra uma nova aba no seu terminal e execute:

ngrok http 8080

O resultado será algo assim:

Session Status                online
Version                       3.22.1
Forwarding                    https://4cc705fd88d9.ngrok.app -> http://localhost:8080

No exemplo acima, o ngrok criou e atribuiu um nome de domínio acessível pela Internet https://4cc705fd88d9.ngrok.app, que pode redirecionar o tráfego para o servidor de callback hospedado localmente e em execução na porta 8080. Vamos usá-lo no arquivo de configuração .env da seguinte forma:

CALLBACK_SERVER_URL=https://4cc705fd88d9.ngrok.app

Você pode ler mais sobre testes com o ngrok nas ferramentas do nosso portal para desenvolvedores.

Etapa 3: Criar um aplicativo da Vonage

Faça login no Painel do Desenvolvedor da Vonage e crie um novo aplicativo. Gere e baixe um arquivo private.key e coloque-o na raiz do diretório do projeto. Ele será copiado para o contêiner do Docker.

Ative os recursos “Voice” e “Mensagens”, conforme mostrado abaixo. Você também precisará configurar os endpoints de webhook para cada recurso; no entanto, como não vamos usar esses endpoints de fato, basta adicionar marcadores de posição.

Para voz:

• URL da resposta: https://4cc705fd88d9.ngrok.app/ncco

• URL do evento: https://4cc705fd88d9.ngrok.app/event

Para mensagens:

• URL de origem: https://4cc705fd88d9.ngrok.app/event

• URL de status: https://4cc705fd88d9.ngrok.app/event

Creating a Vonage application for a Telephony MCP Server in the Vonage API Dashboard, showing the configuration of Voice and Messages capabilities, webhook URLs, and key generation.

Etapa 4: Adicionar um webhook de entrada para receber SMS

No Painel do Desenvolvedor da Vonage, acesse Seus Numbers e edite o número que deseja usar clicando no ícone do lápis. Na seção “URL do webhook de entrada” na janela de configuração, adicione a URL do ngrok seguida de “/event”, por exemplo: https://4cc705fd88d9.ngrok.app/event.

Configuring the inbound SMS webhook URL for a Vonage virtual number in the Dashboard under 'Your Numbers' settings.

Depois de salvar a configuração, qualquer SMS enviada para o número virtual acima será encaminhada para https://4cc705fd88d9.ngrok.app/event

Etapa 5: Adicione suas credenciais da Vonage

Crie um arquivo chamado .env na raiz do projeto.

touch .env

Preencha-o com suas credenciais da Vonage:

VONAGE_API_KEY=your_api_key
VONAGE_API_SECRET=your_api_secret
VONAGE_APPLICATION_ID=your_application_id
VONAGE_PRIVATE_KEY_PATH=/app/private.key # Path inside the container
VONAGE_LVN=your_vonage_long_virtual_number
CALLBACK_SERVER_URL=https://<ngrok_generated_url>

Inicie o servidor MCP de telefonia com o Docker

O projeto utiliza o Docker Compose para simplificar a execução dos serviços necessários.

1. Compilar e iniciar o contêiner

Na raiz do diretório do projeto, execute o seguinte comando:

docker-compose up --build

Este comando irá:

1. Crie uma única imagem do Docker para o aplicativo.

2. Inicie um contêiner que execute dois serviços internamente: o telephony-mcp-server e o callback-server, cada um em uma porta diferente.

3. Os serviços serão iniciados em primeiro plano, permitindo que você monitore seus logs diretamente no seu terminal.

2. Verifique se os servidores estão em funcionamento

• O servidor MCP de telefonia estará disponível em http://localhost:8000.

• O servidor de callback estará em execução em http://localhost:8080.

Integração do servidor MCP de telefonia com o Claude

É possível integrar o servidor MCP de telefonia ao Claude por meio de clientes compatíveis com MCP, como o aplicativo Claude Desktop.

• Abrir as configurações do Claude Desktop: Navegue até Claude > Configurações > Desenvolvedor > Editar configuração para abrir claude_desktop_config.json .

Step-by-step instructions to access and edit the Claude desktop MCP configuration file via Developer Settings.

• Adicionar configuração do servidor MCP de telefonia: Insira o seguinte JSON em claude_desktop_config.json:

{
  "mcpServers": {
    "telephony": {
      "command": "npx",
      "args": [
        "mcp-remote",
        "http://127.0.0.1:8000/mcp"
      ]
    }
  }
}

Salve o arquivo JSON, feche e reinicie o Claude para que essas alterações entrem em vigor.

• Verifique se o Claude está conectado: Vá para Claude > Configurações > Desenvolvedor. Deve haver uma entrada chamada “telephony” com o status “em execução”.

Claude's Developer settings showing the 'telephony' tool actively running with an MCP remote endpoint configured via NPX.

Executando as ferramentas do MCP no Claude Desktop

Depois de integrada, você pode começar a dar comandos ao Claude que utilizem as ferramentas de telefonia. Você pode verificar a disponibilidade das ferramentas no menu “Pesquisa e Ferramentas”:

Screenshot showing Claude’s prompt interface with MCP tools like send_sms and voice_call enabled via the tools menu.

Vamos imaginar que você queira perguntar a um amigo se ele está livre para jantar. Tente enviar ao Claude o seguinte comando: “Envie uma mensagem para a Jane no número +1-202-555-0125 e pergunte se ela está livre para jantar hoje à noite.”

O Claude reconhecerá a intenção e a ferramenta necessária. Ele pode exibir uma mensagem de confirmação antes de executar:

Tool: send_sms
to: "+12025550125"
text: "Hi Jane, are you free for dinner tonight?"

[Execute] [Cancel]

Depois que você aprovar, Claude usará a ferramenta e lhe dará uma confirmação final:

"Enviei a mensagem para a Jane."

Mais tarde, você poderia usar outra ferramenta:

"Ligue para a Jane para saber se ela recebeu minha mensagem."

E Claude usava a ferramenta voice_call para conectar você.

Conversation with Claude using the sms_with_input MCP tool to send and follow up on a message asking if someone likes ice cream.

Conclusão e considerações finais

O Servidor MCP de Telefonia é um exemplo poderoso de como o Protocolo Modelo-Contexto pode preencher a lacuna entre modelos de linguagem avançados e ações do mundo real. Ao oferecer uma maneira padronizada para que os LLMs acessem APIs de comunicação, abrimos caminho para uma nova classe de Applications em que assistentes de IA podem interagir com o mundo em nosso nome de maneira significativa e tangível.

Este projeto não serve apenas como uma ferramenta prática, mas também como um modelo para ampliar as capacidades dos modelos de linguagem a qualquer domínio que possua uma API. As possibilidades são limitadas apenas pela nossa imaginação.

Tem dúvidas ou comentários sobre este tutorial? Baixe o código e outros projetos incríveis em Comunidade Vonage. Sempre valorizamos a participação da comunidade. Compartilhe suas ideias conosco no X (antigo Twitter) ou participe da discussão no nosso canal do Slack da Comunidade Vonage , mencionando este artigo para obter uma resposta rápida. Você também pode entrar em contato com mim no Twitter.