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, exigeSW_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 emSW_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)

Clique: [Novo token MCP]
Resultado esperado: dialog Novo token MCP abre.
2. Preencher o dialog Novo token MCP¶

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¶

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)

Confirme no modal:

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/rpccom Bearer +MCP-Protocol-Version: 2025-11-25retorna 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_tokenemcp.success/mcp.errorno 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) |