~/studies/work 2026-11-20 · published 2026-11-21
Como as definições de ferramentas são fixadas
Um servidor de ferramentas pode reescrever as próprias descrições depois de você aprová-lo. Cinco mecanismos de um levantamento de gateways, e o que o connector-engine faz: um hash RFC 8785 por definição, quarentena em caso de mudança e permissões obsoletas.
- mcp
- pinning
- security
- gateway
- rfc-8785
- ~/project/versatile-sh
O problema
Um agente decide o que chamar a partir do nome, da descrição e do esquema de entrada da ferramenta. Os três vêm do servidor de ferramentas. A especificação do MCP (página de tools de 2026-07-28) diz que um servidor que responde a tools/list deve devolver o conjunto disponível no momento para o cliente que perguntou, e que esse conjunto pode mudar com o tempo. Ela não exige que o cliente compare a nova listagem com a que guardou em cache.
Assim, um servidor que você aprovou na segunda pode publicar outra descrição na terça, e nada no protocolo avisa. Este registro vem de um levantamento que fiz em 2026-11-20 para o estudo de controles do connector-engine. As fontes são documentação de fornecedores e READMEs de projetos lidos com uma ferramenta de fetch, o que o registro marca como confiança média.
Cinco mecanismos na prática
| Fonte | O que faz |
|---|---|
| DigitalOcean Action Gateway | As versões das ferramentas são numeradas. Uma chamada pode fixar <tool>@<version>; chamadas sem fixar pegam as versões novas assim que são lançadas. |
| LiteLLM MCP | Um admin fixa um servidor. O snapshot guarda nome, descrição e esquema de entrada. A deriva gera um alerta que nomeia as ferramentas adicionadas, removidas e alteradas; fixar de novo aceita; chamadas a ferramentas adicionadas depois do pin retornam 403. |
| mcp-context-protector (Trail of Bits) | Confiança no primeiro uso das instruções do servidor, das descrições das ferramentas e dos esquemas de entrada; bloqueia as chamadas seguintes até a mudança ser aprovada na CLI. |
| MCP SEP-3452 (issue) | Os clientes registrariam um digest SHA-256 de cada descrição e exigiriam nova aprovação em caso de mudança. Fechada como concluída em 2026-10-26 com a observação de que propostas precisam antes de engajamento do grupo de trabalho. |
| Cloudflare MCP portals | As mudanças upstream chegam por uma sincronização periódica. O levantamento não encontrou nenhuma etapa de revisão ou diff documentada. |
A documentação do LiteLLM, como li pela ferramenta de fetch, não menciona hashing: o pin é uma cópia guardada comparada ao listar de novo. É uma diferença de design, não um defeito. Uma cópia guardada dá um diff legível; um hash dá uma checagem de igualdade barata e algo a que amarrar outros registros.
O que o connector-engine faz
Segundo a documentação, cada definição de função é hasheada quando capturada, usando JSON canônico RFC 8785. Uma função nova, ou uma descrição ou esquema alterado, fica em quarentena até uma pessoa aceitar. Uma permissão feita contra um hash mais antigo fica obsoleta e precisa ser confirmada de novo. Os re-listados rodam agendados entre dois limites configurados (pinning.relistMin e pinning.relistMax), então um servidor que muda suas ferramentas depois da instalação é detectado.
vsh admin functions accept <connector id> <function name>No console, uma função em quarentena avisa que a definição mudou. Escolher on ou ask aceita. As instruções do servidor também podem ser fixadas (gateway.relayInstructions: pinned), guardadas junto do conector e colocadas em quarentena de novo em caso de mudança.
O hash faz um segundo trabalho: o hash da chamada
O hash da definição alimenta um hash da chamada: o SHA-256 RFC 8785 de tenant, agente, conector, função, hash da definição e argumentos. Uma aprovação fica atada a ele, então uma chamada aprovada não pode virar, sem aviso, uma chamada a uma ferramenta alterada.
O estudo leu este código no commit 905a503 e encontrou propriedades que vale conhecer de qualquer hash de JSON canônico. Números são recodificados como doubles IEEE 754, então 1 e 1.0 geram o mesmo hash e inteiros acima de 2^53 colapsam entre si. Chaves de objeto duplicadas: o último valor vence em silêncio, um comportamento de decodificação do Go que a nota diz não ter executado. Os bytes hasheados não eram os bytes selados e encaminhados, então dois payloads diferentes podiam compartilhar um hash de chamada.
As notas de arquitetura atuais dizem que o gateway agora faz o parse dos argumentos uma vez antes da varredura de tokens, da checagem do esquema e do hash da chamada, e recusa um objeto que repete uma chave em qualquer profundidade, um valor de nível superior que não seja objeto e dados depois do valor de nível superior. Não rodei de novo a sonda original contra essa mudança.
Limites do pinning
- Um pin prova que a definição não mudou, não que a primeira versão era honesta. Confiança no primeiro uso continua sendo confiança.
- Um hash diz mudou ou não. Não diz se a mudança importa. O design julgado do estudo adicionava um diff de definição para isso, e essa parte não foi construída; o trabalho foi pausado pelo dono em 2026-11-21 com apenas o armazenamento do log de mudanças de permissão mergeado.
- Hipótese: uma comparação semântica, que o README do mcp-context-protector diz usar, poderia reduzir o ruído de edições inofensivas, mas uma pessoa ainda precisa ler o que mudou.