Servidor MCP & Integração com Claude Code

SIP VAULT inclui um servidor MCP (Model Context Protocol) que expõe as evidências de chamadas e configs do OpenSIPS para qualquer agente de IA. Combine com a skill /troubleshoot-call no Claude Code e você tem um engenheiro VoIP sênior empacotado, que diagnostica chamadas lendo o diálogo SIP real, métricas RTCP, log e arquivos de config — sem achismo.

O ciclo: cole um Call-ID → Claude lê contexto da chamada + bundle de config via MCP → diagnóstico em prosa com arquivo + linha exata → saída estruturada diagnose(file, line, root_cause, fix).

O que está incluído

Componente	Função	Localização
`sipvault-mcp`	Servidor MCP em Python. Três ferramentas: `get_call_context`, `read_file`, `read_config_bundle`. Fala MCP via stdio.	`mcp/` no repositório
`sipvault-skill`	Skill do Claude Code: `/troubleshoot-call <call-id>`. Orquestra as ferramentas MCP e produz diagnóstico estruturado.	`skill/` no repositório

Ferramentas expostas via MCP

`get_call_context(call_id, customer_id?)`

Busca tudo que o SIP VAULT sabe sobre uma chamada:

Mensagens SIP — decodificadas, em ordem (INVITE, 100, 180, 200, ACK, BYE, etc.)
Relatório de qualidade — MOS, jitter, perda, RTT com breakdown por direção, timeseries de 5 segundos
sip_flow — topologia dos endpoints e setas de mensagens
Trecho de log — cauda do opensips.log filtrada pelo Call-ID
Caminhos de config — arquivos relevantes para ler em seguida (geralmente /etc/opensips/opensips.cfg)

Resposta limitada a ~200 KB para caber na janela de contexto do modelo.

`read_config_bundle(main_path)`

Lê um arquivo cfg do OpenSIPS E segue todos os #!include, retornando todos os arquivos alcançáveis em uma única chamada. Detecta ciclos. Limite de 50 arquivos / 1 MB total. Use isto em vez de múltiplos read_file quando estiver percorrendo uma árvore de cfg.

`read_file(path)`

Leitura de texto puro de um único arquivo. Por padrão, restrita a /etc/opensips/, /etc/rtpproxy/, /var/log/opensips/. Protegida contra path-traversal.

Instale o servidor MCP

Execute no mesmo host do SIP VAULT FastAPI (ou em qualquer lugar que consiga alcançá-lo via HTTPS):

git clone https://github.com/sippulse/sipvault.git
cd sipvault/mcp
pip install -e .

Verifique:

which sipvault-mcp

Configure

Variáveis de ambiente:

Variável	Obrigatória	Padrão	Função
`SIPVAULT_MCP_API_URL`	sim	`http://127.0.0.1:8000`	URL base do SIP VAULT FastAPI
`SIPVAULT_MCP_SERVICE_TOKEN`	sim	—	JWT que autentica MCP → FastAPI. Gerar no lado da API.
`SIPVAULT_MCP_CUSTOMER_ID`	sim	—	Tenant padrão para buscas de chamadas
`SIPVAULT_MCP_ALLOWED_PATHS`	não	`/etc/opensips:/etc/rtpproxy:/var/log/opensips`	Allowlist separada por `:` para `read_file`

Gere o token de serviço

No host do FastAPI, gere o token e defina no ambiente da API. O mesmo token vai para o ambiente do MCP.

# No host do FastAPI:
python -c "import secrets; print(secrets.token_urlsafe(48))"

# Configure no lado da API (exemplo systemd):
sudo systemctl edit sipvault-api
# Adicione:
#   [Service]
#   Environment=SIPVAULT_MCP_SERVICE_TOKEN=<cole aqui>
sudo systemctl restart sipvault-api

Kill switch: remova SIPVAULT_MCP_SERVICE_TOKEN no lado da API e reinicie. O caminho de auth do MCP fica morto, independente do token que o cliente apresente.

Integração com Claude Code

Claude Code lê configs de servidores MCP em ~/.config/claude-code/mcp.json (ou equivalente na sua plataforma). Adicione:

