Como dar um número de telefone ao Claude Code com MCP

Quer que o Claude Code (ou o Cursor, o Windsurf, o VS Code) faça uma chamada ou envie uma SMS diretamente a partir de um prompt, sem escrever código? Basta um comando no terminal para ligar a volai como servidor MCP e, depois, dizer ao editor o que pretende em linguagem corrente: “liga-me para...”, “envia uma SMS para...”. O editor escolhe a ferramenta certa entre as 110 que a volai disponibiliza via MCP e chama-a por si. Sem ler documentação de API, sem código de telefonia à medida.

O que é o MCP e porque funciona sem código?

O MCP (Model Context Protocol) é a forma como um editor com IA vai buscar, em tempo de execução, uma ferramenta de um serviço externo e a utiliza de facto, em vez de apenas falar dela. Assim que a volai está ligada, o editor vê as 110 ferramentas (fazer uma chamada, enviar uma SMS, comprar um número, criar um agente, entre outras) e escolhe a adequada a partir da descrição, com base no que acabou de escrever. Para uma explicação mais aprofundada da ideia de base, veja O que é um servidor MCP e como faz chamadas telefónicas; este artigo trata sobretudo de dar um número de telefone ao Claude Code e de o experimentar logo.

Instalação no Claude Code

Um comando no terminal e fica pronto:

claude mcp add --transport http volai https://volai.eu/mcp \
  --header "Authorization: Bearer vk_A_SUA_CHAVE"

A chave de API (vk_A_SUA_CHAVE) obtém-se no portal da volai, em API e MCP, depois de se registar. Sem uma chave válida, o servidor rejeita o pedido, e o editor avisa-o logo na primeira mensagem.

Cursor e outros editores

O mesmo servidor, com outra sintaxe. Adicione isto a ~/.cursor/mcp.json (ou a .cursor/mcp.json para um único projeto):

{
  "mcpServers": {
    "volai": {
      "url": "https://volai.eu/mcp",
      "headers": {
        "Authorization": "Bearer vk_A_SUA_CHAVE"
      }
    }
  }
}

O Windsurf, o VS Code (Copilot) e o Claude Desktop ligam-se segundo o mesmo princípio, apenas com um formato ligeiramente diferente do ficheiro de configuração; a sintaxe exata de cada um está na página Servidor MCP.

Se o editor não mostrar ferramentas logo após a ligação: costuma ser uma de três coisas. A maioria dos editores só lê a configuração dos servidores MCP no arranque, pelo que a primeira gravação exige um reinício (ou, pelo menos, recarregar a janela ou o projeto). Verifique se a chave que colou tem um espaço perdido no início ou no fim, invisível num terminal ou num ficheiro JSON, mas suficiente para estragar o cabeçalho Authorization. E a forma mais rápida de confirmar que o servidor responde é o prompt exato mais abaixo: quando o editor chamar uma ferramenta, a ligação está a funcionar.

A sua primeira chamada, num só prompt

Depois de ligado, diga ao editor o que pretende, com as suas próprias palavras, mas eis um exemplo concreto:

• ›Liga-me agora para +420777123456 e experimenta o papel de uma linha de encomendas de uma pizaria. Não quero configurar um número nem um agente só para isto.

O editor reconhece isto como a ferramenta make_call com o seu parâmetro systemPrompt: uma chamada de teste, sem número nem agente para configurar de antemão. A chamada parte do número de demonstração partilhado da volai, que é exatamente o que aparece no ecrã de quem atende, e não o seu número, e decorre com a voz predefinida do agente, porque não é possível enviar um voiceId personalizado numa chamada de teste. O systemPrompt está limitado a 1200 caracteres, a chamada é faturada de forma totalmente normal, incluindo o acréscimo do agente (sem desconto), e está limitada a um máximo de 3 chamadas de teste por 24 horas por conta; é necessário um e-mail verificado. Se preferir ligar a partir do seu próprio número, através de um agente seu, basta dizê-lo ao editor: este chamará make_call com agentId em vez de systemPrompt.

A sua primeira SMS, num só prompt

A mesma ideia funciona para mensagens de texto:

• ›Envia uma SMS para +420777123456 a dizer que a consulta está confirmada para amanhã de manhã.

