Wavix

Servidor MCP Wavix

Um servidor Model Context Protocol que dá a LLMs e agentes de IA acesso direto à plataforma de telecomunicações Wavix — SMS/MMS, chamadas de voz, 2FA, troncos SIP, gerenciamento de números de telefone, registro 10DLC, gravações de chamadas, análise de fala e faturamento.

Wavix é uma plataforma global de comunicações para envio de SMS, realização de chamadas de voz e execução de fluxos 2FA por meio de uma única API. Um teste gratuito está disponível; o uso pago segue o plano de preços da Wavix vinculado à sua conta.

A maneira mais rápida de usar este servidor MCP é o endpoint hospedado em https://mcp.wavix.com/mcp — aponte qualquer cliente compatível com MCP para ele e autentique com sua chave de API Wavix. Se você precisar hospedar por conta própria (implantação Wavix personalizada, atrás de firewall, instância dedicada), consulte Execute o seu próprio.

Sumário

• Endpoint
• Instalação — instalação em um clique, Claude Code, Claude Desktop / Web, Cursor, VS Code, Codex CLI, Windsurf
• Execute o seu próprio (hospedagem própria)
• Exemplos
• Ferramentas → catálogo completo em TOOLS.md
• Recursos
• Autenticação (melhores práticas, se um token for comprometido)
• Solução de problemas
• Compatibilidade e limites
• Suporte, Contribuição, Segurança, Licença

Endpoint

Campo	Valor
URL	https://mcp.wavix.com/mcp
Transporte	Streamable HTTP
Autenticação	Authorization: Bearer <api_key>
Ferramentas	consulte TOOLS.md
Recursos	Documentação Wavix + especificação OpenAPI (descoberta automática)

Obtenha uma chave de API Wavix no Console Wavix → Administração → Chaves de API → Criar nova.

Instalação

Antes de começar: pegue sua chave de API Wavix.

1. Faça login em https://wavix.com.
2. Abra Administração → Chaves de API.
3. Clique em Criar nova (ou copie uma chave existente). Mantenha-a à mão — você a colará no lugar de YOUR_API_KEY abaixo.

Instalação em um clique

⚠️ Os botões abaixo inserem um token provisório YOUR_API_KEY na configuração MCP do seu editor. Após o editor concluir a instalação, abra a configuração gerada e substitua o token provisório pela sua chave de API real antes de enviar qualquer solicitação — caso contrário, todas as chamadas retornarão 401 Unauthorized.

Para remover depois: abra o mesmo arquivo de configuração (~/.cursor/mcp.json, .vscode/mcp.json ou o equivalente para o seu editor) e exclua a entrada wavix, ou remova o conector pela interface de MCP / Conectores do seu editor.

Claude Code

claude mcp add --transport http wavix https://mcp.wavix.com/mcp \
  --header "Authorization: Bearer YOUR_API_KEY"

Use claude mcp list para verificar e /mcp dentro de uma sessão para ver o status.

Claude Desktop / Claude Web

Configurações → Conectores → Adicionar conector personalizado:

• Nome: Wavix
• URL: https://mcp.wavix.com/mcp
• Transporte: Streamable HTTP
• Cabeçalho de autenticação: Authorization: Bearer <api_key>

Cursor (manual)

Adicione em ~/.cursor/mcp.json (ou em .cursor/mcp.json no nível do projeto):

{
  "mcpServers": {
    "wavix": {
      "url": "https://mcp.wavix.com/mcp",
      "headers": {
        "Authorization": "Bearer <api_key>"
      }
    }
  }
}

O Cursor 2.4+ expõe o catálogo completo; versões anteriores limitam a 40.

VS Code (manual, GitHub Copilot Chat)

Crie .vscode/mcp.json no seu espaço de trabalho (ou adicione o mesmo objeto servers sob a chave "mcp" em settings.json do usuário):

{
  "servers": {
    "wavix": {
      "type": "http",
      "url": "https://mcp.wavix.com/mcp",
      "headers": {
        "Authorization": "Bearer <api_key>"
      }
    }
  }
}

Consulte o guia de servidores MCP do VS Code para obter o esquema atualizado.

Codex CLI

