# Tire os agentes MCP das variáveis de ambiente: migre as credenciais

Colocar credenciais no ambiente de um servidor MCP é um atalho que se torna perigoso quando um agente pode executar comandos, inspecionar arquivos, investigar falhas ou iniciar processos auxiliares. O problema não é que todo agente vá imprimir um token de propósito. O problema é que você entregou a um processo criado para explorar e agir um segredo reutilizável e depois pediu que ele se comportasse como se não pudesse enxergá-lo.

Tire a autoridade do processo do agente. Faça o agente solicitar uma ação HTTP ou SSH definida e deixe um componente local, que mantém a credencial, executá-la. A mudança parece pequena, mas obriga você a identificar o que cada ferramenta realmente faz, de qual identidade ela precisa e como provar que o token não entrou sorrateiramente no novo caminho.

Já vi migrações falharem porque alguém removeu `API_TOKEN` de um arquivo de configuração, mas o deixou em um perfil do shell, em um executor de tarefas ou em um modelo de projeto copiado. A chamada de API continuou funcionando, todos relaxaram e o agente ainda tinha a credencial antiga. Uma migração limpa trata descoberta, substituição e comprovação como tarefas separadas.

## As variáveis de ambiente dão ao agente mais autoridade do que a ferramenta precisa

Uma variável de ambiente não pertence a uma única requisição. Ela pertence a um processo e, muitas vezes, a tudo que esse processo inicia. Se um cliente MCP inicia um servidor com `SERVICE_TOKEN` no ambiente, o servidor pode lê-lo. O mesmo vale para processos filhos que o herdam, a menos que alguém o remova cuidadosamente. Comandos de depuração, relatórios de falhas, fixtures de teste e uma saída acidental de `env` podem transformar uma conveniência local em um vazamento duradouro.

Isso é diferente de uma ferramenta receber um resultado autenticado. O resultado pode conter uma lista de repositórios, o status de uma implantação ou uma resposta de erro. O agente precisa dessas informações para continuar o trabalho. Ele não precisa do token bearer que tornou a requisição possível.

A diferença fica menos clara porque os dois desenhos podem produzir a mesma requisição bem-sucedida. Eles não são equivalentes:

- **Posse da credencial** significa que o agente pode usar, copiar, transformar ou exfiltrar um segredo fora da chamada de ferramenta prevista.
- **Autoridade de ação** significa que o agente pode pedir a um executor local confiável que faça uma requisição sob controles definidos.
- **Acesso ao resultado** significa que o agente vê a resposta necessária para decidir o próximo passo.

Confundir essa diferença leva a uma recomendação ruim e comum: colocar os tokens em um gerenciador de segredos e depois injetá-los no ambiente do agente na inicialização. Isso pode melhorar o armazenamento em repouso, mas não muda o limite em tempo de execução. O agente ainda recebe o token.

A especificação do MCP descreve um protocolo para clientes, servidores e ferramentas. Ela não declara que variáveis de ambiente são um limite de credencial. Trate-as como transporte para configuração local apenas quando o processo que as recebe já for confiável para manter o segredo subjacente. Agentes autônomos de programação muitas vezes não atendem a esse padrão.

## Crie um inventário de ferramentas antes de mudar qualquer configuração

Comece com um inventário por escrito. Não comece editando arquivos JSON, porque os arquivos de configuração raramente contam toda a história. Uma ferramenta pode ler uma variável diretamente, chamar um wrapper que lê outra ou depender de um cliente de linha de comando que carrega credenciais de um arquivo no diretório pessoal.

Para cada ferramenta MCP, registre o nome da ferramenta, o comando, o destino, o método de autenticação, o responsável pela credencial, o escopo de permissão e a requisição inofensiva que você pode usar para testar. Registre também onde o segredo entra atualmente no processo: configuração do cliente, arquivo de inicialização do shell, arquivo `.env`, exportação de CI, comando do gerenciador de senhas ou script auxiliar.

Um inventário compacto pode ter esta aparência:

| Ferramenta | Destino da ação | Caminho atual do segredo | Novo limite | Teste |
| --- | --- | --- | --- | --- |
| busca de issues | API de issues | `ISSUES_TOKEN` na configuração do cliente | ação HTTP local | listar um projeto conhecido |
| status da implantação | API de implantação | `.env.local` | ação HTTP local | ler o status do serviço |
| diagnóstico do host | alias de host SSH | caminho do arquivo de chave privada | ação SSH local | executar `uname` |
| publicação de pacote | API do registro | exportação do shell | ação HTTP local | ler os metadados do pacote |