Desta vez, o editor recorre a send_sms: por baixo, é exatamente a mesma chamada que escreveria você próprio contra a API REST (POST /v1/messages {"to": "+420...", "body": "..."}), mas sem escrever código. Sem um número próprio, a SMS sai com o nome de remetente partilhado SMSinfo, apenas para um número checo (+420) ou eslovaco (+421), e os destinatários não podem responder: os números de voz da volai não recebem SMS. Receber SMS e enviar a partir do próprio número (apenas para números checos) é o que faz o complemento número de telemóvel (290 kr sem IVA por 30 dias, no máximo 2 por conta): o editor compra-o com buy_sms_number apenas depois de concordar expressamente com o preço, e lê as mensagens recebidas com list_messages; não garantimos códigos de verificação de serviços. O número para chamadas e SMS também recebe SMS e envia a partir do seu próprio número: uma linha fixa de Praga por 49 kr sem IVA por 30 dias (cobrado quando ficar ativo, normalmente no prazo de 1 dia útil; no máximo 2 por conta), para a qual as pessoas podem ligar e enviar mensagens, e a partir da qual o seu agente faz chamadas e envia SMS. O editor encomenda-o com order_voice_sms_number apenas depois de concordar expressamente com o preço, encaminha as chamadas recebidas com set_voice_sms_number_routing e envia SMS a partir dele com send_sms e o campo fromNumber (apenas números checos, sem relatórios de entrega). As mensagens só funcionam depois do primeiro carregamento de saldo: o crédito de boas-vindas cobre as chamadas de teste, não as SMS.

O que mais pode pedir?

O mesmo padrão funciona para qualquer uma das 110 ferramentas. Mais alguns exemplos:

• “Percorre as minhas últimas dez chamadas e diz-me quais precisam realmente da minha atenção.” - a ferramenta list_calls.
• “Diz-me o meu saldo atual e envia um aviso se estiver a ficar baixo.” - a ferramenta get_balance.
• “Configura um número para a nova filial e põe nele um agente que aceite reservas de mesa.” - buy_number e create_agent, uma a seguir à outra.

A tabela completa das 110 ferramentas, com a descrição de quando o editor usa cada uma, está na página Servidor MCP, e a página Integração com o Claude Code tem alguns prompts prontos para tarefas comuns.

É seguro dar uma chave de API ao editor?

O MCP autentica-se com a mesma chave de API que a API REST e partilha com ela o limite de 60 pedidos por minuto: quem tiver essa chave age na sua conta exatamente como você: compra um número, faz uma chamada, envia uma mensagem ou cria um agente, e tudo isso sai do seu saldo.

As ações pagas (send_sms, make_call, buy_number, buy_sms_number) estão deliberadamente marcadas com idempotentHint: false: chamá-las de novo envia uma segunda SMS ou cobra um segundo montante, pelo que um editor bem comportado não as repete por iniciativa própria após um tempo limite. E, mesmo que um prompt se desviasse para um número que não quer que seja chamado, existe mais uma salvaguarda: a lista de números a não contactar (do-not-call). As ferramentas add_to_dnc, list_dnc e remove_from_dnc protegem números que nenhum agente, integrado ou seu, pode voltar a chamar. Aplica-se às chamadas, não às SMS, e nenhum prompt nem chamada de API a pode contornar.

Cada ferramenta também diz de antemão ao editor como se comporta: se apenas lê (readOnlyHint), se é irreversível (destructiveHint) ou se não deve ser repetida sem pensar (sem indicação de idempotência nas ações pagas). É por isso que um bom editor pergunta antes de apagar um agente ou de cancelar uma cedência de relay não utilizada, enquanto as ferramentas só de leitura (saldo, histórico de chamadas, lista de números) correm sem perguntar, porque não há nada a perder.

Duas coisas que o MCP deliberadamente não pode fazer: libertar um número comprado (DELETE /v1/numbers/{e164}) ou um número de telemóvel (DELETE /v1/sms-numbers/{e164}) só funciona através do portal ou da API REST, para que uma frase mal interpretada não lhe custe o número impresso no seu folheto, e o PDF de uma fatura só se descarrega por REST (as próprias faturas leem-se com list_billing_documents e get_billing_document, e os dados de faturação alteram-se com update_billing_details). Descarregar a gravação de uma chamada também não tem ferramenta própria, pelo mesmo motivo: é um ficheiro de áudio, não JSON, e descarrega-se com a mesma chave de API diretamente por REST.

O guia completo, incluindo as propriedades de segurança de cada ferramenta (aquilo sobre o que um bom cliente pergunta antes de agir), está na página Servidor MCP; as tarifas por minuto e por SMS estão na página de preços.

O que se segue