O Codex CLI oferece suporte a MCP via stdio. Faça a ponte para o servidor hospedado por meio de mcp-remote. Edite ~/.codex/config.toml:

[mcp_servers.wavix]
command = "npx"
args = [
  "-y",
  "mcp-remote",
  "https://mcp.wavix.com/mcp",
  "--header",
  "Authorization:Bearer ${WAVIX_API_KEY}"
]

[mcp_servers.wavix.env]
WAVIX_API_KEY = "YOUR_API_KEY"

Windsurf / outros clientes

Qualquer cliente MCP que aceite transporte Streamable HTTP com cabeçalhos personalizados funcionará. Use:

• URL: https://mcp.wavix.com/mcp
• Cabeçalho: Authorization: Bearer <api_key>

Configurando por meio de um agente de IA? Aponte seu agente para llms-install.md — é um guia de instalação legível por máquina que fornece ao modelo a URL, o cabeçalho e a configuração por cliente em um formato determinístico, para que ele não improvise valores de endpoint.

Execute o seu próprio

O servidor hospedado funciona de imediato para a maioria dos usuários. Hospede você mesmo se precisar apontar para uma implantação Wavix não pública, operar atrás de firewall ou rodar dentro da sua própria infraestrutura.

Docker

docker build -t wavix-mcp-server .
docker run --rm -p 8000:8000 wavix-mcp-server

O servidor escuta na porta 8000 e expõe o endpoint MCP em /mcp. Aponte seu cliente para http://<host>:8000/mcp.

A partir do código-fonte

git clone https://github.com/Wavix/wavix-mcp-server.git
cd wavix-mcp-server
pip install -e .
wavix-mcp

Requer Python 3.10+.

Configuração

Variável de ambiente	Padrão	Finalidade
WAVIX_API_BASE_URL	https://api.wavix.com	Substituir o endpoint da API Wavix upstream (para implantações internas ou de staging)

Não é necessário ter credenciais Wavix para executar o servidor — elas são encaminhadas por solicitação a partir do cabeçalho Authorization: Bearer <api_key> do cliente MCP. Quem faz auto-hospedagem é responsável por encerrar o TLS na frente do servidor (nginx, Caddy, balanceador de carga em nuvem) antes de expô-lo publicamente.

Exemplos

Prompts concretos que você pode usar em qualquer cliente conectado.

Os números de telefone abaixo (+1 310 555 0100, +44 7700 900123) estão em faixas de teste reservadas (NANP 555 e Ofcom 070 09xx) — seguros para copiar literalmente; nenhum assinante real é alcançável por meio deles.

Enviar um SMS transacional

Prompt: "Envie um SMS de +13105550100 para +447700900123 dizendo 'Seu código de verificação é 4821'."

O agente chama sms_and_mms_messages_send com from, to e text. Retorna o ID da mensagem e o status de entrega.

Executar uma verificação 2FA

Prompt: "Envie um código de verificação 2FA para +13105550100 via SMS. Quando eu informar o código que receber, verifique se está correto."

O agente chama two_fa_verification_create, aguarda você compartilhar o código recebido via SMS e então chama two_fa_verification_check. Útil para prototipar fluxos sem senha sem escrever código de integração.

Encontrar e comprar um número de telefone

Prompt: "Encontre um número gratuito (toll-free) dos EUA disponível com capacidade de SMS, adicione-o ao carrinho e finalize a compra."

O agente encadeia buy_numbers_list (filtrando por país e recurso), cart_add e cart_checkout. Confirme com o usuário antes da finalização — ela cobra na conta.

Pesquisar transcrições de chamadas

Prompt: "Mostre todas as chamadas recebidas de ontem com mais de dois minutos em que o chamador mencionou 'reembolso'."

O agente usa cdrs_search sobre as transcrições e depois enriquece cada resultado via cdrs_get para obter os metadados completos da chamada.

Baixar uma gravação e transcrevê-la

Prompt: "Obtenha a gravação da chamada abc-123, peça à Wavix para transcrevê-la e retorne a transcrição."

O agente chama call_recording_get (retorna uma URL de download pré-assinada), cdrs_retranscribe e depois consulta cdrs_transcription_get.

Auditar faturamento

