IA - Inteligência Artificial - Servidor MCP do Voipstudio
O servidor MCP (Model Context Protocol) do Voipstudio dá a assistentes de IA como o Claude e o ChatGPT acesso direto e seguro aos dados da sua conta Voipstudio, incluindo gravações, CDRs, chamadas em tempo real, correios de voz e o histórico das suas conversas com um número. Uma vez ligado, o assistente 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 que a IA tem de fazer, o que mantém o uso de tokens baixo e os custos mais previsíveis.
URL do servidor MCP
URL do servidor MCP
Este é um servidor MCP remoto (transporte Streamable HTTP). A ligação faz-se iniciando sessão com a sua conta Voipstudio: não há nenhuma chave de API para criar ou colar.
Como funciona a ligação
Quando adiciona o servidor a uma aplicação de IA, esta abre uma página de início de sessão do Voipstudio:
- Inicie sessão com o seu e-mail e palavra-passe do Voipstudio (e o código 2FA, se a autenticação de dois fatores estiver ativada) ou com Google, Microsoft ou Apple, se a sua conta utilizar início de sessão único. A conta já tem de existir: não é possível criar uma conta nova a partir desta página.
- Uma página de consentimento mostra quem está a pedir acesso. Indica o endereço que irá receber o acesso e, quando se trata de uma aplicação conhecida (Claude, ChatGPT) ou executada no seu próprio computador, identifica também a aplicação. Qualquer outro site é apresentado com um aviso: permita-o apenas se reconhecer o endereço.
- Clique em Allow para estabelecer a ligação ou em Cancel para não ligar nada.
O assistente passa então a ver o que o seu utilizador do Voipstudio pode ver, e nada mais.
A chave de API que cada aplicação recebe
Quando clica em Allow, o servidor cria uma chave de API do Voipstudio para essa aplicação na secção Chaves de API do seu utilizador. O nome da chave começa por VoIPstudio MCP - , seguido do nome da aplicação, por exemplo VoIPstudio MCP - Claude (claude.ai) [1a2b3c4d].
- Cada aplicação ligada tem a sua própria chave. Voltar a iniciar sessão a partir da mesma aplicação substitui apenas a chave dessa aplicação, pelo que as suas outras aplicações continuam ligadas.
- Um utilizador pode ter até 10 destas chaves. Ligar uma décima primeira aplicação remove a chave utilizada há mais tempo.
- Uma chave expira após 30 dias sem utilização. A utilização normal, incluindo a renovação do início de sessão que a aplicação faz em segundo plano, mantém-na ativa.
- Para desligar uma aplicação, remova o conector na aplicação ou elimine a respetiva chave em Chaves de API. Depois de a chave ser eliminada, as chamadas às ferramentas feitas pela aplicação indicam que a ligação foi removida e a aplicação pede-lhe que volte a iniciar sessão.
Ligar ao Claude
No Claude (web ou aplicação para computador), adicione o Voipstudio como conector personalizado:
- Abra Definições → Conectores e escolha Adicionar conector personalizado. Nos planos Team e Enterprise, é um proprietário que adiciona o conector para a organização.
- Introduza um nome, por exemplo
Voipstudio, e o URL do servidor MCP indicado acima. - Clique em Ligar e conclua os passos de início de sessão e consentimento descritos acima.
O Claude pode agora utilizar as ferramentas do Voipstudio em qualquer conversa. Na primeira vez que uma ferramenta é chamada, o Claude pede-lhe que confirme. Escolha Permitir sempre para ignorar este aviso no futuro.
Claude Code
claude mcp add --transport http voipstudio https://mcp.voipstudio.com/mcp
claude mcp login voipstudio
O seu navegador abre a página de início de sessão. Depois de clicar em Allow, clique em Continue para devolver o início de sessão ao Claude Code.
Numa máquina sem navegador, por exemplo através de SSH, execute em vez disso claude mcp login voipstudio --no-browser. Abra o endereço que o comando apresenta num navegador em qualquer computador, inicie sessão e permita o acesso; depois, copie o endereço que a última página mostra e cole-o no Claude Code quando lhe for pedido.
Ligar a outras plataformas de IA
Qualquer aplicação de IA que suporte servidores MCP remotos com início de sessão (OAuth) pode ligar-se utilizando o URL acima, por exemplo o ChatGPT, se o seu plano permitir conectores personalizados. Procure uma opção chamada conector personalizado, MCP personalizado ou MCP remoto nas definições da aplicação, introduza o URL e conclua os passos de início de sessão e consentimento. Os menus exatos dependem da aplicação e do seu plano.
As aplicações que apenas conseguem enviar uma chave de API fixa não se podem ligar: este servidor só aceita o início de sessão que ele próprio emite.
Para programadores
O servidor implementa a autorização MCP:
- Fluxo de código de autorização OAuth 2.1 com PKCE (
S256) e registo dinâmico de clientes. Os metadados são publicados emhttps://mcp.voipstudio.com/.well-known/oauth-authorization-serverehttps://mcp.voipstudio.com/.well-known/oauth-protected-resource/mcp. - Os tokens de acesso são válidos durante uma hora e são renovados com um token de atualização. Um token de atualização permanece válido enquanto for utilizado pelo menos uma vez a cada 30 dias.
- Apenas
initializeetools/listfuncionam sem token. Uma chave de API do Voipstudio não é aceite como bearer token. - Os pedidos são limitados por endereço de cliente: 20 registos de clientes por hora, e 50 pedidos de token e 100 pedidos de autorização por cada 15 minutos.
Para chamar o servidor através do conector MCP da API do Claude, a sua aplicação obtém um token de acesso com o fluxo acima e passa-o como authorization_token do servidor. Consulte a documentação do conector MCP da Anthropic para conhecer o formato do pedido.
CX Addon
Sem o CX Addon, as gravações chegam como metadados brutos. A IA tem 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, do resumo, da análise de sentimento, da extração de ações e da pontuação CX na sua própria infraestrutura, a um custo mensal fixo sem taxas por chamada e sem limites de transcrição. A IA recebe inteligência pronta, sobre a qual pode raciocinar de imediato.
| Sem CX Addon | Com CX Addon | |
|---|---|---|
| Transcrição | A IA deve obter o áudio e transcrever/traduzir | ✓ Incluída, com diarização por locutor |
| Resumo | A IA deve gerar | ✓ Incluído |
| Sentimento | A IA deve inferir | ✓ Incluído |
| Itens de ação | A IA 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
Com o MCP, não precisa de aprender a API do Voipstudio: faz o pedido em linguagem natural, e a IA escolhe as ferramentas e lê os dados por si.
Para os utilizadores mais técnicos que queiram saber o que se passa "nos bastidores", o servidor disponibiliza as seis ferramentas abaixo. Todas elas apenas leem dados.
get_recordings
Devolve gravações de chamadas. Com o CX Addon ativo, cada registo inclui a transcrição, o resumo, o sentimento, a pontuação CX e a linha cronológica. Sem o addon, estes campos são null.
Parâmetros
| Parâmetro | Tipo | Predefinição | Descrição |
|---|---|---|---|
filters | array | — | Objetos de filtro; consulte Filtragem, ordenação e paginação abaixo |
sort | object | — | { "by": "<field>", "dir": "ASC" } ou "DESC" |
limit | number | 10 | Registos por página (1–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 | Corresponde 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
Peça: "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."
A IA chama a ferramenta com:
{
"filters": [
{ "property": "timestamp", "operator": "gte", "value": "2026-11-09 00:00:00" },
{ "property": "cx_score", "operator": "lt", "value": 6 }
],
"sort": { "by": "cx_score", "dir": "ASC" },
"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, sort, limit, page)
Campos de resposta principais
| Campo | Tipo | Descrição |
|---|---|---|
call_id | number | Identificador único da chamada |
calldate | string | Data e hora 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 o tempo de 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 neste momento e que agentes estão nelas?"
get_voicemails
Obtém mensagens de correio de voz. Aceita os mesmos parâmetros filters, sort, limit e page que get_recordings.
Campos principais: caller, callerid, dialled (o número que foi marcado), origtime (quando a mensagem foi deixada), duration, folder, is_new, transcript
get_recording_audio
Devolve o endereço do áudio MP3 de uma gravação, com o respetivo chamador, número chamado, hora e duração.
Parâmetro: id (number) — o campo id de uma resposta de get_recordings.
Trata-se de um endereço da API do Voipstudio. A transferência requer uma chave de API do Voipstudio enviada no cabeçalho x-auth-token, pelo que a IA recebe o endereço e não o áudio.
get_history_for_number
Lista as conversas (chamadas e SMS) da sua conta com um número de telefone.
Parâmetros
| Parâmetro | Tipo | Predefinição | Descrição |
|---|---|---|---|
number | string | — | O número de telefone (obrigatório) |
fromDateTime | string | — | Início opcional, YYYY-MM-DD HH:mm:ss |
toDateTime | string | — | Fim opcional, YYYY-MM-DD HH:mm:ss |
Campos de resposta (uma entrada por chamada ou mensagem): channel, date, direction (Inbound ou Outbound), src, dst, src_name, dst_name, content
Exemplo: "Mostra-me todas as chamadas e SMS com o +44 20 7946 0000 este mês."
Filtragem, ordenação e paginação
As ferramentas get_recordings, get_cdrs e get_voicemails aceitam um array filters opcional. Cada objeto de filtro tem três propriedades:
| Propriedade | Descrição |
|---|---|
property | Qualquer campo da resposta da ferramenta (ex.: calldate, cx_score, src_name) |
operator | eq, ne, lt, lte, gt, gte, in, like, notlike (os símbolos =, !=, <, <=, >, >= também funcionam) |
value | String, número ou array (para o operador in) |
O campo de data varia consoante a ferramenta: calldate para CDRs, timestamp para gravações, origtime para correios de voz.
Os resultados são ordenados com sort, por exemplo { "by": "calldate", "dir": "DESC" }, e paginados com limit (10 por predefinição, máximo 1000) e page (1 por predefinição).
Exemplos comuns
Intervalo de datas (CDRs)
[
{ "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 (gravações)
[{ "property": "cx_score", "operator": "gte", "value": 8 }]
Agente específico
[{ "property": "src_name", "operator": "eq", "value": "Jane Ryder" }]
Apenas chamadas ligadas (CDRs)
[{ "property": "disposition", "operator": "eq", "value": "CONNECTED" }]
Chamadas de entrada com mais de 5 minutos (CDRs)
[
{ "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 suas três chamadas com pior pontuação, com resumos."
Estatísticas de volume do centro de contacto
"Qual foi o nosso volume de chamadas por dia esta semana? Qual foi o nosso 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."
Histórico do cliente
"Mostra-me todas as chamadas e SMS que tivemos com o +44 20 7946 0000 este ano e resume o que foi discutido."
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 a decorrer há mais de 20 minutos?"
Eficiência de Tokens
Cada chamada que a IA 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 fica a cargo do Voipstudio (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 a IA recebe: campos de texto limpos e estruturados, prontos para raciocínio, comparação e relatórios.
Isto significa que pode pedir à IA que analise centenas de chamadas numa única sessão a uma fração do custo em tokens, tornando práticos a QA em larga escala, a análise de tendências e os relatórios de formação de agentes, sem gastos de IA imprevisíveis.