Revise a configuração do cliente MCP antes de confiar em um servidor

Um novo servidor MCP merece a mesma revisão que você faria com um novo executável que pede para ser executado dentro da sua conta de desenvolvimento. O arquivo de configuração pode parecer inofensivo porque contém um comando e alguns argumentos. Na prática, essa entrada decide qual código será iniciado, qual ambiente ele receberá, quais diretórios poderá acessar e quais descrições de ferramentas serão oferecidas a um agente.

O erro que vejo com frequência é tratar «local» como um limite de confiança. Não é. Um servidor local normalmente inicia com as permissões do seu usuário, pode agir antes de publicar sua primeira ferramenta e talvez herde credenciais que ninguém pretendia compartilhar. Revise o contrato de inicialização antes de o cliente se conectar. Depois, revise as ações anunciadas antes que o agente possa chamá-las.

Um servidor local executa com as consequências da sua conta

Um servidor MCP local é um processo filho, não um objeto de configuração inofensivo. Se o cliente o iniciar na sua conta normal do macOS, o servidor poderá ler arquivos de projetos acessíveis, gravar no seu diretório pessoal, fazer solicitações de rede externas e inspecionar as variáveis de ambiente disponíveis para o processo. O MCP não cria um sandbox para o servidor. O protocolo transporta mensagens, mas não limita o que o executável faz entre uma mensagem e outra.

Essa diferença importa quando um servidor chega por meio de um comando de pacote. Esta configuração:

{
  "command": "npx",
  "args": ["-y", "some-mcp-server"]
}

faz mais do que iniciar um binário local conhecido. Ela pede a um executor de pacotes que resolva um pacote, instale ou reutilize código do cache e o execute. Uma máquina limpa, um cache aquecido e uma tag de pacote alterada podem produzir códigos diferentes. O comando familiar faz as pessoas pularem a pergunta importante: qual executável exato será executado hoje?

A mesma preocupação vale para um servidor baixado ao lado do projeto. Um repositório pode conter uma implementação MCP honesta e também um hook de instalação malicioso, um wrapper ou uma dependência de execução. Revise o caminho que inicia o processo, não apenas o arquivo-fonte cujo nome aparece em um guia de configuração.

Use a conta do sistema operacional como sua primeira decisão de contenção. Um espaço de trabalho descartável, uma conta separada com poucos privilégios ou uma máquina virtual dá ao teste inicial menos acesso do que a conta que guarda o código-fonte de produção e as credenciais de nuvem. Isso não substitui a revisão do código. Apenas limita o dano caso algo passe despercebido.

O campo de comando merece uma leitura literal

Leia o comando e os argumentos exatamente como o cliente os executará. Não os traduza mentalmente para a descrição amigável de um README.

O formato mais seguro usa um caminho fixo para o executável e um array de argumentos:

{
  "command": "/Users/dev/tools/acme-mcp/bin/server",
  "args": ["--config", "/Users/dev/review/acme-mcp.json"],
  "env": {
    "HOME": "/Users/dev/review-home",
    "PATH": "/usr/bin:/bin"
  }
}

Esse formato oferece pontos concretos para a revisão. O executável existe nesse caminho? Quem é o proprietário? O arquivo de configuração fica fora de um repositório que outras pessoas podem alterar? O processo realmente precisa de HOME? Ele precisa de um compilador, de um gerenciador de pacotes ou de um PATH amplo?

Um wrapper muda a revisão. Veja este exemplo:

{
  "command": "sh",
  "args": ["-c", "npx -y acme-mcp --token $SERVICE_TOKEN"]
}

Agora o shell expande $SERVICE_TOKEN, interpreta a sintaxe do shell e pode executar mais do que o único programa esperado. O executor de pacotes pode baixar código. O servidor recebe um segredo como argumento de comando, que pode aparecer na inspeção de processos e em diagnósticos. Cada camada tem comportamentos que um caminho direto para o executável evita.