Prompt: "Quanto gastamos com SMS no mês passado? Dê-me um link de download para o PDF da fatura mais recente."

O agente chama billing_transactions_list filtrado por tipo e data e depois billing_invoices_list + billing_invoices_download. A ferramenta de download retorna uma URL pré-assinada para o PDF, não o arquivo em si — abra a URL no navegador ou passe-a ao seu cliente para buscar o documento real.

Ferramentas

122 ferramentas, geradas a partir da especificação OpenAPI da Wavix. Os argumentos espelham os parâmetros de solicitação e os campos do corpo.

Grupo	Nº	Cobertura
SMS e MMS	10	Enviar, listar, recuperar mensagens; IDs de remetente; opt-outs
Controle de chamadas	9	Iniciar / atender / encerrar chamadas; reproduzir áudio; coletar DTMF
Gravação de chamadas	4	Listar, baixar (URL pré-assinada), excluir
Streaming de chamadas	2	Iniciar / interromper fluxo de mídia
Webhooks de chamadas	3	Listar, criar, excluir
CDRs	7	Listar, exportar, recuperar; busca em transcrições e retranscrição
Speech Analytics	4	Enviar, transcrever, recuperar arquivo original
2FA	6	Criar / verificar / cancelar / reenviar verificação; eventos
Meus números	6	Listar, atualizar, liberar; roteamento SMS / voz; upload de documentos
Compra	5	Países, regiões, cidades; busca de números disponíveis
Carrinho	4	Adicionar, remover, recuperar, finalizar compra
Validador de números	3	Validação individual e em lote
Troncos SIP	5	CRUD completo
10DLC	30	Marcas, campanhas, verificação, evidências, assinaturas de eventos
Perfil	3	Obter / atualizar perfil; configuração da conta
Chaves de API	4	Listar, criar, ativar / desativar, excluir
Subcontas	5	Listar, criar, obter, atualizar; transações
Faturamento	3	Transações, faturas, download de extrato
Campanhas de voz	2	Disparar e recuperar
Wavix Embeddable (WebRTC)	5	CRUD de tokens de widget
Encurtador de links	2	Criar links curtos; métricas

Consulte TOOLS.md para obter a lista completa de ferramentas com descrições de uma linha. A fonte oficial é a especificação OpenAPI da Wavix — seu cliente sempre vê o catálogo ativo atual.

Recursos

Além das ferramentas, o servidor expõe a documentação da Wavix como Recursos MCP, para que o modelo possa obter contexto oficial sob demanda em vez de adivinhar com base em conhecimento prévio.

Esquema de URI	Conteúdo
wavix://docs/<path>	Páginas de documentação de docs.wavix.com (descoberta automática via llms.txt).
wavix://api/openapi.yaml	A especificação completa OpenAPI 3.0 da Wavix.

Ambas as fontes — docs.wavix.com e a especificação OpenAPI da Wavix — são publicamente acessíveis e podem ser navegadas diretamente sem autenticação.

Os recursos são buscados de forma preguiçosa em resources/read e armazenados em cache no servidor com TTL de 1 hora. O token Bearer upstream nunca é encaminhado para os hosts de documentação — apenas para api.wavix.com.

Autenticação

Cada solicitação do cliente deve incluir:

Authorization: Bearer <api_key>

O servidor encaminha esse cabeçalho para api.wavix.com por solicitação. O token:

• nunca é registrado em logs,
• nunca é encaminhado em redirecionamentos entre hosts (por exemplo, URLs de download pré-assinadas do S3),
• nunca é enviado a hosts de documentação.

Se o seu cliente seguir uma URL de download pré-assinada retornada por call_recording_get, billing_invoices_download, speech_analytics_file_get ou ten_dlc_brand_evidence_get, busque-a diretamente sem o cabeçalho Authorization.

Melhores práticas

• Use uma chave de API dedicada para o MCP. Crie uma chave de API separada em https://wavix.com → Administração → Chaves de API (ou pela própria ferramenta api_keys_create, de outra sessão). Isso permite revogar o acesso MCP sem interromper outras integrações.

• Rotacione periodicamente. Trate a chave de API como qualquer segredo de produção: rotacione conforme cronograma e em qualquer suspeita de vazamento.

