Tokens em texto simples na sua configuração MCP: como tirá-los de lá

Onde cada agente de código guarda a configuração dos seus servidores MCP, como encontrar os tokens escritos nela, o que o zn-gate init --wrap-mcp faz com eles (não os remove) e como tirar os valores e desfazer cada passo.

Ver .md

Um servidor MCP muitas vezes precisa de um token, e a forma mais rápida de entregá-lo é colá-lo no env ou nos headers do servidor, no arquivo de configuração do agente. O token fica então em um arquivo de texto simples na sua pasta pessoal ou no seu projeto. Esta página mostra onde cada agente guarda esse arquivo, como encontrar os tokens nele, o que zn-gate init --wrap-mcp faz e não faz com eles, e como tirar os valores e desfazer cada passo. Para o panorama geral de segredos e agentes de código, veja o guia com a lista de verificação.

Onde cada agente guarda seus servidores MCP

Agente Arquivo do usuário Arquivo do projeto Reescrito por init --wrap-mcp
Claude Code ~/.claude.json .mcp.json na raiz do projeto ~/.claude.json
Claude Desktop claude_desktop_config.json (macOS ~/Library/Application Support/Claude/, Windows %APPDATA%\Claude\, Linux ~/.config/Claude/) nenhum esse arquivo
Cursor ~/.cursor/mcp.json .cursor/mcp.json ~/.cursor/mcp.json
Codex CLI ~/.codex/config.toml (ou $CODEX_HOME/config.toml) .codex/config.toml (somente projetos confiáveis) o arquivo do usuário
OpenCode ~/.config/opencode/opencode.json (ou opencode.jsonc) opencode.json no projeto o arquivo do usuário
Antigravity ~/.gemini/config/mcp_config.json .agents/mcp_config.json os arquivos do usuário (o zn-gate também procura ~/.gemini/antigravity/mcp_config.json)

~/.claude.json também guarda os servidores configurados para um único projeto, em projects. O init --wrap-mcp envolve apenas os mcpServers de nível superior desse arquivo, então as entradas por projeto ficam sem envoltório; o audit as verifica.

Os caminhos do Claude Code, Cursor, Codex CLI e OpenCode vêm da documentação de cada agente; os do Claude Desktop e do Antigravity seguem a documentação do zn-gate e a página do Antigravity. O init --wrap-mcp não mexe nos arquivos de projeto: um token em um arquivo de projeto continua onde está. Para VS Code, Windsurf, Cline, Zed, JetBrains e Continue, veja Editores.

Encontre os tokens

npx -y zn-gate reach
npx -y zn-gate audit --include-home

O reach exige zn-gate 1.12.0 ou posterior. Os dois são somente leitura. Eles apontam um valor secreto escrito na configuração de um agente (regra ZNA011) e nunca imprimem o valor. Execute audit a partir da pasta de um projeto para verificar também os arquivos dele; --include-home acrescenta os arquivos da sua pasta pessoal da tabela acima (exceto os do Claude Desktop e do Antigravity). Os dois usam a detecção própria do zn-gate, então um token em um formato que ela não conhece pode passar despercebido: leia você mesmo os arquivos de configuração também.

O que zn-gate init --wrap-mcp faz com um token

Ele não o remove. Em cada servidor local (stdio), muda apenas o comando de inicialização: o comando original passa a ser o argumento de npx -y zn-gate shield --. O resto da entrada, inclusive env, fica como estava. O shield então verifica as descrições das ferramentas, os argumentos das chamadas e a saída das ferramentas, e remove da saída os segredos que reconhece antes de o seu agente lê-la (detalhes). Isso protege o que o agente recebe do servidor. Não protege o arquivo.

Outros fatos sobre o comando:

  • Servidores remotos (URL) são deixados como estão, então um token em uma entrada headers permanece.
  • Antes de gravar um arquivo, ele o copia ao lado do original como <arquivo>.bak.<carimbo de data e hora>. Essa cópia é o arquivo como estava, com os tokens.
  • Arquivos do OpenCode com comentários e entradas do Codex com args em várias linhas não são reescritos; o init os indica como "wrap manually".
npx -y zn-gate init --dry-run    # pré-visualização, não altera nada
npx -y zn-gate init --shadow     # envolve, apenas registra
npx -y zn-gate init --wrap-mcp   # envolve e aplica
npx -y zn-gate init --revert     # restaura a última cópia de cada arquivo

Tire o valor

