Phantom Secrets: um proxy local e um servidor MCP que ocultam os segredos reais dos agentes de codificação com IA

Para quem é

Se você ligou um agente de codificação com IA ao seu dia a dia de desenvolvimento e o .env do seu projeto guarda segredos reais, os logs, os ecos de erro e os trechos de contexto podem todos virar caminhos de vazamento. O Phantom atende quem precisa de uma fronteira nítida entre “a aplicação continua recebendo os valores reais” e “o agente nunca enxerga o valor do segredo”, além de equipes que querem distribuir e rotacionar segredos de forma centralizada sem empurrá-los para a toolchain de cada pessoa.

A forma dele é “proxy local + servidor MCP”: os segredos do projeto são substituídos por marcadores phm_ com escopo, a aplicação busca os valores reais por meio de um proxy local autenticado e o lado do agente só tem acesso a ferramentas MCP cegas a valores, usadas para inventário, diagnóstico e requisições controladas. A premissa é que você queira manter um processo proxy sempre em execução na sua máquina e incluir a reescrita do .env no seu próprio processo de controle de versão — essa etapa não é algo que se pule à toa.

Três minutos para a primeira tentativa

O caminho oficial recomendado é o Homebrew. A instalação em macOS indicada pelo repositório é uma cadeia de três passos: primeiro tap, depois trust e por último install; o resultado são dois executáveis, phantom e phantom-mcp, correspondentes à versão v0.7.9 apontada pelo repositório.

brew tap ashlrai/phantom
brew trust --formula ashlrai/phantom/phantom
brew install ashlrai/phantom/phantom

Pré-requisitos: o Homebrew precisa já estar instalado no macOS; se você não usar o Homebrew e compilar o código-fonte por conta própria, o repositório fixa a versão da cadeia de ferramentas de compilação, então seu ambiente de build precisa da cadeia de ferramentas Rust correspondente.

Aí vêm dois passos de configuração, em ordem. Primeiro entre no diretório do projeto e execute phantom init; atenção, isso é uma operação de escrita — ele reescreve o .env desse projeto e troca os valores reais das chaves por marcadores phm_; o ponto de controle é confirmar antes de executar que o .env está salvo em backup ou versionado, e conferir na saída do comando se o número de substituições bate com o esperado. O segundo passo grava a configuração do cliente:

phantom init
phantom setup --client claude

Depois, use o passo somente leitura para uma verificação de baixo risco: o phantom list lista seu inventário de segredos sem mostrar nenhum valor. O sinal de sucesso observável é o terminal listar os nomes dos itens e nenhum caractere de segredo real aparecer atrás de nenhum deles; então peça ao agente para ler o repositório mais uma vez e o que ele recebe são coisas que começam com phm_ em vez dos valores reais.

Para a referência completa de comandos e opções, consulte o repositório oficial https://github.com/ashlrai/phantom-secrets

Casos de uso

Caso um: dar ao agente um canal em que ele vê o inventário, mas não os valores. As ferramentas MCP do lado do agente são cegas a valores e cobrem três usos: inventário, diagnóstico e requisições controladas; o repositório posiciona essas ferramentas como verificações de capacidade, de status e de estado do repositório, que não disparam nenhuma ação do lado do provedor. Assim você pode perguntar ao agente sem receio “quais segredos este projeto configurou, se o caminho atual está funcionando e quais arquivos do repositório referenciam marcadores” — o agente não devolve os valores dos segredos nem altera recursos de nuvem por conta própria durante a verificação.

Caso dois: deixar o código de aplicação continuar rodando com os valores reais, ao mesmo tempo em que esses valores ficam fora da vista do agente. A substituição acontece na fase de inicialização: os valores reais das chaves no .env viram marcadores phm_ com escopo, a aplicação lê as variáveis de ambiente como sempre e as requisições que ela dispara são assumidas pelo proxy local, que recupera os valores reais após a autenticação. O ponto de entrada de requisições controladas do lado do proxy compartilha a mesma restrição “sem valores” que os pontos de entrada de inventário e de diagnóstico, então a aplicação funciona e o agente continua sem conseguir os segredos em si. Vale notar que a documentação do repositório só diz que o proxy é um proxy local “autenticado” e não detalha a forma específica dessa autenticação; nessa camada, siga a descrição do repositório.

Limites de uso

Primeiro, o phantom init reescreve o .env e é uma operação de escrita de verdade. Faça backup ou commit antes de executar e não cole o diff antes/depois diretamente em canal público.

Segundo, a natureza cega a valores das ferramentas do lado do agente só garante “não ver valores”, não “fazer qualquer coisa”. O repositório as posiciona como verificações de capacidade, de status e de estado do repositório e não dispara ações de provedor por você; as chamadas reais para a nuvem acontecem na rota de requisição que a aplicação envia pelo proxy local, então na investigação é preciso separar esses dois trechos.

Terceiro, não é uma ferramenta sem risco: ela precisa ler o .env local e os arquivos de configuração do cliente, e o proxy local envia requisições a provedores terceiros, então os segredos continuam fluindo entre a sua máquina e aquele provedor. Aceitar ou não esse caminho depende de a sua organização permitir que ele exista do lado do agente.

Quarto, os métodos de instalação e as descrições de comandos no repositório mudam de versão; antes de atualizar, volte ao repositório oficial para conferir.