~/studies/work 2026-11-20 · published 2026-11-21

Cómo se fijan las definiciones de herramientas

Un servidor de herramientas puede reescribir sus propias descripciones después de que lo aprobaste. Cinco mecanismos de un relevamiento de gateways, y qué hace connector-engine: un hash RFC 8785 por definición, cuarentena ante cambios y permisos obsoletos.

El problema

Un agente decide qué llamar a partir del nombre, la descripción y el esquema de entrada de la herramienta. Los tres vienen del servidor de herramientas. La especificación de MCP (página de tools 2026-07-28) dice que un servidor que responde a tools/list debe devolver el conjunto disponible en ese momento para el cliente que consulta, y que ese conjunto puede cambiar con el tiempo. No exige que un cliente compare el nuevo listado con el que tenía en caché.

Así, un servidor que aprobaste el lunes puede publicar otra descripción el martes, y nada en el protocolo te avisa. Este registro sale de un relevamiento que hice el 2026-11-20 para el estudio de controles de connector-engine. Las fuentes son documentación de proveedores y READMEs de proyectos leídos con una herramienta de fetch, lo que el registro marca como confianza media.

Cinco mecanismos en la práctica

FuenteQué hace
DigitalOcean Action GatewayLas versiones de las herramientas están numeradas. Una llamada puede fijar <tool>@<version>; las llamadas sin fijar toman las versiones nuevas apenas se publican.
LiteLLM MCPUn admin fija un servidor. La instantánea guarda nombre, descripción y esquema de entrada. La deriva dispara una alerta que nombra las herramientas agregadas, quitadas y cambiadas; volver a fijar la acepta; las llamadas a herramientas agregadas después del pin devuelven 403.
mcp-context-protector (Trail of Bits)Confianza en el primer uso de las instrucciones del servidor, las descripciones de herramientas y los esquemas de entrada; bloquea las llamadas siguientes hasta que el cambio se aprueba en la CLI.
MCP SEP-3452 (issue)Los clientes registrarían un digest SHA-256 de cada descripción y exigirían una nueva aprobación ante un cambio. Cerrado como completado el 2026-10-26 con una nota de que las propuestas necesitan primero participación del grupo de trabajo.
Cloudflare MCP portalsLos cambios upstream llegan por una sincronización periódica. El relevamiento no encontró ningún paso de revisión o diff documentado.

La documentación de LiteLLM, tal como la leí con la herramienta de fetch, no menciona hashing: el pin es una copia guardada que se compara al volver a listar. Es una diferencia de diseño, no un defecto. Una copia guardada da un diff legible; un hash da una comparación de igualdad barata y algo a lo que atar otros registros.

Qué hace connector-engine

Según su documentación, cada definición de función se hashea al capturarse, con JSON canónico RFC 8785. Una función nueva, o una descripción o esquema modificado, queda en cuarentena hasta que una persona la acepte. Un permiso hecho contra un hash anterior queda obsoleto y hay que confirmarlo de nuevo. Los re-listados corren programados entre dos límites configurados (pinning.relistMin y pinning.relistMax), de modo que se detecta un servidor que cambia sus herramientas después de la instalación.

Aceptar la definición actual mediante la API, con un token de admin del tenant.sh
vsh admin functions accept <connector id> <function name>

En la consola, una función en cuarentena indica que la definición cambió. Elegir on o ask la acepta. Las instrucciones del servidor también se pueden fijar (gateway.relayInstructions: pinned), se guardan con el conector y vuelven a cuarentena ante un cambio.

El hash hace un segundo trabajo: el hash de la llamada

El hash de la definición alimenta un hash de la llamada: el SHA-256 RFC 8785 de tenant, agente, conector, función, hash de la definición y argumentos. Una aprobación queda atada a él, así que una llamada aprobada no puede convertirse en silencio en una llamada a una herramienta modificada.

El estudio leyó este código en el commit 905a503 y encontró propiedades que conviene conocer de cualquier hash de JSON canónico. Los números se recodifican como doubles IEEE 754, así que 1 y 1.0 dan el mismo hash y los enteros por encima de 2^53 colapsan entre sí. Claves de objeto duplicadas: gana el último valor en silencio, un comportamiento de decodificación de Go que la nota dice no haber ejecutado. Los bytes hasheados no eran los bytes sellados y reenviados, así que dos payloads distintos podían compartir un hash de llamada.

Las notas de arquitectura actuales dicen que el gateway ahora parsea los argumentos una vez antes del escaneo de tokens, la validación del esquema y el hash de la llamada, y rechaza un objeto que repite una clave a cualquier profundidad, un valor de nivel superior que no es un objeto y datos después del valor de nivel superior. No volví a correr la sonda original contra ese cambio.

Límites del pinning

  • Un pin prueba que la definición no cambió, no que la primera versión fuera honesta. La confianza en el primer uso sigue siendo confianza.
  • Un hash dice cambió o no. No dice si el cambio importa. El diseño juzgado del estudio agregaba un diff de definiciones para eso, y esa parte no se construyó; el dueño pausó el trabajo el 2026-11-21 con solo el almacenamiento del registro de cambios de permisos mergeado.
  • Hipótesis: una comparación semántica, que el README de mcp-context-protector dice usar, podría reducir el ruido de ediciones inofensivas, pero una persona igual tiene que leer qué cambió.