Revisão de ferramenta MCP personalizada: um checklist prático de segurança

Ferramentas MCP personalizadas merecem a mesma revisão que você faria em uma pequena integração de produção com acesso à sua estação de trabalho, à rede e às credenciais. O fato de um agente chamar a ferramenta pelo MCP não reduz sua autoridade. Muitas vezes, isso apenas facilita o uso repetido de uma autoridade mal definida.

Já vi a mesma falha várias vezes: um desenvolvedor lê a descrição de uma ferramenta, vê um nome útil como deploy_preview ou search_docs e concede acesso porque ela parece local. Mais tarde, a implementação transforma uma string fornecida pelo modelo em uma URL, um argumento de shell ou uma leitura recursiva de arquivos. A ferramenta útil nunca foi o limite de segurança. O limite estava na implementação e no caminho da credencial.

A especificação do Model Context Protocol descreve ferramentas como funções expostas por um servidor para que um cliente as descubra e chame. Ela também deixa explícito um fato desconfortável: a execução das ferramentas é controlada pelo modelo. Um cliente pode colocar uma pessoa no fluxo de aprovação, mas o autor da ferramenta ainda precisa presumir que os argumentos podem ser inesperados, excessivos ou direcionados ao alvo errado. Revise a ferramenta antes de dar ao agente a chance de ser criativo.

Comece pelo mapa de autoridade, não pelo README

Uma ferramenta MCP personalizada só é aceitável quando você consegue desenhar um caminho curto e concreto entre a solicitação do agente e o efeito produzido. Comece registrando o que a ferramenta pode ler, para onde pode enviar dados, o que pode alterar e qual credencial ou identidade do sistema operacional torna isso possível.

Faça isso antes de ler os detalhes da implementação. Assim, você terá um padrão para avaliar o código, em vez de deixar que uma descrição agradável defina o padrão. Uma ferramenta chamada get_build_status pode ler um arquivo de configuração local, chamar uma API hospedada, gravar um cache e executar um helper de linha de comando. Cada ação tem um modo de falha diferente.

Use um pequeno mapa de autoridade como este:

Não escreva «a internet» na linha de rede nem «credenciais do desenvolvedor» na linha de credenciais. Esses rótulos mostram que a revisão ainda não começou. Informe o host, a família de rotas da API, a conta ou o token e a pessoa ou o sistema que pode revogá-lo.

Esse exercício também separa duas coisas que as equipes costumam misturar: a finalidade anunciada da ferramenta e sua autoridade real. create_issue parece restrita. Uma função que aceita uma URL base arbitrária, cabeçalhos arbitrários e um corpo de solicitação arbitrário tem a autoridade de um cliente HTTP genérico. Revise essa realidade, não o rótulo.

O esquema de entrada deve reduzir escolhas

Um esquema de entrada MCP deve restringir o agente à operação que você pretende permitir. Ele não deve ser uma definição de tipos decorativa em torno de um canal de comandos livre.

A especificação do MCP usa JSON Schema para os esquemas de entrada das ferramentas. Isso ajuda os clientes a apresentar argumentos e ajuda as implementações a validá-los, mas JSON Schema não é uma proteção se o servidor não rejeitar valores inválidos antes de executar qualquer trabalho. Trate o esquema como a primeira barreira e a validação no servidor como a segunda.

Este é um esquema que pode ser revisado para uma ferramenta que busca o status de um build conhecido:

{
  "name": "get_build_status",
  "description": "Return the status for one build in the approved CI project.",
  "inputSchema": {
    "type": "object",
    "additionalProperties": false,
    "required": ["build_id"],
    "properties": {
      "build_id": {
        "type": "string",
        "pattern": "^[A-Z]{2,8}-[0-9]{1,10}$",
        "maxLength": 20
      },
      "include_logs": {
        "type": "boolean",
        "default": false
      }
    }
  }
}

Ele faz várias escolhas pelo agente. O agente não pode selecionar um host, anexar cabeçalhos nem passar um comando de shell. Também não pode enviar campos não declarados, porque additionalProperties é falso. O identificador do build tem um formato limitado, o que torna seu uso posterior menos perigoso e facilita o registro.

Agora compare com o formato que causa problemas:

