IA - Inteligência Artificial - Servidor MCP do Voipstudio
O servidor MCP (Model Context Protocol) do Voipstudio dá ao Claude AI acesso direto e seguro aos dados da sua conta Voipstudio, incluindo gravações, CDRs, chamadas em tempo real e correios de voz. Uma vez ligado, o Claude pode consultar chamadas, analisar padrões, identificar problemas de desempenho de agentes e gerar relatórios de QA em linguagem natural — sem necessidade de desenvolvimento personalizado.
Adicione o CX Addon e cada gravação chegará pré-enriquecida com transcrição, resumo, sentimento, itens de ação e uma pontuação CX. Isto reduz significativamente o trabalho de IA que o Claude precisa de fazer, mantendo o uso de tokens baixo e os custos mais previsíveis.
Obter uma chave de API
O servidor MCP autentica-se utilizando um token de API do Voipstudio. Cada chave é associada a um utilizador específico, pelo que o Claude só poderá aceder aos dados a que esse utilizador tem acesso.
Para gerar uma chave:
- No painel de administração, abra o utilizador para o qual pretende gerar um token.
- Vá à secção Chaves de API.
- Introduza um nome para a chave — por exemplo,
Claude MCP. - Clique em Adicionar.
- Clique no ícone de olho para revelar a chave de API /
user_token. Copie este valor. - Para ver mais detalhes ou eliminar a chave, clique no ícone de engrenagem e selecione Mostrar Detalhes.
Nota: A chave de API permanece válida enquanto for utilizada pelo menos uma vez a cada 7 dias (tempo limite predefinido). Defina um tempo limite mais longo (ou ilimitado) se necessário, antes de clicar em Adicionar.
Consulte a documentação da API REST
Ligar ao Claude
O Voipstudio não está atualmente listado no diretório de conectores do Claude.ai. Deve adicioná-lo manualmente como servidor MCP personalizado.
URL do servidor MCP
Passos (Claude.ai)
- No Claude.ai, aceda a Definições → Integrações (ou ao painel de conectores, consoante o seu plano).
- Escolha Adicionar servidor MCP personalizado (ou equivalente).
- Introduza o URL do servidor MCP acima.
- Quando solicitado para autenticação, forneça a sua chave de API do Voipstudio.
- Guarde e autorize a ligação.
O Claude pode agora chamar ferramentas Voipstudio em qualquer conversa. Na primeira vez que uma ferramenta for chamada numa sessão, o Claude pedirá que confirme a partilha de dados. Clique em Permitir sempre para ignorar este aviso em sessões futuras.
API Anthropic (para programadores)
const response = await fetch("https://api.anthropic.com/v1/messages", {
method: "POST",
headers: {
"Content-Type": "application/json",
"X-Api-Key": "A_SUA_CHAVE_API_ANTHROPIC"
},
body: JSON.stringify({
model: "claude-sonnet-4-6",
max_tokens: 1024,
mcp_servers: [{
type: "url",
url: "https://mcp.voipstudio.workers.dev/sse",
name: "voipstudio",
authorization_token: "A_SUA_CHAVE_API_VOIPSTUDIO"
}],
messages: [{
role: "user",
content: "Mostra-me os agentes com pontuação CX abaixo de 6 esta semana"
}]
})
});
Ligar a outras plataformas de IA
A maioria das plataformas de IA que suportam MCPs externos pode ligar-se ao servidor MCP do Voipstudio utilizando o mesmo URL e chave de API. Os passos de configuração exatos variam consoante a plataforma. Procure uma opção chamada servidor MCP externo, MCP personalizado ou MCP remoto nas integrações ou definições da sua plataforma.
CX Addon
Sem o CX Addon, as gravações chegam como metadados brutos. O Claude terá de transcrever e analisar cada chamada por conta própria, consumindo um número significativo de tokens por gravação.
Com o CX Addon, o Voipstudio trata da transcrição, resumo, análise de sentimento, extração de ações e pontuação CX na sua própria infraestrutura, a um custo mensal fixo sem taxas por chamada e sem limites de transcrição. O Claude recebe inteligência pronta — disponível para raciocinar imediatamente.
| Sem CX Addon | Com CX Addon | |
|---|---|---|
| Transcrição | O Claude deve obter o áudio e transcrever/traduzir | ✓ Incluída, com diarização por locutor |
| Resumo | O Claude deve gerar | ✓ Incluído |
| Sentimento | O Claude deve inferir | ✓ Incluído |
| Itens de ação | O Claude deve extrair | ✓ Incluídos |
| Pontuação CX | Não disponível | ✓ 1–10 em cada chamada |
| Tokens aprox./chamada | 10.000–15.000 | 300–500 |
| Modelo de custo | Gasto de IA variável | Subscrição mensal fixa |
Campos desbloqueados pelo CX Addon
| Campo | Tipo | Descrição |
|---|---|---|
transcript | string | Transcrição completa ao nível da palavra |
transcript_speakers | object | Segmentos de transcrição com diarização por locutor |
summary | string | Resumo conciso do resultado da chamada |
sentiment | string | Sentimento do cliente: positive, neutral, negative |
cx_score | number (1–10) | Pontuação de experiência do cliente |
metadata.timeline | array | Momentos-chave e itens de ação extraídos da chamada |
Referência de Ferramentas
A simplicidade da integração MCP significa que não é necessário compreender APIs complexas — basta usar prompts simples para que a plataforma de IA interprete os dados fornecidos pelo Voipstudio e responda de forma adequada.
No entanto, alguns utilizadores mais técnicos poderão querer saber o que se passa "nos bastidores", pelo que se segue um guia de referência para algumas das funções do servidor MCP.
get_recordings
Devolve gravações de chamadas. Com o CX Addon ativo, cada registo inclui a transcrição, resumo, sentimento, pontuação CX e linha cronológica. Sem o addon, estes campos devolvem null.
Parâmetros
| Parâmetro | Tipo | Predefinição | Descrição |
|---|---|---|---|
filters | array | — | Objetos de filtro — consulte Filtragem |
limit | number | 10 | Registos por página (máx. 1000) |
page | number | 1 | Número da página |
Campos de resposta
| Campo | Tipo | Descrição |
|---|---|---|
id | number | ID único da gravação |
call_id | number | Liga ao call_id do CDR |
timestamp | string | Início da gravação (UTC, YYYY-MM-DD HH:mm:ss) |
caller | string | Número da parte que origina a chamada |
called | string | Número da parte que recebe a chamada |
src_name | string | Nome do agente (origem) |
dst_name | string | Nome do destino |
duration | number | Duração em segundos |
type | string | I = entrada, O = saída |
context | string | Contexto da chamada (ex.: LOCAL_USER, QUEUE) |
transcript | string | null | Transcrição completa (CX Addon) |
transcript_speakers | object | null | Transcrição com diarização (CX Addon) |
summary | string | null | Resumo da chamada (CX Addon) |
sentiment | string | null | Sentimento do cliente (CX Addon) |
cx_score | number | null | Pontuação CX 1–10 (CX Addon) |
metadata.timeline | array | null | Eventos-chave e ações (CX Addon) |
Exemplo – Pontuações CX baixas esta semana
Diga ao Claude: "Mostra-me todas as gravações desta semana com pontuação CX abaixo de 6, agrupadas por agente, com um resumo do que correu mal em cada chamada."
O Claude chama a ferramenta com:
{
"filters": [
{ "property": "calldate", "operator": "gte", "value": "2026-06-09 00:00:00" },
{ "property": "cx_score", "operator": "lt", "value": 6 }
],
"limit": 100
}
get_cdrs
Registos de Detalhes de Chamadas – o registo bruto de cada segmento de chamada. Útil para estatísticas de volume, análise de custos, distribuições de duração e resumos de atividade de agentes. Disponível sem o CX Addon.
Parâmetros: iguais aos de get_recordings (filters, limit, page)
Campos de resposta principais
| Campo | Tipo | Descrição |
|---|---|---|
call_id | number | Identificador único da chamada |
calldate | string | Timestamp de início da chamada (UTC) |
src_name | string | Nome do agente / chamador |
dst_name | string | Nome do destino |
billsec | number | Segundos faturáveis |
duration | number | Total de segundos incluindo toque |
disposition | string | CONNECTED, NO ANSWER, BUSY, FAILED |
charge | number | Custo da chamada |
type | string | I = entrada, O = saída |
src_ua | string | Dispositivo de origem / user-agent do softphone |
labels | array | Etiquetas personalizadas aplicadas no Voipstudio |
get_live_calls
Devolve um instantâneo em tempo real de todas as chamadas ativas na sua conta. Não são necessários parâmetros.
Exemplo: "Quantas chamadas estão em curso agora, e quais os agentes que estão nelas?"
get_voicemails
Obtém mensagens de correio de voz. A mesma interface de filters, limit e page das outras ferramentas.
Campos filtráveis principais: src, dst, calldate, duration, listened
get_recording_audio
Devolve um URL de transferência direta para o áudio MP3 de uma gravação específica.
Parâmetro: id (number) — o campo id de uma resposta get_recordings.
Os URLs de áudio têm duração limitada. Utilize-os prontamente; não os guarde em cache por períodos prolongados.
Filtragem e Paginação
Todas as ferramentas de listagem aceitam um array filters opcional. Cada objeto de filtro tem três propriedades:
| Propriedade | Descrição |
|---|---|
property | Nome do campo a filtrar (ex.: calldate, cx_score, src_name) |
operator | eq, ne, lt, lte, gt, gte, in, like, notlike |
value | String, número ou array (para o operador in) |
Exemplos comuns
Intervalo de datas
[
{ "property": "calldate", "operator": "gte", "value": "2026-06-01 00:00:00" },
{ "property": "calldate", "operator": "lte", "value": "2026-06-30 23:59:59" }
]
Limiar de pontuação CX
[{ "property": "cx_score", "operator": "gte", "value": 8 }]
Agente específico
[{ "property": "src_name", "operator": "eq", "value": "Jane Ryder" }]
Apenas chamadas ligadas
[{ "property": "disposition", "operator": "eq", "value": "CONNECTED" }]
Chamadas de entrada com mais de 5 minutos
[
{ "property": "type", "operator": "eq", "value": "I" },
{ "property": "billsec", "operator": "gt", "value": 300 }
]
Casos de Uso
Relatório de QA de agentes
"Dá-me um resumo de QA para cada agente este mês — médias de pontuação CX, temas de reclamação frequentes e as três chamadas com pior pontuação com resumos."
Estatísticas de volume do centro de contacto
"Qual foi o volume de chamadas por dia esta semana? Qual foi o tempo médio de atendimento e quantas chamadas ficaram sem resposta?"
Análise de tendência de sentimento
"O sentimento dos clientes está a melhorar ou a piorar em comparação com o mês passado? Quais os tópicos de chamada que se correlacionam com sentimento negativo?"
Lista de acompanhamento de chamadas perdidas
"Lista todas as chamadas de entrada perdidas nas últimas 24 horas com os IDs dos chamadores, para que eu possa priorizar os retornos de chamada."
Revisão de custos e faturação
"Quais os ramais que fizeram as chamadas de saída mais dispendiosas este trimestre?"
Verificação de operações em tempo real
"Quantos agentes estão atualmente em chamadas e existem chamadas com duração superior a 20 minutos?"
Eficiência de Tokens
Cada chamada que o Claude analisa sem o CX Addon requer que processe conteúdo de áudio e gere a sua própria transcrição e análise. O CX Addon transfere este trabalho inteiramente para o Voipstudio:
O que o Voipstudio trata (custo mensal fixo, chamadas ilimitadas):
- Transcrição de áudio
- Diarização por locutor
- Resumo de chamadas
- Classificação de sentimento
- Extração de itens de ação
- Pontuação CX
O que o Claude recebe: Campos de texto limpos e estruturados, prontos para raciocínio, comparação e relatórios.
Isto significa que pode pedir ao Claude para analisar centenas de chamadas numa única sessão a uma fração do custo em tokens, tornando a QA em larga escala, a análise de tendências e os relatórios de formação de agentes práticos, sem gastos de IA imprevisíveis.