• Mantenha as chaves de API fora do git. As configurações de clientes MCP são fáceis de commitar por acidente, levando o token junto para o histórico e os logs de CI. A maioria dos clientes oferece suporte à substituição de ${env:VAR} no valor do cabeçalho — armazene a chave de API em uma variável de ambiente ou no chaveiro do seu sistema operacional e faça referência a ela na configuração. Como rede de segurança, adicione os caminhos comuns de configuração de clientes ao .gitignore do seu projeto:

  .cursor/mcp.json
  .vscode/mcp.json
  claude_desktop_config.json
  .claude/mcp.json
  .codex/config.toml
  

Se um token for comprometido

1. No Wavix Console, desative a chave imediatamente (ou ligue para api_keys_deactivate).
2. Crie uma substituição via api_keys_create ou pelo Console.
3. Atualize a configuração do cliente e reconecte.
4. Revise billing_transactions_list e cdrs_list para atividades inesperadas.

Solução de problemas

Sintoma	Causa provável / correção
401 Unauthorized de qualquer ferramenta	Cabeçalho Authorization: Bearer … ausente ou inválido. Verifique se a chave de API está ativa no Wavix Console.
A ferramenta retorna um download_url, não o arquivo em si	Esperado. Os endpoints de evidência de gravação, fatura, análise de fala e 10DLC retornam URLs pré-assinadas (veja Autenticação). Busque a URL diretamente sem o cabeçalho Authorization.
O cliente mostra apenas ~40 ferramentas, não o catálogo completo	Clientes mais antigos impõem um limite de ferramentas por servidor. Atualize (Cursor 2.4+, VS Code mais recente, Claude mais recente).
Tool not found para uma ferramenta listada neste README	O cliente local pode estar armazenando em cache uma lista antiga de ferramentas. Reinicie o cliente ou remova e adicione novamente o servidor.
4xx com um array errors	Erro de validação da API Wavix. Inspecione errors; consulte a página relevante de wavix://docs/* ou a especificação OpenAPI.
Não é possível acessar o servidor	Confirme o DNS e o HTTPS de saída para mcp.wavix.com:443.
O agente chama uma ferramenta destrutiva inesperadamente	A maioria dos clientes pode exigir confirmação antes de chamadas de ferramenta — ative essa configuração e alterne para uma chave de API MCP dedicada (veja Práticas recomendadas).

Compatibilidade e limites

• Compatível com qualquer cliente MCP que suporte transporte Streamable HTTP (Claude Desktop / Web / Code, Cursor 2.4+, VS Code, Windsurf, SDKs MCP personalizados) e qualquer framework de agente com um adaptador de cliente MCP.
• Clientes mais antigos podem impor um limite de ferramentas por servidor; atualize para uma versão recente para acessar o catálogo completo.
• Limites de taxa e cobranças de uso seguem o plano da sua conta Wavix. Veja Preços Wavix.

Registro de alterações

O servidor hospedado é atualizado continuamente conforme a especificação OpenAPI da Wavix evolui; novas ferramentas aparecem automaticamente e os argumentos de ferramentas existentes podem ganhar campos opcionais. Alterações na documentação deste repositório são rastreadas em Releases. Para mudanças substanciais de comportamento que afetem entradas de ferramentas ou autenticação, publicaremos um aviso tanto lá quanto nas notas de versão da Wavix.

Suporte

• Documentação do produto: https://docs.wavix.com
• Referência da API: https://docs.wavix.com/api-reference
• Perguntas / feedback: support@wavix.com

Contribuição

Este repositório é código-fonte disponível, mas não é aberto a contribuições externas. Pull requests são fechados automaticamente, e Issues / Discussões estão desabilitados. Envie relatórios de bugs, solicitações de recursos e feedback para support@wavix.com. Veja CONTRIBUTING.md para detalhes.

Se você encontrar um bug no framework FastMCP subjacente, por favor, reporte-o upstream lá.

Segurança

Para relatar uma vulnerabilidade de segurança, envie um e-mail para support@wavix.com com o assunto Security: <short summary> em vez de abrir uma issue pública. Veja SECURITY.md para detalhes.

Licença

MIT © Wavix