Não presuma que todos os clientes executam command da mesma forma. Alguns usam a criação direta de processos com um array de argumentos. Outros oferecem uma configuração orientada ao shell ou permitem um script intermediário. Leia a documentação do cliente e teste a inicialização com um comando sem informações sensíveis antes de aprovar um comando real. Se o formato permitir execução direta e por shell, escolha a execução direta, a menos que o servidor tenha uma necessidade específica que você consiga explicar.

Inspecione os wrappers linha por linha. Scripts pequenos muitas vezes escondem os comportamentos mais arriscados: baixar uma versão, ler um arquivo de token, alterar o diretório de trabalho, exportar todas as variáveis de ambiente ou reiniciar silenciosamente por meio de outro runtime. Um inicializador de vinte linhas pode merecer mais atenção que a implementação principal do servidor.

O ambiente herdado é o vazamento de credenciais que passa despercebido

Um bloco env não significa necessariamente «este é o ambiente inteiro». Em muitas APIs de inicialização de processos, o ambiente do processo pai é repassado, a menos que o inicializador o substitua deliberadamente. As entradas de env então adicionam ou substituem valores específicos. Seu cliente MCP pode ter sido iniciado por um terminal, um inicializador da área de trabalho, um editor ou um serviço de automação, e cada caminho pode fornecer variáveis diferentes.

Isso cria uma diferença perigosa entre o que os revisores veem e o que o servidor recebe. O JSON pode listar apenas LOG_LEVEL, enquanto o processo também recebe um token de registro de pacotes, um token de controle de versão, credenciais de nuvem, configurações de proxy, detalhes do agente SSH e uma URL de serviço interno herdados do cliente.

Antes de conectar, descreva o contrato do ambiente em linguagem simples: este processo precisa deste endpoint, desta configuração não secreta e talvez de uma credencial com escopo restrito. Todo o resto é autoridade acidental.

Uma primeira verificação útil começa iniciando o próprio cliente a partir de um shell enxuto. Este comando para macOS e Unix preserva apenas algumas variáveis comuns:

env -i HOME="$HOME/review-home" PATH="/usr/bin:/bin" LANG="${LANG:-C}" \
  YOUR_MCP_CLIENT

Substitua YOUR_MCP_CLIENT pelo comando real do cliente. Se o servidor falhar, adicione uma variável por vez e registre por que ela é necessária. Não resolva a falha restaurando todo o ambiente da sua sessão. Esse atalho já expôs mais credenciais do que as pessoas imaginam.

Você também pode inspecionar uma configuração salva sem executar nenhum comando. O fragmento de Python a seguir imprime nomes de servidores, comandos, argumentos e nomes explícitos de variáveis de ambiente. Ele não imprime nenhum valor de ambiente de propósito.

python3 - "$HOME/.config/your-client/mcp.json" <<'PY'
import json, sys

with open(sys.argv[1], encoding="utf-8") as f:
    data = json.load(f)

for name, spec in data.get("mcpServers", {}).items():
    print(f"server: {name}")
    print(f"  command: {spec.get('command', '')}")
    print("  args:")
    for arg in spec.get("args", []):
        print(f"    - {arg}")
    print("  explicit env names:")
    for env_name in sorted(spec.get("env", {})):
        print(f"    - {env_name}")
PY

A saída terá um formato parecido com este:

server: issue-tracker
  command: /Users/dev/tools/issue-mcp/server
  args:
    - --read-only
  explicit env names:
    - ISSUE_TRACKER_URL

Se você encontrar nomes como AWS_SECRET_ACCESS_KEY, GITHUB_TOKEN, SSH_AUTH_SOCK ou SERVICE_TOKEN, pare e pergunte por que o servidor precisa deles. Os valores secretos não ficam seguros só porque estão em um arquivo JSON, e não no código-fonte. Arquivos de configuração são copiados para backups, compartilhados em solicitações de suporte, enviados por acidente para repositórios e lidos por todo processo que tenha acesso ao arquivo.

Uma lista de ferramentas é uma declaração de capacidade, não uma concessão de permissão

A especificação do Model Context Protocol define tools/list para descoberta e tools/call para invocação. Isso é útil porque um cliente pode inspecionar a interface proposta pelo servidor antes que um agente escolha uma ferramenta. Mas isso não certifica o servidor, suas descrições nem os efeitos colaterais por trás de uma chamada.