Não esconda permissões amplas em nomes vagos como `prod-token` ou `default-key`. Dê ao registro da credencial um nome que informe ao operador o que ela pode fazer e para onde vai. `deploy-api-production-read` é menos bonito e muito mais seguro durante uma revisão apressada.

O inventário também revela se uma credencial deveria existir. Já encontrei tokens com permissão de escrita ligados a ferramentas que apenas liam metadados de projetos, porque alguém copiou uma configuração de desenvolvimento. A migração é o momento certo para emitir credenciais mais restritas. Ela não é um motivo para preservar todos os privilégios antigos dentro de um contêiner mais organizado.

## Remova a injeção do segredo em vez de disfarçá-la

Uma configuração migrada precisa parar de entregar o segredo ao agente ou ao servidor MCP. Trocar um token literal por `${SERVICE_TOKEN}`, `$(secret-tool lookup ...)` ou pelo caminho de um arquivo desprotegido não atende a esse requisito. Você mudou a grafia, não a autoridade.

Primeiro, encontre as referências atuais. Em um diretório de projeto, isto captura muitos casos óbvios:

```sh
rg -n --hidden --glob '! .git' 'API[_-]?KEY|API[_-]?TOKEN|SECRET|PASSWORD|PRIVATE[_-]?KEY|Authorization: Bearer' .
```

A saída esperada tem o formato de uma lista de entradas `arquivo:linha:texto correspondente`. Não cole essa saída em uma issue se ela incluir valores ativos. Use-a para criar uma lista de correções e depois pesquise separadamente nos locais usuais do usuário, como perfis do shell e configurações do cliente MCP.

Em seguida, compare o ambiente visível para o processo antigo do agente com o ambiente visível para o novo. Em um shell de teste controlado, liste os nomes sem imprimir os valores:

```sh
env | cut -d= -f1 | sort | rg 'TOKEN|KEY|SECRET|PASSWORD'
```

Você quer que os nomes antigos desapareçam do processo que inicia o agente. Se `SERVICE_TOKEN` aparecer ali, a migração está incompleta, mesmo que o novo caminho pelo gateway funcione.

Evite o desenho intermediário tentador em que o servidor MCP tem o token, mas o agente principal não. Isso reduz um caminho de exposição, mas o servidor ainda recebe a posse irrestrita da credencial. Se esse servidor puder executar comandos arbitrários, carregar plugins ou gravar logs, você apenas transferiu o problema para um processo que costuma receber menos atenção.

Use configuração sem segredos para selecionar o destino. Uma URL base, um alias de host, um identificador de conta e um rótulo de credencial podem ficar na configuração se não concederem acesso. Mantenha o material autenticado em um cofre local que o agente não possa consultar como dados.

## Modele o novo caminho como requisições, credenciais e resultados

O novo fluxo deve ter um limite rígido: o agente nomeia uma ação e fornece dados comuns da requisição, o executor local seleciona e injeta a credencial e depois devolve a resposta. O agente nunca recebe um placeholder que possa resolver para obter o segredo.

Em uma ferramenta HTTP, separe o formato público da requisição da etapa privada de autenticação. O agente pode solicitar esta requisição:

```text
GET https://api.example.internal/projects/atlas/issues?state=open
```

O executor local anexa a credencial bearer, básica ou de cabeçalho personalizado apropriada e devolve o corpo e o status da resposta. Se o agente solicitar um host, método ou conta não aprovados, o executor deve negar a requisição, sem tentar adivinhar qual credencial se encaixa.

No SSH, a requisição tem um host e um comando, enquanto a chave privada permanece local. Isso importa porque as ferramentas SSH costumam transferir autoridade por caminhos, encaminhamento do agente, inclusões de configuração e `SSH_AUTH_SOCK` herdado. Um caminho de chave privada na configuração da ferramenta não é uma substituição segura. Muitas vezes, o agente consegue ler o arquivo, copiá-lo ou alterar o comando que o utiliza.

O Sallyport usa esse formato por meio do seu shim stdio `sp mcp` integrado: os agentes fazem chamadas MCP, enquanto o aplicativo executa chamadas de API HTTP e comandos SSH sem entregar chaves de API ou SSH ao agente. Esse limite só é útil se você também remover a antiga injeção no ambiente.

