Wavix

oficial

Wavix é uma plataforma global de comunicações que oferece APIs para voz, SMS, 2FA e números de telefone. Nosso servidor MCP traz essas capacidades para agentes de IA e fluxos de trabalho agentivos.

GitHub

O que você pode fazer com Wavix MCP?

Enviar SMS transacional — Solicite o envio de um SMS com texto personalizado e número do remetente via sms_and_mms_messages_send.
Executar verificação 2FA — Crie e verifique códigos de verificação para fluxos de login sem senha usando two_fa_verification_create e two_fa_verification_check.
Encontrar e comprar números — Pesquise números disponíveis por país/recursos, adicione ao carrinho e finalize a compra com confirmação via buy_numbers_list, cart_add e cart_checkout.
Pesquisar transcrições de chamadas — Encontre chamadas por duração e palavras-chave nas transcrições e enriqueça com metadados completos via cdrs_search e cdrs_get.
Transcrever gravações de chamadas — Recupere uma gravação de chamada, solicite a transcrição e consulte os resultados usando call_recording_get_by_call, cdrs_retranscribe e cdrs_transcription_get.
Auditar cobrança — Liste transações e faturas filtradas por tipo e data via billing_transactions_list e billing_invoices_list.

Documentação

Servidor MCP Wavix

Um servidor Model Context Protocol que dá a LLMs e agentes de IA acesso direto à plataforma de telecom Wavix — SMS/MMS, chamadas de voz, 2FA, tronco 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 conecte-se entrando com sua conta Wavix ou com uma chave de API Wavix. Se você precisar de auto-hospedagem (implantação Wavix personalizada, atrás de firewall, instância dedicada), consulte Execute o seu próprio.

Sumário