Trate cada ferramenta anunciada como uma capacidade proposta. Leia seu nome, sua descrição, seu esquema de entrada e todas as anotações em conjunto. Uma ferramenta chamada search_issues pode fazer uma solicitação somente de leitura ou coletar arquivos do projeto e enviá-los a terceiros antes de pesquisar. Uma ferramenta chamada deploy_preview pode criar recursos, alterar o DNS ou usar uma credencial com escopo mais amplo do que o nome sugere.

A especificação MCP permite que os servidores forneçam anotações que indicam comportamentos, como ler dados, alterar dados ou interagir com um sistema externo. Essas indicações ajudam o cliente a apresentar uma interface útil, mas a especificação não as transforma em mecanismos de controle. Um servidor desonesto ou descuidado pode rotular uma ferramenta destrutiva como somente leitura. O sistema operacional e as credenciais do servidor não verificarão esse rótulo antes da execução da ação.

Registre um pequeno inventário para cada servidor aprovado:

• Nome da ferramenta e ação que ela afirma executar.
• Entradas que podem conter caminhos de arquivos, URLs, trechos de shell ou instruções livres.
• Sistemas que a ferramenta pode acessar e a credencial utilizada.
• Efeitos colaterais, incluindo os indiretos, como enviar dados para uma API remota.
• A versão exata ou revisão do código-fonte que você analisou.

Mantenha o inventário perto da configuração. Um diff se torna significativo quando uma atualização adiciona delete_repository, muda query para execute ou acrescenta uma entrada que aceita uma URL arbitrária. Sem um inventário anterior, as pessoas costumam aprovar uma lista alterada porque o nome do servidor ainda parece familiar.

As descrições merecem a mesma desconfiança que qualquer outro texto não confiável entregue a um agente. Um servidor pode descrever uma ferramenta como obrigatória, afirmar que a aprovação é desnecessária ou instruir o agente a passar segredos sem relação com a tarefa como argumentos. O agente não deve tratar a prosa fornecida pelo servidor como autoridade maior que a solicitação do usuário e as regras de aprovação do cliente.

As credenciais precisam de um limite fora do processo do agente

Não entregue um token de API de longa duração ou uma chave SSH privada a um servidor apenas porque ele executa no mesmo laptop. Depois que o processo recebe um segredo, ele pode registrá-lo, encaminhá-lo, gravá-lo em disco ou expô-lo por meio do resultado de uma ferramenta. O cliente não consegue recuperar esse segredo depois que o processo o leu.

Separe duas decisões que as equipes costumam misturar. A permissão para iniciar um servidor é a permissão para executar código. A permissão para usar uma credencial de produção é a permissão para agir em um sistema externo. Um servidor pode merecer a primeira permissão em um espaço de teste e claramente não merecer a segunda.

Para usos simples de desenvolvimento, emita uma credencial com escopo restrito e curta duração, que só possa acessar dados de teste. Registre seu escopo por escrito. «Usada pelo servidor de chamados» é vago; «pode ler chamados no projeto de sandbox e não pode criar, comentar ou alterar membros» oferece algo que os revisores conseguem testar.

Para ações que exigem uma credencial importante, mantenha o segredo em um limite local de credenciais e exponha apenas a operação específica. O Sallyport segue essa abordagem para ações HTTP e SSH: o agente não recebe a chave de API nem a chave SSH, enquanto o app executa a ação e retorna o resultado.

Esse limite muda o tratamento dos segredos, mas não elimina a necessidade de revisar o servidor. Um servidor malicioso ainda pode pedir a um agente que faça uma chamada prejudicial, embora autorizada. Coloque a aprovação onde a consequência acontece, restrinja as credenciais à menor autoridade útil e leia cada solicitação que atravesse o limite de um sistema importante.

Não passe credenciais em argumentos de comando. Listagens de processos, relatórios de falhas, diagnósticos e processos pai podem expô-las. Evite segredos em texto simples nos arquivos de configuração pelo mesmo motivo. Se um guia de configuração exigir um segredo em um desses locais, descubra antes se o servidor pode usar um armazenamento de credenciais do sistema operacional, um token de curta duração ou um serviço externo de ações.

