Cambiar tu servidor MCP sin romper a los usuarios

La primera publicación es la parte fácil. Construyes herramientas, sacas el servidor, la gente lo engancha. La cosa se pone interesante en la versión dos. Una herramienta tiene un nombre poco afortunado, falta un parámetro, una respuesta debería estar mejor estructurada. Y a partir de ahora de cada cambio cuelga alguien a quien no conoces y a quien no puedes preguntar.

La diferencia con una biblioteca normal: tus usuarios no son solo personas que programan, también son modelos de lenguaje. Cuando un modelo venía llamando bien a una herramienta y después de tu actualización falla el tiro, no hay error de compilación. Hay una respuesta que simplemente es peor. Eso es lo que hace que los cambios rotos de MCP sean tan difíciles de notar.

Esta guía te enseña cómo hacer visible tu superficie, comprobar los cambios de forma automática y cambiar de versión con limpieza.

Paso 1: Aclara qué es tu contrato desde el punto de vista de quien lo usa

Tu contrato no es tu código. Es exactamente lo que ve un cliente ajeno al conectarse: la lista de tus herramientas con nombre, descripción y esquema de entrada, más los datos de tu servidor. Todo lo que hay por debajo lo puedes rehacer a tu gusto.

Tómate cinco minutos y escribe esa superficie una vez como lista. Por herramienta: cómo se llama, qué campos son obligatorios, cuáles opcionales, qué devuelve y qué significa en términos del negocio. Esa lista es tu punto de referencia a partir de ahora.

La última columna, el significado de negocio, es la que todo el mundo olvida. No está en ningún esquema y aun así es la que rompe con más fuerza.

Paso 2: Convierte la descripción en parte de la API

En una biblioteca clásica un comentario es cosmética. En MCP la descripción de una herramienta es funcional, porque a partir de ella el modelo decide si llama siquiera a esa herramienta.

Reformula una descripción y habrás cambiado el comportamiento de enrutado, aunque no hayas tocado ningún esquema. Una herramienta que antes se elegía de forma fiable de repente se salta, o hay otra que se lleva las llamadas.

Trata por eso las descripciones como código. Van a la revisión, no a un commit rápido de limpieza de paso.

Paso 3: Congela la superficie como fichero

Tu servidor puede imprimir su propia lista de herramientas. Justo eso lo escribes en un fichero y lo dejas junto a tu código en el repo, por ejemplo como mcp-surface.json.

A partir de ahora tu contrato ya no es una idea en tu cabeza, sino un fichero versionado. Cada cambio en tus herramientas produce un cambio en ese fichero, y lo ves en el diff antes de que lo note nadie más.

Este es el paso que pasa todo el asunto de la disciplina a la mecánica. Sin él, todos los pasos siguientes se quedan en buenos propósitos.

Paso 4: Deja que el diff detenga tu build

Monta un paso de comprobación que al pasar los tests genere la lista actual de herramientas y la compare con el fichero que está en el repo. Si difieren, la ejecución se corta.

Lo importante es el mensaje de error. No debería decir "el fichero es distinto", sino qué ha cambiado y si eso es inofensivo o delicado para quien lo usa. O sea: herramienta nueva añadida, campo que pasa de opcional a obligatorio, herramienta desaparecida.

El corte no es una prohibición. Puedes actualizar el fichero cuando quieras. Solo se trata de que no pases de largo sin darte cuenta.

Paso 5: Apréndete los cuatro cambios que siempre rompen

Primero, renombrar una herramienta. Cada llamada existente apunta al vacío.

Segundo, introducir un campo obligatorio nuevo. Todas las llamadas que no lo manden se caen en la comprobación del esquema.

Tercero, convertir en obligatorio un campo hasta ahora opcional. El mismo efecto, solo que menos evidente.

Cuarto, cambiar el significado manteniendo el nombre. Un campo limit ayer significaba filas y hoy páginas. Esquema idéntico, resultados equivocados, y nadie recibe un error. Ese es el caso que te persigue durante más tiempo.

