Inicio / Artículos

mcpmodel-context-protocolpythonmigrationai-agents

Migrar un servidor MCP a la especificación 2026-07-28: veinte minutos, paso a paso

Migrar un servidor MCP a la especificación del 28-07-2026 en aproximadamente veinte minutos: las sesiones han desaparecido, cinco cambios importantes, pasos para usar el SDK de Python 2.0 y la reescritura de MRTR.

Editor: REACTAPP.TOP10 min de lectura2207 palabras

Fuentes: Your MCP Server Is Running on a Deprecated Spec. Here’s the 20-Minute Migration.

Nada se rompió, y ese es el aspecto preocupante. El 28 de julio de 2026, el Model Context Protocol publicó su especificación 2026-07-28, el cambio más importante desde la aparición inicial del MCP remoto. Se eliminó un encabezado del que dependían los servidores y el modelo de transporte cambió de forma, pero se mantuvo la compatibilidad. Los servidores continuaron funcionando sin registros de errores, alertas ni indicaciones de compilación fallida.

Ese es el tipo silencioso de deuda técnica. Permanece oculta hasta que alguien necesita escalar la infraestructura, o hasta que finaliza el período de desuso de doce meses y una dependencia deja de recibir mantenimiento. Un servidor que sigue utilizando la versión del 28 de noviembre de 2025 está desactualizado. Uno que emplea el transporte HTTP+SSE heredado está utilizando una tecnología ya obsoleta, además de tres funcionalidades cuyo soporte está a punto de finalizar.

Lo que sigue explica qué cambió, por qué lo hicieron los mantenedores y cómo ponerse al día. Para la mayoría de los servidores, se trata de unos veinte minutos de trabajo. Sin embargo, hay un cambio que implica una reescritura real en algunos servidores, y es mejor indicarlo desde el principio.

Por qué cambiaron las sesiones

El motivo técnico explica todo lo demás. MCP se lanzó a finales de 2024 como un protocolo orientado a sesiones: el cliente inicia la conexión con un handshake initialize, el servidor emite un Mcp-Session-Id, y cada solicitud posterior lo incluye. Eso era adecuado para el caso original de un cliente y un servidor en una misma máquina a través de stdio.

Luego los servidores pasaron a infraestructura real y el diseño se topó con un obstáculo. Los ingenieros de Google describieron esto en su informe sobre la actualización sin estado: un diseño ideal para un único cliente local dejó de funcionar una vez que los servidores MCP se distribuyeron en infraestructura nativa en la nube.

Considere qué exige un ID de sesión: ya sea un enrutamiento persistente, para que un cliente siempre acceda a la misma instancia, o un almacén de sesiones compartido al que cualquier instancia pueda consultar. Un servicio HTTP simple necesita repentinamente un equilibrio de carga consciente de la afinidad y algo como Redis, simplemente para manejar el transporte, antes de poder realizar cualquier función útil.

El artículo de lanzamiento de David Soria Parra y Den Delimarsky lo expresa sin rodeos: MCP pasa de ser un protocolo bidireccional con estado a uno sin estado basado en solicitudes/respuestas, lo cual estaba entre los cambios más solicitados por los desarrolladores que buscaban fiabilidad y escalabilidad. La urgencia se debe al volumen: los SDK de nivel 1 registran casi cincuenta millones de descargas al mes, mientras que los SDK de TypeScript y Python ya han superado el billón de descargas en total. Un protocolo a esa escala no puede seguir dependiendo de que cada despliegue resuelva el problema de la afinidad de sesiones.

Por lo tanto, la sesión ya no existe. Cada solicitud lleva consigo su propia versión de protocolo, identidad del cliente y capacidades, lo que significa que cualquier solicitud puede llegar a cualquier instancia detrás de un balanceador simple de tipo round-robin sin almacenamiento compartido. Todo lo que sigue se deriva de esto.

Cinco cambios que hay que entender

1. Sin intercambio de datos iniciales, sin encabezado de sesión

El intercambio de initialize y initialized así como el encabezado Mcp-Session-Id han sido oficialmente retirados (SEP-2575 y SEP-2567). Cada solicitud funciona de forma independiente, con la versión, la identidad del cliente y sus capacidades incluidas en _meta. Una solicitud según la nueva especificación se ve así:

POST /mcp HTTP/1.1
MCP-Protocol-Version: 2026-07-28
Mcp-Method: tools/call
Mcp-Name: search

{"jsonrpc":"2.0","id":1,"method":"tools/call",
 "params":{"name":"search","arguments":{"q":"otters"},
 "_meta":{"io.modelcontextprotocol/clientInfo":
              {"name":"my-app",
                "version":"1.0"}
          }}}

Un cliente que quiera conocer las capacidades de un servidor de antemano puede utilizar la nueva RPC server/discover, la cual es opcional y ya no constituye un proceso de conexión obligatorio.

Un miedo común es que las aplicaciones ya no puedan mantener estado. Sin embargo, todavía pueden hacerlo. Eliminar la sesión del protocolo no obliga a una aplicación a ser sin estado. Cuando un servidor necesita continuidad, una herramienta debe generar un identificador explícito que el modelo devuelva posteriormente como argumento. Esto funciona mejor que almacenar el estado dentro del transporte, ya que el modelo puede ver el identificador y pasarlo de una herramienta a otra. Un estado visible es mejor que uno invisible.

2. Dos encabezados obligatorios

A partir de ahora, las solicitudes HTTP de Streamable deben incluir Mcp-Method y Mcp-Name (SEP-2243), y se espera que el servidor confirme que coinciden con la solicitud. Las ventajas para la infraestructura son que una pasarela, un limitador de velocidad o un WAF pueden enrutar y medir el tráfico mediante estos encabezados, evitando así el análisis de JSON. Aquellos que abandonaron el limitado de velocidad por herramienta en el nivel de red, debido a que el nombre de la herramienta estaba oculto dentro del contenido de la solicitud, ahora tienen una solución.

3. Respuestas de lista cachebillables

Los resultados de tools/list, prompts/list, resources/list y resources/read ahora incluyen ttlMs y cacheScope (SEP-2549) y se devuelven en un orden determinista. Los clientes pueden almacenar en caché el catálogo de herramientas y mantener estables las cachés de prompts en el servidor remoto durante las reconexiones. Dado que una gran parte de la facturación por tokens de un agente se debe a las definiciones de herramientas enviadas repetidamente, esto también funciona como una medida para reducir costos.

4. Autorización más estricta

Se han implementado cuatro cambios, y uno de ellos podría explicar un error con el que ya hayas tenido problemas:

  • Los servidores de autorización deben devolver el parámetro iss definido en RFC 9207, y los clientes deben verificarlo antes de canjear un código (SEP-2468), lo que cierra una vulnerabilidad relacionada con confusiones.
  • Los clientes establecen application_type durante el Registro Dinámico de Clientes (SEP-837), por lo que los servidores de autorización dejan de rechazar las redirecciones a localhost para aplicaciones de escritorio y de línea de comandos. Si el flujo OAuth de una aplicación de línea de comandos falló alguna vez por un error en redirect_uri, probablemente sea por esta razón.
  • Las credenciales del cliente están vinculadas al emisor que las creó y no pueden reutilizarse en diferentes servidores de autorización (SEP-2352).
  • El propio Registro Dinámico de Clientes está formalmente obsoleto en favor de los Documentos de Metadatos de ID de Cliente. Sigue funcionando y será eliminado en una versión futura.

5. La lista de obsoletos

La palabra obsoleto tiene gran importancia aquí. Roots, Sampling and Logging (SEP-2577) están obsoletos pero siguen funcionando, con al menos doce meses de vida útil, por lo que las nuevas implementaciones no deberían adoptarlos. El transporte HTTP+SSE heredado también está obsoleto, con un plazo similar de un año para su retiro.

Tasks fue reubicado, no obsoleto. Pasó de ser parte del núcleo experimental a formar parte de la extensión io.modelcontextprotocol/tasks; se consulta mediante tasks/get y se actualiza a través de la nueva función tasks/update (SEP-2663). Las notificaciones de cambios ahora fluyen a través de un único flujo subscriptions/listen al que los clientes deciden suscribirse.