O primeiro contato deve acontecer em uma conta de teste sem surpresas

Execute um servidor desconhecido em uma conta controlada antes de fornecer a ele um projeto, um ambiente amplo ou credenciais reais. Esse teste responde a uma pergunta específica: o que o programa faz ao iniciar e quando o cliente solicita suas ferramentas?

Use um diretório novo com arquivos inofensivos cujos nomes tornem leituras inesperadas evidentes. Dê ao processo um HOME temporário. Comece com um PATH enxuto. Não monte um diretório cheio de código-fonte só porque pretende testar um servidor de controle de versão. Comece com um repositório falso ou uma cópia sem credenciais.

Observe o comportamento antes de qualquer chamada de ferramenta. Um servidor que abre uma conexão de rede, examina seu diretório pessoal, lê dados do navegador ou cria arquivos de persistência durante a inicialização já ultrapassou o que a maioria dos usos do MCP exige. Alguns servidores realmente verificam um endpoint ou carregam uma configuração local. Esse comportamento deve ser fácil de explicar e de desativar.

Depois, solicite o inventário de ferramentas, inspecione-o e faça uma chamada inofensiva com uma entrada conhecida. Registre a solicitação, o resultado, a saída do processo e os arquivos alterados no diretório de teste. Se a ferramenta retornar conteúdo de outro sistema, use dados de teste inconfundíveis para saber se ela acessou o local correto.

Uma sequência básica de revisão é esta:

1. Verifique o caminho do executável, a versão do pacote, o checksum ou a revisão do código-fonte e todos os scripts de inicialização.
2. Inicie o processo com um ambiente enxuto, em uma conta de teste ou espaço de trabalho isolado.
3. Registre o primeiro resultado de tools/list e compare cada ferramenta com o trabalho pretendido.
4. Faça uma chamada de leitura inofensiva com dados falsos e observe arquivos, processos filhos e destinos de rede.
5. Adicione apenas as credenciais e o acesso a diretórios exigidos pelo comportamento confirmado.

Não confunda uma resposta bem-sucedida com um servidor seguro. Um servidor pode retornar a resposta esperada e, ao mesmo tempo, copiar arquivos ou usar um token herdado em outro lugar. O teste fornece evidências, não provas. Ele identifica projetos descuidados e surpresas óbvias antes que cheguem ao acesso de produção.

A conveniência dos pacotes cria um caminho de atualização que você precisa controlar

Gerenciadores de pacotes e inicializadores de runtimes tornam a configuração do MCP agradavelmente curta. Eles também criam um caminho de atualização. Um intervalo de versões, uma tag de pacote flutuante ou um simples nome de pacote pode alterar o servidor iniciado na próxima semana sem nenhuma diferença na configuração.

Fixe uma versão quando o ecossistema permitir e registre a origem do pacote junto com o inventário de ferramentas. Melhor ainda, use um artefato local revisado ou um arquivo de lock que sua equipe já acompanhe. O objetivo prático é simples: uma execução posterior deve resolver para um código que você consiga identificar.

Não permita que o agente instale seu próprio servidor MCP durante uma tarefa. Isso reúne aquisição de software, execução e autorização de ferramentas em uma única solicitação conversacional. Uma pessoa deve adicionar a configuração do servidor depois de revisar o código-fonte e o contrato de inicialização. Se um fluxo de desenvolvimento precisar de muitos servidores, mantenha um catálogo revisado em vez de aceitar trechos de configuração de comentários de issues ou da saída de ferramentas.

As atualizações merecem uma nova revisão breve. Compare o executável ou o arquivo de lock de dependências, o comando e os argumentos, os nomes explícitos de variáveis de ambiente e o inventário de tools/list. A adição de uma ferramenta pode ser inofensiva. Também pode introduzir acesso de escrita que a revisão anterior nunca considerou. O mesmo vale quando um servidor altera suas credenciais, seu endpoint ou sua biblioteca de autenticação.