Coloque o token em uma variável de ambiente e faça a configuração se referir a ela pelo nome. O que diz a documentação de cada agente:

  • Claude Code, em .mcp.json: ${VAR} (e ${VAR:-default}) é expandido em command, args, env, url e headers. Para url e headers de um servidor remoto, a documentação do Claude Code acrescenta um limite para variáveis de credenciais; leia-o antes de confiar nisso ali.
  • Cursor, em mcp.json: ${env:NAME} é resolvido em command, args, env, url e headers.
  • Codex CLI, em config.toml: env_vars repassa variáveis do ambiente do Codex a um servidor stdio, bearer_token_env_var indica a variável que guarda um token bearer e env_http_headers associa nomes de cabeçalhos a nomes de variáveis. O arquivo guarda apenas nomes.
  • OpenCode: {env:VARIABLE_NAME} é substituído nos arquivos de configuração, e a documentação de MCP dele o mostra nos cabeçalhos.
  • Claude Desktop, Antigravity e os outros editores: não verificamos uma forma de se referir a uma variável de ambiente nos arquivos MCP deles, então esta página não dá nenhuma.

Exemplo para o Cursor, com um servidor e uma variável inventados (EXAMPLE_API_TOKEN):

{
  "mcpServers": {
    "example": {
      "command": "npx",
      "args": ["-y", "example-mcp-server"],
      "env": { "EXAMPLE_API_TOKEN": "${env:EXAMPLE_API_TOKEN}" }
    }
  }
}

A variável precisa existir no ambiente do processo do agente: defina-a onde você inicia o agente (o perfil do seu shell, ou a forma como o seu sistema operacional define variáveis), reinicie o agente e confira se o servidor conecta. Lembre-se de que o perfil do shell também é um arquivo de texto simples que o agente pode ler, então colocar o token ali só o move para outro arquivo. O melhor é usar o chaveiro do sistema operacional ou um gerenciador de segredos para fornecer a variável ao iniciar o agente, ou ao menos guardar o token em um arquivo fora de qualquer pasta que o agente abra.

Uma ordem segura

  1. Execute npx -y zn-gate reach e anote quais arquivos têm um token.
  2. Troque cada token por uma referência a uma variável de ambiente, como acima, e reinicie o agente.
  3. Rotacione todos os tokens que já estiveram no arquivo, se ele foi commitado, copiado, compartilhado ou enviado, se um agente pôde lê-lo ou se o token apareceu em uma transcrição. Um valor que você tirou do arquivo continua válido até você revogá-lo no provedor.
  4. Só então execute npx -y zn-gate init --dry-run, depois --shadow e depois --wrap-mcp. A cópia que ele grava contém o arquivo sem os tokens.
  5. Se você envolveu primeiro: apague os arquivos .bak.<carimbo de data e hora> ao lado dos seus arquivos de configuração depois de tirar os tokens, porque eles ainda guardam os valores antigos.
  6. Execute npx -y zn-gate reach de novo.

Para que serve zn env shadow e para que não serve

zn env shadow .env move os valores de um arquivo .env para o cofre local do zn-gate e deixa marcadores no arquivo (Scrubber). Ele lê linhas CHAVE=valor. Os arquivos de configuração MCP são JSON ou TOML, e a documentação do zn-gate não descreve env shadow para eles, então não o aponte para um deles.

Como desfazer cada passo

  • Envolver: npx -y zn-gate init --revert copia a última .bak.<carimbo de data e hora> de volta sobre cada arquivo de configuração. Tudo o que você mudou no arquivo depois de envolver se perde, e se a cópia tem tokens, eles voltam. Depois do passo 2, desfaça à mão: em cada entrada, ponha o comando e os argumentos originais no lugar de npx -y zn-gate shield --.
  • Referências a variáveis de ambiente: só ponha o valor de volta no arquivo se for inevitável, e nunca em um arquivo que você commita.
  • env shadow: zn env unshadow ARQUIVO --backup NOME, com o nome que o env shadow imprimiu.

Limites

  • A detecção encontra formatos conhecidos; um token sem formato conhecido pode passar despercebido.
  • Envolver verifica o que um servidor devolve e o que o agente envia a ele. Não impede que outro programa leia o arquivo de configuração.
  • Um arquivo de projeto como .mcp.json fica fora do init --wrap-mcp.
  • Um token que você moveu para uma variável de ambiente é visível a qualquer programa iniciado com esse ambiente.

Perguntas frequentes

O zn-gate init --wrap-mcp remove os tokens da minha configuração MCP? Não. Ele muda o comando de inicialização dos servidores locais e deixa env e headers como estavam.

A cópia de segurança guarda os meus tokens? Sim, se eles estavam no arquivo quando você envolveu. Apague os arquivos .bak.<carimbo de data e hora> depois de tirar os valores.

Posso usar zn env shadow em mcp.json? Ele está documentado apenas para arquivos .env.

Como confiro que não sobrou nada? Execute npx -y zn-gate reach e npx -y zn-gate audit --include-home, e leia os arquivos você mesmo.

Fontes