Não transforme o executor local em um proxy de uso geral com uma única credencial todo-poderosa. A requisição do agente deve identificar um destino e uma credencial configurados, não fornecer uma URL arbitrária mais uma escolha de token. Caso contrário, um agente manipulado por um prompt pode transformar uma credencial legítima em um assinador de requisições para um lugar que você nunca pretendeu alcançar.

## Escolha pontos de aprovação que as pessoas ainda consigam avaliar

A aprovação humana funciona quando uma pessoa consegue entender o que está aprovando. Ela falha quando um agente de longa duração gera uma pilha de pedidos quase idênticos até que a pessoa clique em todos. Essa falha é previsível e representa um problema de projeto, não uma falha de atenção do operador.

Use uma aprovação por sessão quando precisar estabelecer que um processo específico de agente pode usar as ações configuradas durante uma execução. A aprovação deve identificar o processo de uma forma que ajude a distinguir o cliente real de uma imitação. O nome do processo, sozinho, é uma evidência fraca, porque qualquer programa pode escolher um nome familiar.

Reserve a aprovação por chamada para credenciais com consequências que exigem um julgamento humano renovado. Acesso de escrita em produção, um comando destrutivo em um host e uma API relacionada a pagamentos justificam esse atrito. Uma busca de issues somente leitura normalmente não. Se toda chamada de ferramenta exigir uma decisão, os operadores deixarão de ler a decisão.

Um cofre bloqueado deve negar requisições, mesmo que um agente previamente aprovado continue em execução. Esse é o objetivo de uma barreira do cofre. Um processo sem supervisão não deve manter autoridade apenas porque a recebeu mais cedo naquele dia.

O Sallyport tem três controles fixos, em vez de uma linguagem de políticas: uma barreira do cofre, autorização para cada novo processo de agente e um requisito opcional de aprovação por chave. O modelo fixo é deliberadamente mais restrito do que um mecanismo de regras, o que deixa menos regras complexas para um operador cansado escrever errado.

## Teste o sucesso e o sigilo como afirmações separadas

Uma resposta positiva da ferramenta prova apenas que algo autenticou a requisição. Ela não prova que o agente não conseguiu obter a credencial. Execute um teste de migração que verifique as duas afirmações, começando por uma ação de baixo risco.

Use esta sequência para cada ferramenta:

1. Bloqueie o cofre local e invoque a ferramenta. A chamada deve falhar sem recorrer a um token de ambiente.
2. Desbloqueie o cofre, inicie um processo novo do agente e aprove esse processo, se sua configuração exigir isso. Execute a requisição inofensiva identificada no inventário.
3. Inspecione o diário de ações ou o registro de auditoria no servidor para conferir o destino exato, a conta, o método e o status do resultado. Confirme que a ação foi registrada sem registrar o segredo.
4. Pelo caminho de execução permitido ao agente, inspecione o ambiente dele em busca do nome da variável antiga e pesquise no espaço de trabalho o prefixo do token. O token não deve aparecer em nenhum dos dois lugares.
5. Reinicie o processo do agente e repita a requisição. Isso verifica que você não dependeu acidentalmente de um estado herdado do shell antigo.

A primeira etapa captura um erro sutil e sério. Às vezes, as equipes configuram um caminho para o cofre, mas deixam a variável antiga como alternativa. Quando o cofre é bloqueado, a ferramenta continua funcionando. Isso parece confiável até que a mesma alternativa apareça em um worker de CI, em um repositório copiado ou na transcrição de um agente.

Não peça ao agente para imprimir todas as variáveis de ambiente como sua principal comprovação. Esse teste cria uma rota de divulgação e pode colocar o token antigo no histórico da conversa. Verifique os nomes em um shell controlado e use uma variável de marcação deliberadamente sem segredo durante simulações, se precisar validar o comportamento de herança.

Para SSH, teste um comando que retorne informações inofensivas sobre a identidade do sistema, em vez de um comando que altere o estado. Confirme o resultado e depois confirme que a configuração do agente contém uma referência ao host, não o material da chave privada. Inspecione também a configuração SSH em busca de `ForwardAgent yes`. O encaminhamento do agente pode dar a um host remoto um caminho para usar identidades locais, o que representa um risco diferente da exposição do arquivo de chave privada.

## Os registros de auditoria precisam permitir a reconstrução de uma ação contestada

