Ir para o conteúdo

Roteiro: Emitir token MCP e conectar agente (stdio ou remoto)

Perfil necessário: admin Menus usados: Sistema (submenu → MCP) Risco: alto (segredo exibido uma única vez; token read-only porém dá acesso de consulta operacional a agentes externos) Rollback: revogar o token na tabela MCP; o agente perde o acesso na próxima chamada

Pré-requisitos

  • [ ] Login como usuário admin (a rota /system/mcp é exclusiva de admin)
  • [ ] Decidir o transporte: stdio local (agente no próprio servidor) ou remoto HTTP (/api/mcp/rpc, exige SW_ADMIN_MCP_REMOTE_ENABLED=true + TLS)
  • [ ] Usuário Unix que executará o agente local (ex.: ubuntu, opensips-admin) — a emissão exige allowlist quando não há allowlist global em SW_ADMIN_MCP_ALLOWED_UNIX_USERS
  • [ ] Cofre de segredos acessível antes de criar o token

O que os escopos permitem

Todos os transportes são read-only; o escopo define o que o agente pode consultar:

Escopo Permite
calls:read Busca CDR e timeline de chamadas
routing:read Classificação e contexto de roteamento
health:read Snapshot operacional e saúde
audit:read Consulta de contexto de auditoria

Passo a passo

1. Abrir a página MCP

Caminho: Sistema → MCP (URL /system/mcp)

Lista de tokens MCP com o botão Novo token MCP destacado

Clique: [Novo token MCP]

Resultado esperado: dialog Novo token MCP abre.

2. Preencher o dialog Novo token MCP

Dialog Novo token MCP com nome, actor, escopos, usuários Unix e expiração

Preencha:

Campo Obrig. Formato/exemplo Efeito
Nome * Sim agente-noc-local Identificação na lista/auditoria
Actor * Sim noc-agent Identidade do agente nos logs MCP
Escopos * Sim (≥ 1) checkboxes; default: calls:read, routing:read, health:read Limita as ferramentas consultáveis
Usuários Unix permitidos Condicional CSV: ubuntu, opensips-admin Restringe o transporte stdio local a estes usuários; exigido na emissão se não houver allowlist global
Definir expiração Não toggle desativado por default Sem expiração automática
Data/hora de expiração Só com o toggle ativo dd/mm/yy + hora (24h) Após esta data o token volta Expirado

Clique: [Criar token] (rodapé do dialog)

Resultado esperado: dialog Token MCP criado abre.

3. Copiar o segredo NA HORA

Dialog Token MCP criado com aviso de exibição única e snippets de conexão

Clique: [Copiar token]

Resultado esperado: toast "Token copiado".

⚠️ O segredo (mcp_...) é exibido UMA ÚNICA VEZ — só o hash fica persistido e só o prefixo aparece na tabela. Guarde no cofre antes de fechar. Se fechar sem copiar, revogue e emita outro token.

O mesmo dialog já traz três snippets prontos, com o token embutido:

Snippet Uso
Bridge local para MCP remoto Cliente de IA que só aceita MCP stdio, apontando para o endpoint HTTP remoto
Cliente HTTP nativo Agente MCP que fala Streamable HTTP direto
Stdio local no servidor Agente rodando na própria máquina do softswitch

4. Conectar o agente — stdio local (no servidor)

Para agente rodando no próprio servidor (o campo de usuários Unix permitidos só afeta este transporte):

export SW_ADMIN_MCP_PRESENTED_PAT="mcp_XXXXXXXX"
cd admin/backend
./venv/bin/python -m app.mcp_server

Resultado esperado: servidor MCP em stdio pronto para o cliente de IA; auditoria registra mcp.* com transport: stdio e actor@usuario_unix.

5. Conectar o agente — remoto via HTTP ou bridge stdio

Remoto nativo (HTTP): habilite SW_ADMIN_MCP_REMOTE_ENABLED=true no backend e publique /api/mcp/rpc atrás de reverse proxy TLS. O agente usa:

URL:    https://seu-dominio/api/mcp/rpc
Header: Authorization: Bearer mcp_XXXXXXXX
Header: MCP-Protocol-Version: 2025-11-25

Bridge stdio (cliente só aceita MCP local): execute o bridge na máquina do agente; ele lê stdio e encaminha ao endpoint remoto:

export SW_ADMIN_MCP_REMOTE_PAT="mcp_XXXXXXXX"
python3 scripts/mcp_remote_bridge.py --url https://seu-dominio/api/mcp/rpc

Resultado esperado: chamadas MCP autenticadas por Bearer; respostas JSON-RPC fluindo; sem erros 401.

6. Revogar um token

Na tabela MCP, na linha do token, Clique: [Revogar token MCP] (ícone de banimento em Ações)

Botão de revogação de token MCP destacado na tabela

Confirme no modal:

Modal de confirmação da revogação do token MCP

Resultado esperado: toast "Token MCP revogado"; Status muda para Revogado e o botão fica desabilitado (também desabilitado para tokens Inativo/Expirado). O segredo deixa de autenticar em ambos os transportes.

Validação

  • [ ] Visual: token listado com Status Ativo, prefixo, escopos e usuários Unix corretos
  • [ ] Funcional (stdio): cliente MCP local lista as ferramentas do escopo concedido
  • [ ] Funcional (remoto): POST /api/mcp/rpc com Bearer + MCP-Protocol-Version: 2025-11-25 retorna JSON-RPC 200
  • [ ] Funcional (revogação): após revogar, chamada retorna 401 com erro JSON-RPC de permissão negada
  • [ ] Auditoria: eventos create_mcp_token / revoke_mcp_token e mcp.success/mcp.error no log de auditoria

Erros comuns

Sintoma Causa provável Correção
422 ao criar: "Informe usuários Unix permitidos..." sem allowlist local nem global preencher o campo CSV ou definir SW_ADMIN_MCP_ALLOWED_UNIX_USERS
Toast "Nome, actor e ao menos um escopo são obrigatórios" campos * vazios preencher nome, actor e marcar ≥ 1 escopo
Toast "Selecione a data de expiração" toggle ativo sem data preencher o DatePicker ou desligar a expiração
Stdio falha com "usuario Unix nao autorizado" usuário que executa o agente fora da allowlist do token incluir o usuário no CSV (requer novo token) ou usar allowlist global
Remoto 404 SW_ADMIN_MCP_REMOTE_ENABLED desligado habilitar a flag no backend
Remoto 401/406/400 Bearer ausente, Accept sem application/json ou protocolo não suportado conferir headers do snippet "Cliente HTTP nativo"
Bridge falha com "SW_ADMIN_MCP_REMOTE_PAT ausente" variável de ambiente não exportada exportar o segredo antes de rodar o bridge
Token perdido antes de copiar dialog fechado sem copiar revogar e emitir novo token (segredo não é recuperável)

Tabela de referência rápida

Tarefa Onde
Criar token Sistema → MCP → Novo token MCP
Ver uso Colunas Último uso / Expiração da tabela
Revogar Ícone de banimento na linha → Revogar
Transportes stdio local (app.mcp_server) • HTTP remoto (/api/mcp/rpc) • bridge (scripts/mcp_remote_bridge.py)