La mejor noticia es la existencia de una política formal de obsolescencia que establece un plazo mínimo de doce meses. La información proporcionada por Real Python añade que el plazo mínimo de 90 días solo se aplica a riesgos de seguridad activos, lo cual representa un aviso más amplio que cualquier otro que haya existido hasta ahora en el ecosistema. Esa política podría ser más importante que cualquier otro aspecto de esta versión, ya que permite distinguir entre un protocolo con el que se experimenta y uno sobre el que se puede construir un negocio.

La migración, paso a paso

La guía utiliza el SDK de Python, cuyo cambio de nombre es el más problemático de los cuatro, aunque la estructura es la misma en TypeScript, Go y C#.

Minutos 0 a 2: decidir. Si el servidor utiliza muestreo, extracción de información o métodos basados en raíces, se necesita una reescritura completa, la cual se explica a continuación. Si solo expone herramientas y recursos, continuar.

Minutos 2 a 5: actualizar el SDK. El SDK de Python alcanzó la versión 2.0.0 el día en que se publicó la especificación, y ahora pip install mcp descarga la línea de versiones 2.x.

pip install --upgrade "mcp>=2"

Un cambio transitivo importante: el SDK pasó de httpx a httpx2. Si httpx está especificado en otro lugar de su árbol de dependencias, resuelva eso ahora mismo.

Minutos 5 a 10: renombrar la clase. Todos los servidores en Python se ven afectados. FastMCP ahora es MCPServer, sin alias ni mecanismo de transición para su desuso:

# Before, on mcp 1.x
from mcp.server.fastmcp import FastMCP

mcp = FastMCP("Demo")

# After, on mcp 2.x
from mcp.server.mcpserver import MCPServer

mcp = MCPServer("Demo")

Tres cambios de nombre más llegan en la misma versión:

# Wire types are snake_case now
result.isError        # → result.is_error
tool.inputSchema      # → tool.input_schema

# The error class matches the new capitalisation
except McpError:      # → except MCPError:

mcp-types ahora es un paquete independiente, pero mcp.types sigue siendo la ruta de importación admitida, por lo que esas importaciones seguirán funcionando. Una advertencia: quienes utilicen el paquete independiente fastmcp en lugar del SDK oficial no se verán afectados. Se trata de un proyecto distinto con sus propias versiones 3.x, y una de las razones del cambio de nombre es separarlos.

Minutos 10 a 15: eliminar la infraestructura de sesiones. Los diccionarios de sesiones, los temporizadores de limpieza y una instancia de Redis creada exclusivamente para el estado de las sesiones pueden eliminarse todos. Si realmente se necesita continuidad entre llamadas, utilice el patrón de handle:

# Instead of hiding state in a session the model can't see:
@mcp.tool()
def open_dataset(path: str) -> str:
    """Open a dataset and return a handle for subsequent calls."""
    handle = register_dataset(path)     # your own store, your own TTL
    return handle                        # the model now HOLDS this

@mcp.tool()
def query_dataset(handle: str, query: str) -> list[dict]:
    """Query a previously opened dataset."""
    return lookup(handle).query(query)

Minutos 15 a 18: validar los nuevos encabezados. El servidor debe comprobar que los valores de Mcp-Method y Mcp-Name recibidos coincidan con la solicitud. La SDK cubre el caso habitual, pero detrás de una pasarela personalizada o de un mecanismo de transporte escrito a mano, es necesario verificarlo de extremo a extremo.

Minutos 18 a 20: corregir el código de error. Es fácil pasarlo por alto, lo que genera un comportamiento confuso en el cliente. Los errores por recurso no encontrado deben utilizar el código estándar JSON-RPC invalid-params -32602 y no el código propio de MCP, -32002.

Listo para su lanzamiento

Un único MCPServer sirve a ambas eras del protocolo, por lo que un cliente de la era 2025 sigue funcionando con un servidor migrado sin necesidad de realizar configuraciones en ninguno de los lados. Por eso se puede lanzar en un día ordinario de martes, sin necesidad de coordinar un día especial en todos los clientes.

Cuando lleva más tiempo

Los servidores que utilizan muestreo, solicitud explícita o métodos basados en raíces enfrentan una reescritura real, que Real Python denomina el elemento más importante de la lista de migración. Anteriormente, el servidor podía iniciar una solicitud y devolver la respuesta al cliente a través de un flujo bidireccional permanente. Un diseño sin estado no cuenta con dicho flujo, por lo que se recurre a solicitudes múltiples de ida y vuelta (SEP-2322).

