Migración de un servidor MCP por HTTP a 2026-07-28 con soporte para clientes anteriores

Objetivo

Estado al 25 de octubre de 2026. Migrar un servidor MCP por HTTP a la revisión 2026-07-28 y conservar una vía con soporte explícito para clientes 2025-11-25. Volver a comprobar la especificación del transporte para esa versión, los esquemas de mensajes y el soporte documentado del SDK elegido antes del despliegue. Este es un procedimiento de aceptación propuesto, no un informe de una migración probada.

Requisitos previos

Inventariar las revisiones del protocolo de los clientes, los manejadores de inicialización, el almacenamiento de sesiones, los callbacks, las suscripciones y las políticas de autorización. Preparar un endpoint de preproducción detrás de una pasarela equivalente a la de producción, una configuración de reversión y clientes para ambas revisiones. Utilizar herramientas de prueba inocuas e identidades de prueba separadas. Registrar la versión real del paquete del SDK; una revisión del protocolo no es una versión de paquete.

Pasos

1. Separar las vías del protocolo. Las reglas de compatibilidad permiten ambos comportamientos en un mismo endpoint. Un initialize de un cliente anterior selecciona la semántica anterior; los metadatos por solicitud de la revisión moderna seleccionan el procesamiento sin estado. Conservar el comportamiento negociado de la revisión anterior mientras sus clientes sigan teniendo soporte. No aplicar indiscriminadamente los requisitos modernos de cabeceras a la inicialización anterior.

2. Hacer que las solicitudes sean autocontenidas. Exigir io.modelcontextprotocol/protocolVersion e io.modelcontextprotocol/clientCapabilities en params._meta. Incluir la identidad del cliente según lo recomendado, pero nunca utilizar esa identidad declarada por el propio cliente para autorizar el acceso. Dejar de deducir las capacidades o el contexto de la aplicación a partir de la conexión anterior. Exponer identificadores explícitos para el estado que abarque varias llamadas.

3. Implementar el descubrimiento y la validación del transporte. Implementar server/discover, reflejar la versión en MCP-Protocol-Version y validar las cabeceras obligatorias frente al cuerpo. Una comprobación básica de descubrimiento para un endpoint de preproducción sin autenticación es:

   curl --request POST 'https://mcp.example.com/mcp' \
     --header 'Content-Type: application/json' \
     --header 'Accept: application/json, text/event-stream' \
     --header 'MCP-Protocol-Version: 2026-07-28' \
     --header 'Mcp-Method: server/discover' \
     --data '{"jsonrpc":"2.0","id":1,"method":"server/discover","params":{"_meta":{"io.modelcontextprotocol/protocolVersion":"2026-07-28","io.modelcontextprotocol/clientCapabilities":{},"io.modelcontextprotocol/clientInfo":{"name":"migration-check","version":"local"}}}}'
   

   Sustituir la URL de ejemplo. Para endpoints protegidos, utilizar el cliente de prueba autenticado y aprobado para ese despliegue; no desactivar la autenticación para ejecutar esta comprobación.

4. Actualizar los resultados y las interacciones. Emitir resultType: "complete" para los resultados ordinarios. Implementar MRTR para las operaciones interactivas permitidas: devolver input_required y, a continuación, aceptar los inputResponses correspondientes y el requestState opaco sin modificar con un nuevo ID de solicitud. Verificar la integridad del estado cuando afecte a los permisos o a la lógica de negocio; vincularlo al sujeto autenticado, a una caducidad y a la operación de origen según lo recomendado. Imponer el uso único en el servidor cuando sea necesario.

5. Migrar las notificaciones y la caché. Sustituir el flujo GET independiente de notificaciones por subscriptions/listen. Conservar SSE asociado a la solicitud donde se utilice, pero eliminar la reanudación mediante Last-Event-ID: cerrar un flujo de respuesta indica la cancelación. Añadir un ttlMs no negativo y el cacheScope apropiado a los resultados completos cubiertos por la especificación de caché. Excluir de la caché los resultados intermedios y los de reintentos MRTR.

6. Probar expresamente la recuperación ante incompatibilidades de versión. Una versión moderna no admitida devuelve UnsupportedProtocolVersionError con las versiones compatibles. Los clientes deberían reintentar con una versión compatible. Ante un HTTP 400, inspeccionar el cuerpo JSON-RPC: los errores modernos reconocidos exigen una corrección o la selección de otra versión; un cuerpo vacío o no reconocido permite recurrir a la inicialización anterior. No pasar a una versión anterior solo porque se haya rechazado una solicitud moderna válida.

7. Probar el paso por la infraestructura del despliegue. En preproducción, ejecutar el descubrimiento, la obtención de listas, una llamada inocua, un reintento interactivo y una suscripción a través de la pasarela. Repetir con un cliente anterior y distribuir las solicitudes modernas entre varias instancias. Interrumpir una respuesta SSE inocua y verificar la cancelación y la recuperación segura sin reanudación. Verificar la autorización de cada identidad y confirmar que los metadatos de la solicitud llegan al servidor sin modificaciones.

Resultado esperado

Ambas revisiones admitidas completan sus respectivos flujos de trabajo. Las operaciones modernas no requieren una sesión de transporte; los clientes anteriores conservan el ciclo de vida negociado. Mantener disponible la configuración anterior hasta que se superen las comprobaciones de aceptación.

Límites y base de verificación

La especificación citada define el comportamiento del protocolo; los pasos anteriores son un plan de verificación propuesto por un operador. No acreditan la compatibilidad de los SDK, la seguridad de los reintentos de acciones de negocio ni el funcionamiento correcto en un balanceador de carga concreto. Eso requiere pruebas específicas del despliegue.