{
  "name": "request",
  "inputSchema": {
    "type": "object",
    "properties": {
      "url": {"type": "string"},
      "method": {"type": "string"},
      "headers": {"type": "object"},
      "body": {}
    }
  }
}

Isso é um cliente HTTP com um nome simpático. Se tiver um token bearer, poderá enviar esse token ou dados de um prompt controlado pelo agente para um endpoint arbitrário. As pessoas mantêm esse desenho porque ele economiza tempo durante a prototipagem. Ainda assim, é um limite ruim para produção, mesmo que o nome da ferramenta pareça específico.

Teste o tratamento das entradas com valores que alterem a interpretação, e não apenas com valores que pareçam malformados. Experimente um campo de identificador duplicado, um campo inesperado, uma string grande, caracteres Unicode parecidos, uma quebra de linha e um valor sintaticamente válido, mas que aponte para fora do domínio de negócio pretendido. Se uma entrada virar um caminho, exija um identificador relativo e resolva-o contra um diretório fixo. Se virar um filtro de API, use parâmetros estruturados em vez de concatenar strings de consulta.

Nunca passe um argumento para um shell só porque validou o esquema. Use um array de argumentos com um caminho fixo para o executável. Isto é mais seguro:

subprocess.run(
    ["/usr/local/bin/buildctl", "status", "--id", build_id],
    check=True,
    text=True,
    capture_output=True,
    env={"PATH": "/usr/bin:/bin"}
)

Isto indica uma falha na revisão:

subprocess.run(f"buildctl status --id {build_id}", shell=True)

A primeira forma ainda precisa de validação, tratamento de erros e um executável confiável. Ela não pede que um shell reinterprete pontuação controlada pelo modelo.

Toda solicitação externa precisa de um destino fixo

Uma ferramenta MCP personalizada deve trabalhar com um conjunto pequeno de destinos, e seu código deve rejeitar qualquer outro antes de abrir uma conexão. Colocar um hostname em uma lista de permissões na documentação não serve para nada se o código da solicitação aceita uma URL arbitrária.

Revise o tráfego externo em dois níveis. Primeiro, procure no código bibliotecas HTTP, clientes WebSocket, consultas DNS, instaladores de pacotes, SDKs de telemetria, bibliotecas de webhook e qualquer processo auxiliar que possa se conectar a outro lugar. Depois, observe uma execução real. A inspeção estática encontra os caminhos pretendidos. A observação em tempo de execução detecta uma dependência que faz chamadas externas ou um valor de configuração que mudou o destino.

Um cliente seguro monta a URL a partir de partes fixas e codifica apenas o identificador:

from urllib.parse import quote

BASE = "https://ci.example.internal/api/builds/"
url = BASE + quote(build_id, safe="")
response = client.get(url, timeout=10, follow_redirects=False)

O controle importante não é quote. É a origem fixa. Se o cliente seguir redirecionamentos, uma origem confiável poderá redirecionar para um host não confiável. Desative redirecionamentos, a menos que a ferramenta verifique cada destino contra a mesma lista de permissões.

Isso também importa para serviços internos. Uma ferramenta que aceita http://host/path pode ser enganada para acessar serviços administrativos locais ou endpoints de metadados que o agente não consegue acessar diretamente. Bloquear hosts públicos não resolve o problema. Você precisa de uma lista positiva de origens aprovadas e de uma regra que recuse endereços IP literais ou destinos privados, a menos que a ferramenta precise explicitamente deles.

Capture o tráfego em um ambiente de teste descartável. No macOS, lsof oferece uma primeira visão rápida dos sockets de rede atuais:

lsof -nP -iTCP -sTCP:ESTABLISHED -c python

O formato da saída identifica um processo, seu usuário, o descritor de arquivo e o endpoint remoto:

COMMAND   PID  USER   FD   TYPE             DEVICE SIZE/OFF NODE NAME
python   8421  alex   12u  IPv4 0x...             0t0  TCP 10.0.0.8:51244->203.0.113.20:443 (ESTABLISHED)

Substitua python pelo nome real do processo e repita enquanto invoca uma operação da ferramenta. Esse comando não é uma auditoria completa do tráfego. Conexões curtas podem desaparecer antes da inspeção. Ainda assim, ele é bom para revelar uma conexão inesperada de longa duração ou um helper cuja existência você desconhecia.