Endpoint
Instalação — entrar com uma conta, chave de API, instalação em um clique, Claude Code, Claude Desktop / Web, Cursor, VS Code, Codex CLI, Windsurf
Execute o seu próprio (auto-hospedagem)
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	Entrar com uma conta Wavix (OAuth 2.1), ou `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

Duas maneiras de conectar — escolha a que seu cliente suporta; nenhuma é obrigatória sobre a outra.

Entrar com uma conta Wavix

Se o seu cliente MCP suporta OAuth (Claude Desktop / Web e outros clientes compatíveis com OAuth), conecte-se sem chave de API: adicione o conector para https://mcp.wavix.com/mcp e, quando o cliente solicitar, entre com sua conta Wavix e aprove o acesso. O cliente executa o fluxo OAuth 2.1 e armazena o token por conta própria — nada para colar. As ferramentas que você obtém são limitadas ao que você aprova e ao que sua função na conta permite (consulte Solução de problemas).

Conectar com uma chave de API

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

Entre em https://wavix.com.
Abra Administração → Chaves de API.
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 preenchem a configuração MCP do seu editor com um token de espaço reservado YOUR_API_KEY. Após o editor terminar a instalação, abra a configuração gerada e substitua o espaço reservado pela sua chave de API real antes de enviar qualquer solicitação — caso contrário, toda chamada retornará 401 Unauthorized.

Para remover depois: abra o mesmo arquivo de configuração (~/.cursor/mcp.json, .vscode/mcp.json ou o equivalente para seu editor) e exclua a entrada wavix, ou remova o conector pela interface 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 obter 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>

Para conectar entrando em vez disso, adicione o conector sem cabeçalho de autenticação e entre com sua conta Wavix quando o cliente solicitar.

Cursor (manual)

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

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

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" no usuário settings.json):

{
  "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 suporta MCP via stdio. Faça a ponte para o servidor hospedado via 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 suporte 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 imediatamente para a maioria dos usuários. Faça auto-hospedagem se precisar apontar para uma implantação Wavix não pública, operar atrás de firewall ou operar 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)
`OAUTH_ISSUER`	não definido	URL base do servidor de autorização OAuth 2.1. Seu JWKS é lido de `<issuer>/.well-known/jwks.json`
`OAUTH_RESOURCE`	não definido	URL base pública pela qual este servidor é acessado, usada como identificador de recurso
`OAUTH_API_KEY_PASSTHROUGH`	`true`	Com OAuth ativado, ainda aceitar um bearer que não seja um JWT OAuth e encaminhá-lo upstream (chaves de API continuam funcionando). Defina `false` para exigir um JWT
`MCP_PATH`	`/mcp`	Caminho no qual o endpoint MCP é servido

Nenhuma credencial Wavix é necessária para executar o servidor — elas são encaminhadas por solicitação a partir do cabeçalho Authorization: Bearer <api_key> do cliente MCP. Auto-hospedeiros são responsáveis por encerrar TLS na frente do servidor (nginx, Caddy, balanceador de carga em nuvem) antes de expô-lo publicamente.

OAuth 2.1 (opcional)

Defina OAUTH_ISSUER e OAUTH_RESOURCE juntos para transformar o servidor em um recurso protegido por OAuth 2.1. Ele então publica metadados RFC 9728 em /.well-known/oauth-protected-resource<MCP_PATH>, valida tokens de acesso recebidos como JWTs contra o JWKS do emissor e responde a solicitações não autenticadas com um desafio WWW-Authenticate apontando para esses metadados. Clientes MCP que suportam OAuth usam isso para executar o fluxo de autorização por conta própria, então os usuários não precisam mais colar uma chave de API na configuração do cliente.

A audiência que cada token deve carregar é OAUTH_RESOURCE + MCP_PATH, que também é o valor resource publicado nos metadados. Servidores de autorização que implementam RFC 8707 comparam o parâmetro resource do cliente contra essa string exatamente, então os dois devem ser configurados para corresponder — incluindo o caminho.

Ativar OAuth não corta clientes que autenticam com uma chave de API Wavix. Um token bearer que não seja um JWT OAuth válido é encaminhado upstream sem verificação, exatamente como antes, deixando a API Wavix como única autoridade sobre ele — então uma implantação existente pode ativar OAuth para novos clientes sem quebrar os já conectados. Uma solicitação sem token algum ainda recebe o desafio WWW-Authenticate, que é o que permite que um cliente compatível com OAuth descubra o servidor de autorização. Apenas conexões autenticadas por OAuth são filtradas por escopo; uma conexão com chave de API vê toda a superfície de ferramentas.

Defina OAUTH_API_KEY_PASSTHROUGH=false para remover essa alternativa e exigir um JWT válido — o modo estrito para adotar quando o acesso por chave de API for descontinuado.

Deixar qualquer um de OAUTH_ISSUER / OAUTH_RESOURCE não definido mantém o comportamento anterior: nenhum metadado é publicado e qualquer token bearer que o cliente enviar é encaminhado upstream sem verificação.

Exemplos

Prompts concretos que você pode inserir 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 lhe der o código que receber, verifique se está correto."

O agente chama two_fa_verification_create, aguarda você compartilhar o código que chega 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 dos EUA disponível com capacidade de SMS, adicione-o ao meu carrinho e finalize a compra."

O agente encadeia buy_numbers_list (filtrando por país e recurso), cart_add e cart_checkout. cart_checkout primeiro retorna uma prévia com os números e suas taxas, e cobra da conta apenas quando chamado novamente com seu confirmation_token.

Pesquisar transcrições de chamadas

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

O agente usa cdrs_search contra transcrições e então enriquece cada resultado via cdrs_get para obter 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_by_call (retorna uma URL de download pré-assinada), cdrs_retranscribe e então consulta cdrs_transcription_get.

Auditar faturamento

Prompt: "Quanto gastamos com SMS no mês passado e quais faturas foram emitidas?"

O agente chama billing_transactions_list filtrado por tipo e data e então billing_invoices_list. O download do PDF da fatura em si não é exposto via MCP — busque-o na API Wavix ou no painel.

Ferramentas

Gerado a partir da especificação OpenAPI da Wavix. Os argumentos espelham parâmetros de solicitação e campos de corpo. As ferramentas exibidas dependem das permissões que você aprova ao entrar e dos recursos habilitados na sua conta.

Grupo	Cobertura
SMS e MMS	Enviar, listar, recuperar mensagens; IDs de remetente; opt-outs
WhatsApp	Contas comerciais; remetentes; modelos; enviar / listar / recuperar mensagens
Controle de chamadas	Iniciar / atender / encerrar chamadas; reproduzir áudio; coletar DTMF
Gravação de chamadas	Listar, baixar (URL pré-assinada), excluir
Streaming de chamadas	Iniciar / parar fluxo de mídia
Webhooks de chamadas	Listar, criar, excluir
CDRs	Listar, recuperar; busca de transcrição e retranscrição
Análise de fala	Transcrever, recuperar arquivo original
2FA	Criar / verificar / cancelar / reenviar verificação; eventos
Meus números	Listar, atualizar, liberar; roteamento de SMS / voz
Comprar	Países, regiões, cidades; busca de números disponíveis
Carrinho	Adicionar, remover, recuperar, finalizar compra
Validador de números	Validação individual e em lote
Troncos SIP	CRUD completo
10DLC	Marcas, campanhas, verificação, evidências, assinaturas de eventos
Perfil	Obter / atualizar perfil; configuração da conta
Chaves de API	Listar, criar, atualizar, excluir
Subcontas	Listar, criar, obter, atualizar; transações
Faturamento	Transações; listar faturas / extratos
Campanhas de voz	Disparar e recuperar
Wavix Embeddable (WebRTC)	CRUD de tokens de widget
Encurtador de links	Criar links curtos; métricas

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

Recursos

Além das ferramentas, o servidor expõe a documentação da Wavix como Recursos MCP, para que o modelo possa obter contexto autoritativo 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 (descobertas automaticamente 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 — estão disponíveis publicamente e podem ser acessadas 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 hosts de documentação — apenas para api.wavix.com.

Autenticação

O servidor hospedado aceita dois métodos de conexão — nenhum é preferido:

Entrar com uma conta Wavix (OAuth 2.1). Para clientes compatíveis com OAuth. O cliente executa o fluxo de autorização e o usuário faz login; nenhuma chave de API é armazenada. O acesso é limitado por escopo ao que o usuário aprova e ao que a função da conta permite. Consulte Entrar com uma conta Wavix.
Chave de API Wavix (Bearer). Para qualquer cliente Streamable-HTTP. Cada solicitação deve incluir:

Authorization: Bearer <api_key>

O servidor encaminha este 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 para hosts de documentação.

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

Boas práticas

Use uma chave de API dedicada para MCP. Crie uma chave de API separada em https://wavix.com → Administração → Chaves de API (ou por meio da 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 agendamento e em qualquer suspeita de vazamento.
Mantenha chaves de API fora do git. Configurações de clientes MCP são fáceis de commitar por acidente, levando o token junto para o histórico e logs de CI. A maioria dos clientes suporta 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 referencie-a na configuração. Como rede de segurança, adicione os caminhos comuns de configuração de clientes ao seu .gitignore do projeto:
```
.cursor/mcp.json
.vscode/mcp.json
claude_desktop_config.json
.claude/mcp.json
.codex/config.toml
```

Se uma credencial for comprometida

Se você conectou com uma chave de API:

No Console Wavix, desative ou exclua essa chave imediatamente (ou chame api_keys_delete).
Crie uma substituição via api_keys_create ou no Console.
Atualize a configuração do cliente e reconecte.

Se você conectou entrando com sua conta Wavix:

Revogue a conexão na página de gerenciamento de concessões do portal Wavix, que lista as conexões que você autorizou e revoga a que você escolher — isso invalida os tokens dessa conexão. Nenhuma chave de API está envolvida.
Reconecte e entre novamente.

Em ambos os casos, 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	Falha de autenticação. Com chave de API: o cabeçalho `Authorization: Bearer …` está ausente, ou a chave é inválida ou inativa — verifique no Console Wavix. Com login de conta: sua sessão/token expirou ou foi revogado, ou o login nunca foi concluído — reconecte e entre novamente.
A ferramenta retorna um `download_url`, não o arquivo em si	Esperado. Endpoints de gravação, análise de fala e evidências 10DLC retornam URLs pré-assinadas (consulte Autenticação). Busque a URL diretamente sem o cabeçalho `Authorization`.
O cliente mostra apenas parte do catálogo	Clientes mais antigos impõem um limite de ferramentas por servidor. Atualize (Cursor 2.4+, VS Code mais recente, Claude mais recente).
Menos ferramentas disponíveis após entrar com uma conta Wavix	Esperado. O login de conta é filtrado por escopo — você obtém as ferramentas que seus escopos aprovados e a função da conta permitem, não o catálogo completo. Uma conexão com chave de API vê toda a superfície de ferramentas. Para ampliar o conjunto, aprove mais escopos no login (sujeito à sua função) ou conecte com uma chave de API que os contenha.
`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 o servidor novamente.
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 alcançar o servidor	Confirme DNS e 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 ferramentas — ative essa configuração e rotacione para uma chave de API MCP dedicada (consulte Boas práticas).

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 adaptador de cliente MCP.
Cada ferramenta anotada com destructiveHint, além de call_webhooks_create, sip_trunks_update e sub_accounts_update, executa em duas etapas: a primeira chamada retorna uma prévia e um confirmation_token de uso único (válido por 5 minutos), e a ação é executada somente quando a ferramenta é chamada novamente com os mesmos argumentos e esse token. Qualquer cliente MCP pode fazer isso; nenhum suporte de confirmação no lado do cliente é necessário.
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. Consulte Preços da Wavix.

Changelog

O servidor hospedado é atualizado continuamente conforme a especificação OpenAPI da Wavix evolui; novas ferramentas aparecem automaticamente e argumentos de ferramentas existentes podem ganhar campos opcionais. Alterações de documentação para este 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 é fonte disponível, mas não aberto a contribuições externas. Pull requests são fechados automaticamente, e Issues / Discussions estão desabilitados. Envie relatórios de bugs, solicitações de recursos e feedback para support@wavix.com. Consulte CONTRIBUTING.md para detalhes.

Se você encontrar um bug no framework subjacente FastMCP, 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. Consulte SECURITY.md para detalhes.