Tokens MCP

O token que o agente usa para falar com o RootPilot é um PAT — personal access token. Ele dá acesso de leitura à sua infraestrutura inteira, através do Agent que roda nela. É uma credencial de primeira grandeza, e esta página é o que você precisa saber para emitir uma sem se arrepender.

O token é de uma pessoa, não da organização

Isso tem uma consequência que precede qualquer decisão de escopo: um token sem dono é sempre read-only. Tokens emitidos fora de um usuário — pela CLI de operação, ou herdados de antes de os tokens serem pessoais — não têm identidade para atribuir, então o gate de escrita falha fechado e eles nunca escrevem. Se o que você quer é um agente que abre ticket, o token precisa pertencer a alguém.

Duas portas em série

A escrita passa por duas verificações independentes, e passar numa não é passar na outra:

O escopo do token — read ou write, escolhido no momento da emissão.
O papel do usuário dono — a permissão mcp:write, que é de owner e admin.

O escopo é uma restrição adicional, nunca uma promoção:

Escopo do token	Papel do dono	Resultado
`read`	owner / admin	Somente leitura
`read`	member	Somente leitura
`write`	owner / admin	Leitura + as cinco ferramentas de escrita
`write`	member	Somente leitura
qualquer	sem dono (CLI/legado)	Somente leitura

A porta do papel é a que falha fechada: usuário inativo, papel que não resolve, erro de consulta — tudo isso nega a escrita em vez de liberá-la. A do escopo só sabe bloquear, e é por isso que ela é uma restrição a mais, nunca a única.

Por que alguém escolheria write, então? Só por um motivo concreto: aquela pessoa quer que o agente dela abra um chamado no Jira ou poste no Slack durante uma investigação, sem sair do fluxo. Fora disso, read é o certo — e é o default do formulário de emissão, de propósito. O que exatamente um token write destrava está em o que o agente escreve.

Mostrado uma vez

No momento da criação, o valor cru do token aparece uma única vez. O que persiste no nosso banco é só o sha256 dele.

Não há recuperação. Não existe tela de “ver o token de novo”, nem suporte que consiga extraí-lo — nós literalmente não o temos. Perdeu, o caminho é revogar e emitir outro.

Solicitação → aprovação → claim

Um member não precisa virar admin para ter acesso ao MCP. Ele pede, alguém autoriza, e ele mesmo gera:

Estado	O que já aconteceu	O que falta
`pending`	O solicitante pediu (nome, escopo, motivo)	Um owner/admin revisar
`approved`	Um owner/admin autorizou o nome e o escopo	O solicitante ainda precisa gerar o token
`claimed`	O solicitante gerou — e viu o valor, uma vez	Nada; o token existe
`denied`	Um owner/admin recusou	Nada; a solicitação está encerrada

O estado que confunde é o approved, e vale dizer com todas as letras: aprovado não é ter token. A aprovação autoriza; o token só passa a existir quando o próprio solicitante o gera. Até lá, não há segredo nenhum criado.

Onde cada lado age: quem solicita e depois gera vê as suas solicitações no perfil; quem revisa vê a fila em Governança.

Uma segunda geração da mesma solicitação não acontece: a transição approved → claimed é atômica, então duas tentativas simultâneas produzem um token só.

Revogação

Revogar é soft — o token é marcado como revogado, e a linha continua existindo para efeito de trilha. A revogação é escopada por organização (não há como revogar token de outra) e vira evento de auditoria.

O efeito é imediato na prática: a identidade do token é resolvida a cada requisição, não só na abertura da sessão. Uma sessão MCP em curso com um token revogado morre na chamada seguinte, com 401. Não é preciso esperar nada expirar.

Como você percebe que um token está vivo

Duas colunas de metadado existem exatamente para isso, e as duas são o que separa “token esquecido” de “token em uso por alguém”:

Último uso. Atualizado quando o token autentica (com uma janela de um minuto, para não escrever a cada requisição). Um token que ninguém usa há meses é candidato a revogação — e é a lista mais barata de higiene que existe aqui.
Origem observada. O endereço de rede com que aquele token chegou até nós pela última vez — é como um uso vindo de onde ninguém esperava fica visível, e é por onde se começa a configurar a allowlist de origem, em vez de adivinhar o bloco. Guardamos só o último endereço, ele é apagado junto com o token no revoke, e some sozinho depois de 90 dias sem se repetir; quem não quiser o registro desliga, na mesma tela da allowlist.

Onde o token vaza

Não são cenários hipotéticos; são os três de sempre:

.mcp.json commitado. O arquivo de configuração do cliente MCP vive no diretório do projeto. Se o token literal estiver dentro, ele entra no repositório — e continua válido no histórico depois de “removido”.
Log de CI. Um echo de variáveis, um comando com --verbose, um dump de ambiente em passo que falhou.
Backup de laptop. Sincronização de diretório de projeto para nuvem pessoal.

Ao suspeitar, revogue. É a única resposta que fecha o buraco. A allowlist de origem de rede reduz a janela — o token vazado deixa de bastar, porque também é preciso estar na sua rede —, mas ela não substitui a rotação, e quem tiver acesso tanto ao token quanto à rede permitida continua passando.

O que fica registrado

Emissão, revogação e cada passo do fluxo de solicitação viram evento na trilha de auditoria da sua organização, com o autor. As escritas feitas com o token são uma trilha separada, com atribuição por usuário — ver o que o agente escreve.