Revise os payloads das solicitações com o mesmo cuidado. Uma ferramenta pode chamar corretamente uma API aprovada e, ao mesmo tempo, despejar um diff inteiro do repositório, uma variável de ambiente ou a transcrição do agente em um parâmetro de consulta. Restrinja os campos enviados no código. Monte o payload com os valores nomeados de que a operação precisa, em vez de serializar um objeto inteiro recebido do agente.

A identidade do processo faz parte da permissão

Você não pode aprovar uma ferramenta com responsabilidade se não consegue dizer qual executável solicitou a ação. O nome do processo, sozinho, é uma evidência fraca, porque qualquer processo pode escolher um nome familiar.

Registre o comando completo de inicialização, o caminho do executável, a versão, o diretório de trabalho, o processo pai e a conta de usuário. Quando a assinatura de código do macOS se aplicar, verifique também a autoridade da assinatura. codesign pode mostrar as declarações de identidade vistas pelo macOS:

codesign -dv --verbose=4 /absolute/path/to/mcp-server 2>&1 | grep -E 'Identifier|TeamIdentifier|Authority'

A saída normalmente contém campos como:

Identifier=com.example.mcpserver
Authority=Developer ID Application: Example Developer
TeamIdentifier=ABCDE12345

Esses campos são evidências, não uma decisão de permissão por si só. Um binário assinado ainda pode ser o binário errado para esse trabalho, e um script interno não assinado não é automaticamente malicioso. A revisão pergunta se o caminho, o proprietário, o código-fonte e a identidade correspondem à ferramenta que você esperava executar.

Depois, inspecione a árvore de processos durante uma invocação:

ps -axo pid,ppid,user,command | grep -E 'mcp-server|sp-ssh|node|python'

Você quer uma resposta sem surpresas: o cliente do agente inicia o servidor MCP, e o servidor inicia apenas os processos auxiliares esperados. Desconfie quando o servidor iniciar um shell, um gerenciador de pacotes, um interpretador de um diretório de projeto mutável ou um processo em segundo plano que continue depois da sessão.

Uma falha comum parece inofensiva em um arquivo de configuração:

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

Isso pode baixar ou alterar código no momento da inicialização, dependendo do cache local e da resolução do pacote. Assim, uma revisão do código de ontem se torna menos significativa do que as equipes imaginam. Fixe o executável ou a versão do pacote, instale-o por um processo controlado e inicie um caminho local conhecido. Se a ferramenta precisar de atualizações, transforme as atualizações em um evento explícito de revisão, em vez de um efeito invisível da inicialização de um agente.

A identidade do processo também inclui o ambiente herdado. Um servidor iniciado a partir do shell de um desenvolvedor pode herdar tokens de nuvem, tokens de controle de código-fonte, configurações de proxy e um PATH amplo. Imprima um inventário sanitizado nos testes ou inicie o processo com um ambiente mínimo. Não registre valores secretos. Registre os nomes das variáveis que afetam o comportamento e confirme que a ferramenta não precisa de credenciais ambiente que nunca deveria usar.

Os logs devem reconstruir as ações sem repetir segredos

Um registro de auditoria útil responde quem executou a ferramenta, sob qual processo, com quais argumentos sanitizados, contra qual destino e com qual resultado. Uma linha que diz tool call succeeded não responde a nenhuma das perguntas que surgirão quando um agente enviar dados para um lugar inesperado.

Separe os logs operacionais das saídas de depuração que contêm segredos. Os operadores precisam de detalhes suficientes para investigar. Não precisam de tokens bearer, cabeçalhos de autorização, chaves privadas, transcrições brutas do agente ou corpos completos de respostas copiados para um arquivo de texto.

Para cada invocação, registre campos semelhantes a estes:

{
  "time": "2025-03-08T14:22:11Z",
  "session_id": "run_7c2f",
  "process": "/opt/tools/build-mcp",
  "tool": "get_build_status",
  "argument_summary": {"build_id": "CI-4812", "include_logs": false},
  "destination": "ci.example.internal",
  "decision": "approved",
  "result": "success",
  "request_id": "c4e8..."
}

O exemplo usa intencionalmente um resumo dos argumentos. Um resumo deve preservar identificadores e campos limitados que ajudem na investigação, enquanto oculta ou transforma em hash os valores sensíveis. Se uma operação realmente enviar um documento, registre a quantidade de bytes e um digest do conteúdo quando isso ajudar na correlação. Não coloque o documento no diário apenas para facilitar a depuração.