Um log de ações é útil quando responde a uma pergunta difícil em uma segunda-feira de manhã: qual execução de agente fez esta requisição, por meio de qual credencial configurada e uma pessoa a aprovou? Uma linha vaga como `tool succeeded` não resolverá nada.

Mantenha um registro de sessão para as execuções dos agentes e um registro de chamada para ações individuais. O registro de sessão informa quando um processo começou, qual identidade você aprovou e quando a revogou. O registro de chamada informa o que aconteceu nessa sessão. Não misture os dois em um único fluxo plano de eventos se precisar investigar uma execução entre muitas.

A evidência contra adulteração importa porque um agente com execução de comandos local pode tentar apagar seus rastros depois de uma ação indesejada. Um log encadeado por hashes permite detectar histórico alterado ou removido, mas apenas se a verificação não depender da cooperação do agente.

O Sallyport gera os dois diários a partir de um log de auditoria criptografado, somente para gravação e encadeado por hashes, e oferece verificação offline da cadeia sobre o texto cifrado com este comando:

```sh
sp audit verify
```

Um resultado positivo deve indicar que a verificação foi concluída com sucesso. Uma falha deve fazer você tratar o diário como suspeito até entender a interrupção. A verificação não informa se a ação foi prudente. Ela informa se o registro ainda mantém continuidade.

Mantenha os dados de auditoria fora dos prompts do modelo e das transcrições normais de chat. O registro pode conter contexto sensível da requisição ou metadados da resposta, mesmo quando nunca contém a credencial. O acesso para investigação não deve se tornar uma porta dos fundos para navegação casual.

## A alternância é a limpeza que prova que você realmente fez a migração

Depois que cada novo caminho passar pelos testes, alterne a credencial antiga. Deixá-la válida porque «talvez precisemos reverter» prolonga o período em que configurações esquecidas ainda podem autenticar. Planeje a reversão com uma substituição controlada separadamente, não com um segredo que você já espalhou pelos ambientes locais.

A ordem da alternância importa. Crie a nova credencial com escopo restrito, armazene-a localmente, valide o novo caminho, remova a injeção do segredo antigo e depois revogue a credencial antiga. Se um token antigo pode ter aparecido no controle de versão, em uma mensagem de chat, em um ticket de suporte ou na saída de um build, revogue-o primeiro e aceite a interrupção enquanto restaura o acesso seguro.

Repita a pesquisa de descoberta depois da revogação. Você está procurando referências antigas, não valores secretos ativos. Remova nomes de variáveis obsoletos de arquivos de exemplo, documentos de integração, perfis do shell, scripts de tarefas e instruções de teste. Futuros desenvolvedores copiam exemplos com uma fidelidade surpreendente.

Por fim, deixe um teste de falha deliberado nas suas notas operacionais: bloqueie o cofre e execute uma chamada de ferramenta inofensiva. Se a chamada funcionar, alguém reintroduziu um desvio. Esse único teste captura mais migrações malfeitas do que outro diagrama de arquitetura bem acabado.

## Trate credenciais amplas como uma falha no projeto da ferramenta

Mover um token para um cofre não torna apropriado para um agente um token amplo. Isso apenas muda quem o mantém. Uma ferramenta que consulta issues de projetos não deve carregar silenciosamente permissão para excluir projetos, alterar cobranças ou implantar código em produção.

Divida as ferramentas de acordo com o trabalho real e suas consequências. Ações de descoberta somente leitura podem usar uma credencial limitada e uma aprovação simples. Ações que alteram o estado merecem escopos mais restritos, destinos explícitos e, às vezes, consentimento por chamada. Isso também facilita a supervisão do agente, porque os verbos disponíveis correspondem à tarefa que você deu a ele.

Desconfie de uma credencial universal `admin` justificada pela simplicidade da ferramenta. Essa configuração é popular porque reduz o trabalho de configuração hoje. Amanhã, ela piora a resposta a incidentes, porque você não consegue distinguir quais requisições precisavam desse poder e quais simplesmente o herdaram.

A migração é bem-sucedida quando um agente consegue concluir o trabalho previsto, um cofre bloqueado o interrompe, um processo novo precisa conquistar a autoridade configurada e nenhum token antigo permanece no ambiente dele. Se alguma dessas afirmações não tiver um teste, você tem uma demonstração funcionando, não um limite de credencial.