El nuevo flujo funciona de la siguiente manera: el servidor responde con resultType: "input_required" y las preguntas cuyas respuestas se necesitan, y el cliente repite la llamada original incluyendo sus respuestas en inputResponses. Esto cambia la forma en que se escriben las herramientas. Un manejador no puede detenerse a mitad de camino esperando una respuesta. Puede ser invocado varias veces para una misma operación lógica y debe continuar correctamente cuando llegue la entrada, por lo que todo lo almacenado en variables locales durante la pausa debe guardarse en un lugar al que pueda accederse en un intento de reintentar.

Los beneficios son reales. El jefe de producto de Supabase dijo que la implementación de esta funcionalidad llevaba tiempo en el plan de desarrollo, pero no era factible debido a que su servidor MCP funciona sin estado, mientras que MRTR lo hace posible, permitiendo que las herramientas consulten primero al usuario, por ejemplo, sobre el costo de un nuevo proyecto o una consulta que podría borrar datos. Escribir la herramienta se vuelve ligeramente más complicado, pero ejecutarla sin estado a gran escala se vuelve posible.

Qué aporta el nuevo protocolo

Manufact alberga miles de servidores MCP y mantiene el framework de código abierto mcp-use. Determinó que la versión SDK v2 es aproximadamente un 83% más pequeña y un 25% más rápida, atribuyéndolo a la nueva separación entre cliente y servidor. Según el resumen del ecosistema de la Agentic AI Foundation, ahora un servidor funciona como cualquier otro servicio HTTP, respondiendo desde la instancia que elige un balanceador round-robin, mientras que los gateways gestionan el enrutamiento y aplican límites de velocidad mediante encabezados. La política de doce meses implica que el protocolo también dejará de evolucionar sin que uno se dé cuenta.

La adopción fue rápida para un estándar abierto. En cuestión de días, los proveedores de infraestructura, los mantenedores de SDK, las plataformas en la nube y los vendedores de herramientas anunciaron su soporte, publicaron notas de migración y lanzaron implementaciones en producción. El Agents SDK de Cloudflare gestionó las especificaciones desde el día cero, Amazon Bedrock AgentCore incluye el núcleo sin estado, y Microsoft Foundry, Netlify, Figma, Supabase y Honeycomb se unieron también. Honeycomb afirma que casi una de cada cinco consultas interactivas mensuales proviene ahora de agentes, lo que explica por qué esto es importante. Los agentes ya han superado la fase de demostración.

Permanecer en 1.x

Esa es una opción legítima. Fijar y esperar:

# Buys you time, keeps security patches coming
pip install "mcp>=1.28,<2"

Conozca dos cosas mientras está allí. La línea 1.x se encuentra en modo de mantenimiento, con solo correcciones de seguridad. Además, la extensión Tasks aún no forma parte de la versión 2.0 del SDK de Python, por lo que Tasks ha sido eliminado de la especificación principal sin llegar al SDK. Para los usuarios de Python que dependen de Tasks, lo correcto es esperar. Programe un recordatorio en el calendario para el decimosegundo mes desde la publicación de Roots, Sampling and Logging, ya que los períodos de obsolescencia parecen interminables hasta que finalizan.

El peligro de la obsolescencia silenciosa

Un cambio que rompe la funcionalidad es evidente: hace que la compilación falle, alerta a alguien y se corrige. La obsolescencia, por diseño, es silenciosa. El servidor sigue funcionando, las pruebas pasan y nada se marca como error, mientras que los problemas se acumulan: un transporte con fecha de vencimiento, falta de escalabilidad horizontal sencilla y una dependencia en modo de mantenimiento mientras el ecosistema avanza. La versión indicada en MCP-Protocol-Version es una fecha, y vale la pena verificar cuán antigua es actualmente.

Para la mayoría de los servidores, ponerse al día lleva como máximo una tarde, y menos de media hora de trabajo real. Los servidores que utilicen muestreo o extracción de información deben reservar un día y leer primero la especificación MRTR. De cualquier manera, háganlo antes de que los doce meses se conviertan silenciosamente en dos.

Leer más

← Todos los artículosEnviar el brief