O modelo de logging do OpenTelemetry é útil aqui, mesmo que você não adote o OpenTelemetry. Ele distingue o corpo do evento dos atributos e enfatiza campos estruturados para filtragem e correlação. Aplique essa ideia localmente: torne o destino, a operação, o resultado e a identidade do processo legíveis por máquinas. Um amontoado de linhas em prosa se torna inútil na primeira vez que você precisar descobrir se o agente enviou a mesma solicitação dez vezes.

Inspecione também os caminhos de erro. Muitas ferramentas ocultam as solicitações bem-sucedidas, mas imprimem um objeto completo quando uma API retorna um erro. Force um 401, um timeout, um JSON malformado e uma falha de DNS. Leia cada linha emitida. É na saída de depuração que as credenciais costumam escapar.

O Sallyport mantém um Sessions journal para as execuções dos agentes e um Activity journal para chamadas individuais, ambos projetados a partir de um log de auditoria criptografado, encadeado por hashes e sem possibilidade de escrita. Esse desenho é útil quando você precisa de um registro local além dos próprios logs do autor da ferramenta, mas não torna segura uma ferramenta ampla. A ferramenta ainda precisa de entradas restritas e destinos conhecidos.

Prompts de aprovação não consertam uma autoridade ampla

A aprovação humana só funciona como um freio útil quando o objeto aprovado tem um escopo compreensível. Um cartão que diz que um processo desconhecido quer usar uma credencial informa algo importante. Ele não diz se uma ferramenta de solicitações genérica enviará um arquivo do repositório para um host escolhido por um modelo cinco segundos depois.

Mantenha a unidade de aprovação próxima da unidade de autoridade. Um token somente leitura para consultar status e um token de implantação em produção não devem ficar atrás da mesma aprovação, porque suas consequências são diferentes. Uma ferramenta que lê um registro de release não deve ganhar silenciosamente a capacidade de criar um, apenas porque as duas operações usam a mesma API.

A especificação do Model Context Protocol recomenda que os clientes obtenham o consentimento do usuário antes de invocar ferramentas. É uma orientação correta, mas o consentimento tem um ponto fraco: as pessoas aprovam prompts repetitivos e mal descritos até que o prompt deixe de transmitir informação. Não resolva a fadiga de prompts aprovando para sempre uma categoria inteira de ações. Corrija o limite da ferramenta que produz prompts vagos ou excessivos.

A escada de decisões do Sallyport coloca um cofre bloqueado antes de todas as ações, solicita autorização por sessão por padrão e pode exigir uma decisão para cada uso de uma credencial específica. Use aprovação por chamada para credenciais cujo uso você gostaria de inspecionar todas as vezes, como uma credencial de implantação ou uma API com permissão de escrita. Não use isso como desculpa para dar essa credencial a uma ferramenta HTTP genérica.

Um bom teste de aprovação pode ser resumido em uma frase: «Este processo assinado, iniciado a partir deste caminho, pode usar esta credencial para consultar o status deste serviço durante esta execução». Se você não consegue dizer isso honestamente, negue a solicitação e volte ao mapa de autoridade.

Teste os caminhos de falha antes de confiar no sucesso

Uma ferramenta que funciona no caminho esperado ainda não passou por uma revisão de segurança. Você precisa ver como ela se comporta quando as entradas estão erradas, a credencial está ausente, a rede aponta para um lugar inesperado e o processo auxiliar falha.

Execute a ferramenta em uma conta de teste ou projeto isolado, com uma credencial de escopo mínimo viável. Use dados de teste suficientemente parecidos com os reais para exercitar serialização e limites de tamanho, mas nunca coloque segredos de produção em uma ferramenta não revisada apenas para ver o que acontece.

Use esta sequência de cinco partes:

1. Chame a ferramenta com uma solicitação válida e capture sua árvore de processos, o destino externo e o registro de auditoria.
2. Envie um campo não declarado, um valor no tamanho máximo, um valor com quebras de linha e um identificador aparentemente válido, mas fora do projeto permitido. O servidor deve rejeitar cada um antes de fazer uma solicitação.
3. Force um host não aprovado por todas as rotas disponíveis de entrada e configuração. Inclua redirecionamentos se a ferramenta usar HTTP. A ferramenta deve recusá-lo e registrar a recusa sem expor a entrada sensível.
4. Remova ou revogue a credencial enquanto o servidor continua em execução e repita a solicitação válida. Confirme que a próxima ação falha, em vez de ter sucesso por causa de um cache oculto ou de um ambiente herdado.
5. Encerre o processo pai do agente e verifique se existem processos servidores ou helpers sobreviventes. Um worker em segundo plano que mantém acesso depois da saída do agente precisa de uma justificativa clara e de uma revisão separada.

Mantenha as evidências junto da versão da ferramenta: manifesto, revisão do código-fonte ou digest do pacote, comandos usados, endpoints observados, exemplo de registro de auditoria redigido e a pessoa que aceitou os riscos restantes. Isso não é burocracia por si só. Sem evidências versionadas, uma atualização posterior do pacote muda a ferramenta e todos presumem que a revisão antiga ainda vale.

Uma falha merece atenção especial. Imagine que uma ferramenta de busca de documentos aceite repository_path e chame um helper usando uma string de shell. As solicitações normais funcionam. Mais tarde, o agente recebe uma instrução incorporada em um ticket para buscar um caminho que contém pontuação de shell. O helper executa um segundo comando sob a conta do desenvolvedor, lê um arquivo de credenciais e a ferramenta envia o resultado para seu endpoint de busca, que era aprovado. Cada componente fez o que seu autor esperava. A composição falhou porque o esquema permitia um caminho, o shell o reinterpretou e o payload externo aceitava qualquer saída do helper. Teste as cadeias, não apenas as funções isoladas.

Remover o acesso exige mais que apagar uma entrada de configuração

Remover um servidor MCP da configuração do agente interrompe o caminho normal de inicialização. Isso não revoga um token copiado para um cache, encerra um servidor que ainda está em execução, remove uma chave SSH de um processo agente nem invalida o acesso no serviço remoto.

Planeje a remoção quando conceder o acesso. O responsável pela credencial deve saber onde revogá-la, a ferramenta deve usar uma credencial distinta quando possível e o operador deve saber quais processos e arquivos locais remover. Tokens compartilhados de desenvolvedores transformam uma remoção simples em um incidente, porque não é possível saber qual uso pertence à ferramenta.

Para uma ferramenta que usa HTTP, revogue ou desative primeiro o token remoto. Depois pare o servidor MCP e todos os helpers filhos, remova a referência local à credencial e apague a configuração de inicialização. Por fim, repita a mesma solicitação e preserve o resultado negado. No caso de SSH, remova a chave pública relevante da conta ou do repositório remoto, encerre os processos auxiliares locais e verifique se a configuração do agente contém identidades alternativas.

Não confunda o bloqueio de um cofre local com a revogação remota. O bloqueio impede usos futuros por meio desse cofre enquanto ele permanecer bloqueado. Ele não pode recolher dados já enviados, invalidar um token armazenado em outro lugar nem interromper um processo independente que tenha herdado uma credencial anteriormente.

Torne a remoção testável antes de um incidente. Adicione uma entrada curta ao runbook com o local da revogação remota, a resposta de negação esperada, o comando do servidor, o local da configuração e os campos do log que confirmam que a tentativa falhou. Se o responsável pela ferramenta não puder fornecer essa entrada, a integração não está concluída.

Uma ferramenta restrita conquista confiança repetível

As ferramentas que passam pela revisão costumam ser entediantes da melhor forma. Elas aceitam poucos campos tipados, conectam-se a um serviço conhecido, executam um programa conhecido quando necessário, retornam apenas o resultado de que o agente precisa e deixam um registro que alguém pode consultar depois.

Ferramentas amplas parecem flexíveis porque transferem as decisões de desenho para o agente em tempo de execução. Também transformam uma única aprovação em autoridade sobre destinos, dados e comandos que ninguém revisou. Mantenha a flexibilidade no código que você controla e exponha ao agente uma operação restrita.

Antes de aprovar uma ferramenta personalizada, tente remover uma entrada, um destino, um escopo de credencial ou um processo filho. Se ninguém conseguir explicar por que esse item precisa permanecer, remova-o. A revisão fica mais fácil, assim como a resposta a um eventual incidente.