Paso 6: Y los que son seguros

Añadir una herramienta nueva no tiene riesgo, mientras no desplace a las existentes.

Un campo opcional nuevo con un valor por defecto razonable no tiene riesgo, porque las llamadas antiguas siguen funcionando igual.

Ampliar un resultado con un campo adicional casi nunca tiene riesgo, mientras los campos de antes conserven el mismo significado.

Todo lo que consista en quitar o reinterpretar pertenece al paso 5. Todo lo que consista en añadir está en casa aquí. Esa línea divisoria es más fácil de recordar que cualquier lista de reglas.

Paso 7: Construye al lado en vez de retorcer

Quieres renombrar search_docs como find_documents y ordenar los parámetros. El camino caro es hacerlo de una tacada.

El camino tranquilo: creas la herramienta nueva además de la vieja. Las dos funcionan en paralelo, por dentro llaman al mismo código. La antigua sigue operativa, la nueva es el camino recomendado.

Con eso desplazas el dolor desde tu día de publicación hasta un momento que eliges tú. Y conservas la posibilidad de apagar la herramienta antigua solo cuando veas que ya no la usa nadie.

Paso 8: Anuncia el apagado donde se va a leer

Un aviso en el changelog llega a la gente que lee changelogs. Son pocos, y los modelos de lenguaje no están entre ellos.

El sitio que de verdad llega es la descripción de la herramienta antigua. Basta una frase: que esta herramienta ha sido sustituida, cómo se llama la sucesora y a partir de cuándo desaparece. Los modelos leen esa descripción en cada conexión, quien programa la ve al depurar.

Pon una fecha concreta en vez de "próximamente". Sin fecha no pasa nada, y acabas arrastrando la herramienta antigua dos años.

Paso 9: Cuida el número de versión que ya estás enviando

Al establecer la conexión, tu servidor informa de sus datos, y entre ellos va una versión. Mucha gente la pone una vez en 1.0.0 y no la vuelve a tocar.

Úsala como señal. Sube la tercera cifra en correcciones internas, la segunda en las ampliaciones del paso 6, la primera en todo lo del paso 5. Así quien engancha tu servidor puede ver, sin preguntar, lo arriesgada que es para él una actualización.

No te cuesta nada y es el único aviso legible por máquina que tienes.

Paso 10: Si algo cambia en tiempo de ejecución, avisa

Hay servidores cuya lista de herramientas cambia durante el funcionamiento, por ejemplo porque alguien activa un módulo. Para ese caso el protocolo prevé una notificación con la que el servidor le comunica al cliente que la lista ha cambiado.

Si tu lista es dinámica, mándala. Si no, el cliente sigue trabajando con un estado que ya no existe y llama a herramientas que han desaparecido.

Si tu lista queda fija al arrancar, no necesitas esto. Entonces tu proceso de publicación es el sitio donde llega el cambio, y para eso tienes los pasos 3 a 8.

Qué sigue

Si estás en este punto, tienes un servidor en marcha con usuarios reales. La siguiente ampliación con sentido es el control de acceso, porque desde el momento en que gente ajena engancha tu herramienta, quieres saber quién. Eso está en Auth de MCP.

Y si vienes justo del otro lado, es decir, si eres tú quien engancha servidores ajenos y quieres saber en qué fijarte: el playbook Revisar servidores MCP ajenos con seguridad es la dirección contraria de este.

Fuentes

Los datos sobre definición de herramientas, esquema de entrada y la notificación por lista de herramientas modificada vienen de la especificación de MCP, sección Tools: https://modelcontextprotocol.io/specification/2025-06-18/server/tools

Los datos del servidor al establecer la conexión, incluido el campo de versión, están en la sección Lifecycle: https://modelcontextprotocol.io/specification/2025-06-18/basic/lifecycle