Permissões e segurança
Como o conector MCP decide o que cada usuário enxerga e executa — escopos, cargos, unidade, aprovações, rate limit e auditoria.
Permissões e segurança
O conector não dá poderes novos a ninguém. Ele reaproveita as mesmas regras do dashboard: se você não consegue cancelar uma mensalidade na tela, o Claude também não consegue por você.
Dois eixos de autorização
Escopo da conexão × cargo do usuário
O escopo é o teto da conexão; o cargo é o teto da pessoa. Vale o menor dos dois.
1. Escopo da conexão
| Escopo | O que libera |
|---|---|
mcp:read | Ferramentas de leitura |
mcp:write | Ferramentas de escrita (implica mcp:read) |
Quando o cliente de IA não pede escopo — o caso mais comum — a conexão recebe
mcp:read mcp:write. Numa conexão só de leitura, as ferramentas de escrita não aparecem na
listagem. Conexões antigas com portal.read / portal.write continuam válidas e são traduzidas
para os escopos acima.
2. Cargo do usuário (RBAC)
Cada ferramenta é mapeada para a mesma permissão que a rota HTTP equivalente exige. O conector é fail-closed: ferramenta sem permissão mapeada fica oculta.
| Permissão | Cobre |
|---|---|
students:read / students:manage | Clientes, alunos, deals e sinais de risco |
students:enroll | Matricular aluno (a Recepcionista tem, sem acesso financeiro amplo) |
finance:read / finance:manage | Mensalidades, títulos, DRE, caixa, adquirente, fornecedores |
commissions:read | Comissões apuradas |
plans:read / plans:manage | Planos e eventos (categorias de evento são planos) |
classes:read | Aulas, tipos de aula e instrutores |
workouts:read | Fichas de treino e biblioteca de exercícios |
access:read | Ocupação e check-ins |
sales:read / products:manage | Catálogo, vendas e estoque |
promotions:read / promotions:manage | Cupons |
marketing:read / marketing:manage | Campanhas, listas, WhatsApp e Meta Ads |
team_members:read / team_members:manage | Equipe (sem dados sensíveis de RH) |
portal:read / portal:manage | Portal white-label |
| — | Contexto da empresa e unidades (qualquer membro ativo) |
Cargo com acesso total (*) alcança todas as ferramentas não elevadas. A permissão exigida por
ferramenta está no catálogo.
A ferramenta some, não dá erro
Se o Claude não menciona uma capacidade, normalmente é porque ela não está visível para o seu cargo — não porque não existe. Ajuste o cargo em Configurações → Cargos e permissões.
Limite por unidade
Usuário restrito a uma unidade só lê e altera as linhas daquela unidade — inclusive nas buscas que antecedem uma escrita (cancelar, congelar, matricular, atualizar). Admins, donos e conexões por API key são team-wide.
O que sempre passa por aprovação
Ações irreversíveis iniciadas por IA não executam: elas criam uma solicitação no painel de aprovações do OctaGym, para uma pessoa decidir.
| Ação | Regra |
|---|---|
request_payment_refund | Sempre vira solicitação — nunca estorna direto |
merge_suppliers | Sempre |
generate_benefit_batch (VA/VT) | Sempre |
bulk_update_financial_titles | Acima de 20 títulos (até 20 aplica direto, tudo ou nada) |
settle_financial_title | Acima do limite de baixa da empresa |
send_payments_to_paggo | Acima do limite de aprovação de pagamento da empresa |
create_financial_title | Quando a política de Compras da empresa exigir |
| Escritas de Meta Ads | Ficam pendentes até meta_confirm_action (ou meta_reject_action) |
Campanhas seguem a mesma filosofia por outro caminho: nascem como rascunho e só saem com
confirm_campaign_send.
Simular antes de gravar
Toda ferramenta de escrita do financeiro aceita dry_run: true — devolve o efeito calculado sem
tocar no banco. O padrão recomendado é sempre: simular, mostrar o resultado, confirmar.
Limites técnicos
- Rate limit de escrita: 60 operações por minuto, por empresa. Acima disso a ferramenta responde pedindo para tentar de novo em instantes.
- Recursos por plano: ferramentas de módulos contratados por plano (notificações, loja) recusam com uma mensagem de upgrade quando o módulo não está no plano da empresa.
- Tempo de execução: até 300 segundos por requisição (as ferramentas de Meta Ads conversam com a Graph API).
Auditoria
Toda escrita é registrada em audit_logs com a ação mcp.<nome_da_ferramenta>, guardando quem fez
(o usuário do OAuth, ou a conexão quando é API key), o cliente de origem e os argumentos da chamada.
Leituras não são auditadas.
Dados que o conector nunca entrega
- RH sensível: salário, documentos e dados bancários de colaborador não são selecionados por nenhuma ferramenta de equipe.
- Credencial de pagamento: dados bancários e chave Pix de fornecedor saem mascarados — o suficiente para conferir com um comprovante, não para pagar.
- Financeiro sem permissão: quem não tem
finance:readrecebe as métricas do negócio com os valores redigidos, igual ao dashboard.