Cómo seguir los cambios incompatibles en servidores MCP

Un servidor MCP es una API cuyo principal consumidor es un modelo de lenguaje. Eso hace que los cambios incompatibles sean más extraños de lo habitual: un cliente nunca lanza un error de tipos, simplemente el modelo empieza a llamar a una herramienta ligeramente mal.

Por qué es fácil pasar por alto la deriva de esquemas

El autor de un servidor cambia el nombre de un parámetro de query a search_text, o hace obligatorio un campo opcional. Nada falla en el despliegue. La lista de herramientas se obtiene en tiempo de ejecución, así que cada cliente recoge el nuevo esquema en su siguiente conexión. Los agentes que funcionaban ayer ahora pasan los nombres de argumentos antiguos y reciben errores de validación o, peor, entradas ignoradas en silencio.

Vimos repetidamente tres tipos de cambio que causaban problemas:

• Una herramienta se renombró o se eliminó.
• Un parámetro cambió de tipo o pasó a ser obligatorio.
• Una descripción cambió lo bastante como para alterar cuándo un modelo elige la herramienta.

Qué compara Proxar

Proxar toma una instantánea de la respuesta de tools/list de cada servidor frente al que se sitúa y la almacena con un hash de contenido. Cuando el hash cambia, compara las dos instantáneas herramienta por herramienta.

{
  "name": "search_issues",
  "inputSchema": {
    "type": "object",
    "properties": {
      "query": { "type": "string" },
      "limit": { "type": "integer" }
    },
    "required": ["query"]
  }
}

La comparación recorre el JSON Schema de cada herramienta, no el texto en bruto, así que reordenar claves o reformatear nunca cuenta como un cambio.

Decidir qué es incompatible

Usamos un conjunto de reglas deliberadamente conservador, en el mismo espíritu que el versionado semántico de las bibliotecas.

Incompatible

Eliminar una herramienta, eliminar un parámetro, añadir un parámetro obligatorio, restringir un tipo (por ejemplo, de string a un enum) o endurecer una restricción como maxLength.

Compatible

Añadir una herramienta, añadir un parámetro opcional, ampliar un tipo o relajar una restricción.

Requiere a una persona

Los cambios de descripción. No podemos saber si una descripción reformulada cambia el comportamiento del modelo, así que Proxar la marca como aviso en lugar de como ruptura y muestra el texto antiguo y el nuevo lado a lado.

Qué hace con el resultado

Una diferencia incompatible no bloquea el tráfico por defecto. Genera una alerta con la ruta exacta que cambió, por ejemplo search_issues.inputSchema.required, y puede optar por fijar la instantánea anterior mientras actualiza sus agentes.

# compare the pinned snapshot with what the server reports now
proxar diff --server issues-mcp --against pinned

Lo que aún hacemos mal

Los cambios semánticos tras un esquema sin cambios nos resultan invisibles. Si una herramienta empieza a devolver resultados ordenados de otra forma, el esquema es idéntico y la diferencia está vacía. Preferimos decirlo antes que fingir que una comprobación de esquema lo cubre. El muestreo de respuestas está en la lista, y lo contaremos cuando funcione.