{
  "mcpServers": {
    "sipvault-mcp": {
      "command": "sipvault-mcp",
      "args": [],
      "env": {
        "SIPVAULT_MCP_API_URL": "https://sua-sipvault-api.exemplo.com",
        "SIPVAULT_MCP_SERVICE_TOKEN": "<cole-o-token>",
        "SIPVAULT_MCP_CUSTOMER_ID": "seu-customer-id",
        "SIPVAULT_MCP_ALLOWED_PATHS": "/etc/opensips:/etc/rtpproxy:/var/log/opensips"
      }
    }
  }
}

Reinicie o Claude Code. Verifique:

claude mcp list
# Esperado: sipvault-mcp  (running)

Instale a skill `/troubleshoot-call`

claude plugin install github.com/sippulse/sipvault-skill

Em qualquer sessão do Claude Code:

/troubleshoot-call abc123-@-10.0.0.1

A skill:

Chama get_call_context para o Call-ID.
Lê o bundle de config em /etc/opensips/opensips.cfg (seguindo #!include).
Raciocina ponta-a-ponta: diálogo SIP, assimetria de direção RTCP, erros no log, inconsistências de config.
Emite prosa (Observado / Causa raiz / Correção) em menos de 200 palavras.
Finaliza com chamada estruturada diagnose(file, line, root_cause, fix) que sua ferramenta pode consumir.

Exemplo de sessão

> /troubleshoot-call F7FCEF17-AA99-433F-99A6-6CF81901D70F

[Claude lê get_call_context, vê 200 OK recebido mas sem RTP na direção UAC→UAS]
[Claude lê read_config_bundle(/etc/opensips/opensips.cfg)]
[Claude percorre nat.cfg, encontra route[NAT_REPLY] sem rtpproxy_answer()]

**Observado.** Diálogo chegou a 200 OK. RTCP mostra áudio unidirecional:
o chamador recebeu mídia, o chamado recebeu zero pacotes. Log mostra que
o rtpproxy foi engajado no INVITE mas não na resposta.

**Causa raiz.** `nat.cfg:47` — `route[NAT_REPLY]` chama `fix_contact()` mas
omite `rtpproxy_answer()`, então o SDP no 200 OK mantém o IP privado do
chamador na linha `c=`.

**Correção.** Adicione `rtpproxy_answer();` dentro de `route[NAT_REPLY]`
logo após `fix_contact()`, recarregue o OpenSIPS.

diagnose(file="nat.cfg", line=47, root_cause="route[NAT_REPLY] sem rtpproxy_answer(), SDP no 200 OK vaza IP privado", fix="adicionar rtpproxy_answer() após fix_contact() em route[NAT_REPLY]")

Troubleshooting

`sipvault-mcp: command not found`

pip install -e . não colocou o script no PATH. Tente pip install --user -e . e adicione ~/.local/bin ao PATH, ou instale dentro de uma venv que o Claude Code enxergue.

`401 invalid service token`

O SIPVAULT_MCP_SERVICE_TOKEN do lado MCP não bate com o configurado na FastAPI. Regenere, configure dos dois lados, reinicie ambos os processos.

`call not found`

O Call-ID não bateu com nenhuma gravação nos últimos 7 dias sob o customer_id configurado. Verifique que o agente está rodando no servidor OpenSIPS que tratou a chamada e que o customer_id bate com o tenant do bucket S3.

Ferramentas MCP não aparecem no Claude Code

claude mcp list deveria incluir sipvault-mcp. Se não: o Claude Code não parseou seu mcp.json. Valide a sintaxe JSON (jq . ~/.config/claude-code/mcp.json), reinicie o Claude Code, verifique os logs do Claude Code procurando erros de startup do MCP.

A skill roda mas nunca chama `diagnose`

O prompt da skill exige diagnose como ação final. Se Claude pular: seu servidor MCP provavelmente retornou um erro ({"error": "..."}) sendo tratado como texto. Verifique stderr do servidor MCP para a classe do erro.

Modelo de segurança

Auth MCP-para-FastAPI é um JWT compartilhado. Rotacione trocando ambas as env vars e reiniciando. Nenhuma identidade de usuário é carregada — as chamadas MCP rodam com o customer_id do env, não por usuário.
read_file é allowlistado — tentativas de path-traversal retornam erro. Você pode restringir mais a allowlist por deployment.
Sem execução de código — o servidor MCP é read-only. Nunca faz shell out, nunca escreve em disco, nunca reinicia o OpenSIPS.
Trilha de auditoria — a FastAPI loga toda requisição MCP com o Call-ID. Mande esses logs para seu SIEM como qualquer outra API.

Veja o Guia de Segurança para o modelo completo de ameaças.