¿Cómo mantener actualizados un servidor MCP y una CLI cuando cambia la API?

Cuando un sistema ofrece API, servidor MCP y CLI, un cambio en la API puede romper las otras dos interfaces sin que nadie se dé cuenta. Quien lo nota primero es el usuario.

Primero, los términos: la API es la puerta que ofrece tu sistema para que otros programas se comuniquen con él. El servidor MCP (el conector que usan los asistentes de IA) y la CLI (la versión de línea de comandos que se usa en la terminal) son dos formas de usar esa misma puerta.

Escribe en AGENTS.md (el archivo de instrucciones que los agentes de programación leen al abrir el proyecto) una regla sencilla: cuando cambie la API, revisa el servidor MCP y la CLI y aplica los cambios necesarios.

La API es la base de la que dependen esas interfaces. Cambiar la base y olvidar lo que se construyó encima se convierte en un problema de organización y mantenimiento.

Cada lanzamiento termina solo cuando las interfaces relacionadas también incorporan el cambio.

Por qué todo queda desalineado

Cada interfaz suele escribirse en un momento distinto y, a veces, por personas distintas. La API recibe un campo nuevo, cambia un nombre o empieza a exigir un parámetro. El servidor MCP y la CLI siguen con la versión anterior.

El resultado es un asistente de IA que llama a una función que ya no existe o un comando de terminal que devuelve un error sin explicación. No es falta de conocimientos técnicos, sino un paso que falta en el proceso.

Una sola fuente de verdad

Ayuda mucho describir la API en un archivo formal, como una especificación OpenAPI (un documento estándar que enumera cada ruta, campo y respuesta). Con él, es posible generar automáticamente parte del código del MCP y de la CLI o comprobar que esté actualizado.

Incluso sin generar código, ese archivo se convierte en la referencia que consulta el agente de programación para saber qué cambió.

Instrucciones claras para el agente

En AGENTS.md, la regla funciona mejor cuando es específica. En vez de pedir que mantenga todo actualizado, indica qué carpetas revisar, qué pruebas ejecutar y qué registrar en el historial de cambios.

Así, cuando le pidas al agente que cambie la API, sabrá que la tarea también incluye las otras interfaces y no se detendrá a mitad del camino.

Una prueba que impide lanzar

La protección más sólida es una prueba automática que llame a la API mediante MCP y CLI, y compruebe que la respuesta coincida. Si no coincide, no se lanza la versión.

Así, la regla deja de depender de la memoria y se convierte en una barrera del propio proceso.

1. Describe la API en un archivo de especificación, como OpenAPI, y guárdalo junto al código.
2. Escribe en AGENTS.md la lista de carpetas del MCP y de la CLI que deben revisarse con cada cambio.
3. Crea una prueba breve que llame a las funciones principales desde las tres interfaces.
4. Haz que esa prueba sea obligatoria antes de publicar una versión.
5. Registra en el historial de cambios qué cambió en la API y las interfaces.
6. Avísales a los usuarios cuando un cambio requiera actualizar el MCP o la CLI.

• Dejar la regla vaga en AGENTS.md: el agente la interpreta de la manera más breve y se salta partes.
• Probar solo la API: el problema suele aparecer en las capas superiores.
• Eliminar un campo sin avisar: quienes usan una versión anterior tienen problemas sin entender por qué.

• Incluye una regla en AGENTS.md.
• La API es la base; MCP y CLI se construyen encima.
• El lanzamiento solo se cierra cuando todo está actualizado.

• CursoMCP — Model Context Protocol desde ceroDel concepto a la creación de tu propio servidor MCP.
• Proyectoinema-agent-runtimeEscalera de opciones: API, MCP, CLI o pantalla, y cuándo usar cada una.
• Proyectofaxina-agentesUn AGENTS.md único y organizado, con las reglas que sigue el agente.

Algunos de estos materiales están en portugués.