A recomendação popular de «sempre usar o pacote mais recente para obter correções de segurança» é incompleta para servidores MCP. Você deve aplicar correções de segurança rapidamente, mas uma alteração automática não revisada pode mudar o código executado ao lado das suas credenciais. Use um processo de atualização controlado, que permita inspecionar a mudança e revertê-la se o novo servidor se comportar de forma diferente.

A aprovação deve acompanhar a ação, não o nome do servidor

Uma aprovação única para um processo de servidor responde a apenas uma pergunta: este executável pode participar desta sessão? Ela não pode responder com segurança a todas as perguntas posteriores sobre excluir uma branch remota, enviar dados de clientes ou abrir um comando SSH em um host de produção.

Separe a descoberta comum das ações relevantes. Listar projetos disponíveis, ler uma issue pública e buscar um esquema local costumam exigir menos atenção que alterar registros ou enviar dados para fora da máquina. Seu cliente ou limite de credenciais deve solicitar uma nova aprovação humana quando uma chamada ultrapassar essa fronteira. Se toda chamada de leitura exigir atenção, as pessoas clicarão sem ler. Se um único clique na inicialização conceder acesso ilimitado à produção, alguém acabará se arrependendo.

A identidade do processo também importa. Um aviso de aprovação deve informar qual processo assinado solicitou o acesso, não apenas mostrar um rótulo escolhido pelo servidor. Um rótulo como database-helper pode ser copiado por qualquer programa. O caminho do executável, a identidade da assinatura quando disponível e os argumentos de inicialização oferecem uma superfície de revisão melhor.

Mantenha registros em dois níveis: a sessão do agente que solicitou o trabalho e a ação individual que usou uma credencial ou alcançou um serviço externo. Você precisa do registro da sessão para investigar por que um agente tinha autoridade. Precisa do registro da ação para investigar o que realmente mudou. Um único registro não responde bem às duas perguntas se omitir o solicitante ou a solicitação exata.

Um registro resistente a adulterações ajuda quando o servidor, o cliente ou o operador discorda mais tarde sobre o que aconteceu. Ele não torna uma ação perigosa segura no momento da aprovação. Leia o destino, o método, o comando e os parâmetros relevantes antes de autorizar uma ação difícil de desfazer.

Um servidor rejeitado precisa de limpeza, não apenas de remoção

Se você decidir que um servidor não é confiável depois de conectá-lo, remova imediatamente sua entrada do cliente, mas não pare aí. O processo pode ter gravado arquivos, alterado a configuração do shell, criado tarefas agendadas, modificado um hook do repositório ou copiado credenciais enquanto estava em execução.

Preserve as evidências antes de apagar tudo. Salve a configuração, a versão do pacote ou a revisão do código-fonte, a saída do processo e os registros de ações. Depois, inspecione o HOME de teste, o diretório de trabalho do servidor, o cache de pacotes, os arquivos de inicialização do shell, os launch agents, os hooks de repositório e todos os diretórios que o servidor podia gravar. Verifique os processos ativos e as conexões de rede recentes enquanto as evidências ainda estiverem disponíveis.

Faça a rotação de todos os segredos que o processo poderia ter lido, não apenas do segredo que você forneceu intencionalmente. Isso inclui tokens herdados, acesso ao agente SSH, credenciais de pacotes e sessões de desenvolvimento baseadas no navegador, quando relevante. Remover uma linha de um arquivo de configuração não revoga um token copiado.

Depois, fortaleça o processo de revisão que permitiu a conexão. Se a falha veio de um ambiente herdado, use um inicializador enxuto. Se veio de uma atualização inesperada do pacote, fixe e revise os artefatos. Se veio de uma descrição enganosa de ferramenta, exija um inventário capturado antes da aprovação. O resultado útil é um controle alterado, não uma promessa vaga de ter mais cuidado na próxima vez.

Um novo servidor MCP recebe acesso em seu momento mais perigoso, antes de conquistar qualquer confiança. Torne seu comando literal, mantenha seu ambiente pequeno, inspecione sua lista de ferramentas e mantenha suas credenciais separadas do agente. É nesse ponto que você ainda controla o resultado.