Migrar un servidor de la era 2025

Unos 31 minutos de lectura, con 6 ejemplos en 9 secciones.

Edición 2026.11.14 Ejemplos verificados el 19 de nov de 2026 70 de 70 ejemplos pasan Qué ha cambiado

Traducido con IA. Verificado por personas en inglés. Cómo hacemos los libros

Traducido del libro en inglés, edición 2026.11.14. Lee el original

Al final de este capítulo podrás migrar un servidor del Model Context Protocol escrito para las revisiones de 2025 y la línea 1.x del SDK de Python hacia la especificación en la revisión 2026-07-28 y mcp 2.3.0. Las afirmaciones sobre el destino valen para esa revisión y esa versión del SDK. Encontrarás de qué depende el servidor, eliminarás sus sesiones, lo sacarás del transporte HTTP+SSE, reemplazarás sampling, roots, logging y Dynamic Client Registration, portarás el código y servirás a clientes de ambas eras mientras sigan existiendo los antiguos.

Los capítulos anteriores construyeron el servidor de la tienda, el único caso de este libro, como shop-support para la revisión fijada desde el principio. La mayoría de los equipos no empiezan ahí. Tienen un servidor que un equipo de 2025 escribió para las revisiones 2025-03-26 a 2025-11-25 con el SDK 1.x, y hosts que todavía hablan esas revisiones. Este capítulo es el único que enseña el protocolo de 2025, y solo como el punto de partida de la migración.

Entre esas revisiones y la revisión fijada, el Model Context Protocol (MCP) eliminó el handshake initialize y las sesiones de protocolo, eliminó las peticiones que un servidor envía al cliente en medio de una llamada, y marcó como obsoletas cinco funciones y dos valores de un campo de sampling (registro de cambios). El servidor de la tienda de la era 2025 usa la mayoría de lo que esas revisiones eliminaron o marcaron como obsoleto. El listado que sigue es ese servidor, tal como lo escribiría un equipo para mcp==1.30.0:

"""shop-support as a 2025-era team wrote it, for SDK 1.x and revisions up to 2025-11-25."""
import os

from mcp.server.fastmcp import Context, FastMCP
from mcp.server.session import ServerSession
from mcp.types import SamplingMessage, TextContent
from pydantic import BaseModel

import shop_calls                                   # the shop's API, as chapter 3 calls it; not shown

server = FastMCP("shop-support", "Answers the support team's questions about orders, refunds and stock.",
                 port=8000, stateless_http=False)
quotes: dict[ServerSession, dict] = {}              # each connection's open quote

class Release(BaseModel):
    release: bool

@server.tool()
async def quote_refund(order_id: str, ctx: Context) -> dict:
    quotes[ctx.session] = quote = shop_calls.quote(order_id)
    await ctx.info(f"quoted {quote['amount']} for {order_id}")
    return quote

@server.tool()
async def issue_refund(ctx: Context) -> dict:
    quote = quotes.pop(ctx.session)                 # the quote this connection made last
    if not quote["within_limit"]:
        answer = await ctx.elicit(f"Refund {quote['amount']}? It is above the policy limit.", Release)
        if answer.action != "accept" or not answer.data.release:
            return shop_calls.hold(quote)
    return shop_calls.refund(quote)

@server.tool()
async def triage_ticket(text: str, ctx: Context) -> str:
    reply = await ctx.session.create_message(
        [SamplingMessage(role="user", content=TextContent(type="text", text=text))],
        max_tokens=20, system_prompt="Name the one shop tool this ticket needs.")
    return reply.content.text

@server.tool()
async def save_restock_report(ctx: Context) -> str:
    folder = (await ctx.session.list_roots()).roots[0].uri.path
    return shop_calls.write_restock_report(folder)

server.run(transport="sse" if os.environ.get("SHOP_OLD_HOSTS") else "streamable-http")   # HTTP+SSE: the 2024 transport

El listado es el servidor de la tienda de la era 2025, y un módulo compartido para este capítulo, lib.legacy, lo guarda como texto junto con la configuración OAuth del host y las reglas para localizar cada dependencia. Se muestra y se analiza, nunca se ejecuta. El SDK 1.x y el SDK 2.x son ambos la distribución mcp, así que un entorno contiene solo uno de los dos, y el entorno de los ejemplos fija la 2.x. Cada ejemplo ejecuta, en cambio, el servidor portado sobre la 2.x, o lee el listado. shop_calls representa las llamadas a la API de la tienda que hacen las herramientas del capítulo 3, y el listado no las muestra.

Esta parte aún no está traducida, así que está en inglés.

Inventory what the old server depends on

Último cambio en la edición 2026.11.14

A migration starts with a list, because the pinned revision treats each old feature in one of three ways, and each way sets its own deadline. The first group was removed at revision 2026-07-28, with no window: the initialize handshake, protocol sessions and the Mcp-Session-Id header, requests a server sends to the client in the middle of a call, whatever they ask for, the HTTP GET stream, resources/subscribe, ping, logging/setLevel and stream resumability (changelog). A client at the pinned revision never uses any of them, so code that depends on one fails for that client the first time it runs.

The second group is deprecated: roots, sampling, logging, the HTTP+SSE transport and Dynamic Client Registration. The changelog says that roots, sampling and logging stay "fully functional during the deprecation window" (same source), and the specification's registry gives each deprecated feature a migration path and an earliest removal (deprecated features). An earliest removal is the date when a feature becomes eligible to go, not when it goes. Removal is a decision the core maintainers make when they prepare a revision, so a feature may stay deprecated much longer (feature lifecycle). The window runs at least twelve months from the release of the revision that first marks the feature deprecated, and it can be cut to ninety days for an active security risk, so the windows differ from feature to feature. Dropping a feature from the specification doesn't oblige an SDK to drop it, because each SDK's own policy decides (same source).

The third kind isn't a protocol change at all. SDK 2.x renamed and moved parts of the 1.x API, so a 1.x server fails to start on 2.x even where the protocol didn't change (migration guide).

We parse the server listing in this chapter and the host's OAuth setup, shown in Replace dynamic client registration, with Python's ast module, and match each node against lib.legacy.RULES. Each rule names a dependency, its status at the pinned revision, its replacement and, for a deprecated feature, the registry's earliest removal. The scan then prints them grouped by status, with the function each one sits in.

scan-a-2025-server.py Python 3.12.15 Superado
"""Sorts the 2025-era server's dependencies, and its host's OAuth setup, into removed, deprecated and SDK changes, eachwith its replacement. The prose's point, that removed dependencies fail for every client at the pinned revision, rests on the first group'scount and the functions it names."""import astfrom lib import legacyfound: dict[str, list[str]] = {rule.feature: [] for rule in legacy.RULES}def where(tree: ast.Module, node: ast.AST, listing: str) -> str:    """The function a node sits in, or the listing's setup when it sits in none."""    for function in ast.walk(tree):        if isinstance(function, ast.AsyncFunctionDef | ast.FunctionDef) and node in ast.walk(function):            return function.name    return f"{listing} setup"                # module-level code, outside every functionfor listing, source in legacy.LISTINGS.items():    tree = ast.parse(source)                   # parsed, never run: SDK 1.x can't install beside 2.x    for node in ast.walk(tree):        for rule in legacy.RULES:            # each function is listed once per feature, however many of its nodes match            if rule.matches(node) and where(tree, node, listing) not in found[rule.feature]:                found[rule.feature].append(where(tree, node, listing))print("written for:", legacy.WRITTEN_FOR)for kind in ("removed", "deprecated", "sdk"):    rules = [rule for rule in legacy.RULES if rule.kind == kind and found[rule.feature]]   # a rule with no match is left out    print(f"{kind} dependencies:", len(rules))    for rule in rules:        print(f"  {rule.feature}: {', '.join(found[rule.feature])} -> {rule.replacement}")        if rule.removal:                          # only deprecated features have a removal date            print(f"  {rule.feature} earliest removal: {rule.removal}")
Salidapython scan-a-2025-server.py
written for: mcp==1.30.0
removed dependencies: 2
  sessions: server setup, quote_refund, issue_refund -> a handle the server mints, passed back as a tool argument
  pushed requests: triage_ticket, issue_refund, save_restock_report -> an input request in a Multi Round-Trip Request
deprecated dependencies: 5
  sampling: triage_ticket -> a model call the host or the server makes itself
  sampling earliest removal: first revision released on or after 2027-07-28
  roots: save_restock_report -> a tool parameter, a resource URI or server configuration
  roots earliest removal: first revision released on or after 2027-07-28
  logging: quote_refund -> stderr on stdio, or OpenTelemetry
  logging earliest removal: first revision released on or after 2027-07-28
  HTTP+SSE transport: server setup -> Streamable HTTP
  HTTP+SSE transport earliest removal: three months after SEP-2596 reaches Final
  dynamic client registration: host setup -> a Client ID Metadata Document
  dynamic client registration earliest removal: first revision released on or after 2027-07-28
sdk dependencies: 3
  FastMCP: server setup -> mcp.server.mcpserver.MCPServer
  positional instructions: server setup -> instructions= by keyword
  transport settings on the constructor: server setup -> arguments to run() or streamable_http_app()

The removed ones come first, because they fail for every client at the pinned revision. The scan found 2 removed dependencies, 5 deprecated ones and 3 SDK changes. The removed dependencies are the sessions that quote_refund and issue_refund share, and the requests that three tools push in the middle of a call: ctx.elicit in issue_refund, create_message in triage_ticket and list_roots in save_restock_report.

So sampling and roots are on both lists. As features they are deprecated, and they keep working through their window: for a 2025-era client as written, and for a client at the pinned revision only when the server asks for them through a round trip, as Replace sampling, roots and logging shows. Pushed mid-call, they fail for that client as ctx.elicit does, with SDK 2.3.0 raising NoBackChannelError (mcp/server/_streamable_http_modern.py). Of sampling, roots and logging, only logging works as written for a client at the pinned revision, and only for a request whose _meta asks for a log level. For any other request the SDK drops the line (mcp/server/connection.py).

Four of the deprecated features share one earliest removal, the first revision released on or after 2027-07-28. The HTTP+SSE transport's date is different, and Move from HTTP+SSE to Streamable HTTP gives it.

The SDK at 2.3.0 doesn't warn about all of these either. Its sampling, roots and logging APIs emit MCPDeprecationWarning, a UserWarning that prints by default (what's new). Its HTTP+SSE app and client and its registration code carry no deprecation marker: we searched mcp/server/sse.py, mcp/client/sse.py, mcp/server/auth/handlers/register.py and mcp/client/auth/oauth2.py for "deprecat" and found nothing. A server can run on 2.x without a single warning and still depend on two deprecated features.

Working rule: Inventory before you change anything, and sort the list by status. Fix every removed dependency before you let a client at the pinned revision connect, because there is no window for it, and count every request the server pushes mid-call as removed, even when the feature it asks for is only deprecated. Give each deprecated one a date of your own, earlier than the registry's earliest removal, and don't wait for warnings: run a scan like this one in CI, because the SDK is silent about some deprecated features.

Eliminar initialize y los ID de sesión

Último cambio en la edición 2026.11.11

El análisis de Inventariar de qué depende el servidor antiguo enumeró primero las sesiones. Bajo las revisiones de 2025, una conexión comenzaba con initialize, y un servidor Streamable HTTP podía asignar un ID de sesión en su respuesta. El cliente debía entonces enviar Mcp-Session-Id en cada solicitud, iniciar una sesión nueva cuando el servidor respondía 404, y terminarla con DELETE (transportes de 2025-11-25). Un servidor podía guardar lo que quisiera por sesión.

La revisión fijada elimina el protocolo de enlace y las sesiones. Cada solicitud lleva su versión del protocolo y las capacidades del cliente en _meta. Un cliente pregunta qué admite un servidor con server/discover, que todo servidor DEBE implementar, y un servidor que necesita estado entre llamadas genera un manejador explícito y hace que el cliente lo devuelva como un argumento ordinario de la herramienta (registro de cambios). Incluir la versión y las capacidades en cada solicitud muestra las claves de _meta.

El servidor de la era 2025 guarda una pieza de estado por sesión. quote_refund almacena la cotización bajo ctx.session, el objeto del SDK para la conexión, y issue_refund no recibe argumentos y reembolsa la cotización que hizo esa conexión por última vez. Con el SDK 1.x, un mismo objeto atiende cada solicitud de una conexión (mcp/server/lowlevel/server.py en la 1.x), así que esto funcionaba. Pasamos las dos herramientas a la 2.x sin cambios, como envoltorios de las funciones de cotización y reembolso del capítulo 3, y llamamos a cada una una vez desde un mismo cliente en la revisión fijada. Después llamamos al servidor del capítulo 3, cuyo quote_refund devuelve un quote_id que issue_refund acepta, de la misma manera.

stateless-after-migration.py Python 3.12.15 · cryptography 50.0.2 · httpx2 2.16.2 · jsonschema 4.26.0 · mcp 2.3.0 · mcp-types 2.3.0 · pydantic 2.14.3 · starlette 1.10.0 · uvicorn 0.54.0 Superado
"""Ports the 2025 server's per-connection quote to SDK 2.x unchanged, then with the handle the pinned revision asks for.The prose's point rests on the session-keyed failure, the count of session objects, and the handle's refund line."""import asyncioimport osfrom mcp import Clientfrom mcp.server.mcpserver import Context, MCPServerfrom mcp.server.mcpserver.exceptions import ToolErrorfrom lib import confirmations, loopback, shop_api, shop_toolschapter3 = confirmations.chapter3_tools()          # quote_refund and issue_refund from lib.shop_toolsserver = MCPServer("shop-support", version="0.12.0")quotes = {}                                        # the 2025 code: each connection's open quote, by its sessionsessions_seen = set()@server.tool(description="Quote a refund for a whole order, for issue_refund to refund.")def quote_refund(order_id: str, ctx: Context) -> str:    sessions_seen.add(id(ctx.session))       # each request gets its own session object at the pinned revision    quotes[ctx.session] = chapter3["quote_refund"].fn(order_id, sku="KG-1050")   # chapter 3's quote needs a SKU; the port pins one    return f"Quoted {quotes[ctx.session].amount}."@server.tool(description="Refund the quote this connection made last.")def issue_refund(ctx: Context) -> shop_tools.Refund:    sessions_seen.add(id(ctx.session))    if ctx.session not in quotes:        raise ToolError("There is no open quote in this session. Call quote_refund first.")    return chapter3["issue_refund"].fn(quotes.pop(ctx.session).quote_id)   # pop: a quote is used onceasync def main() -> None:    with loopback.serve(shop_api.create_app()) as api_url:        os.environ.update(shop_api.server_env(api_url))      # both servers run in this process        with loopback.serve(server.streamable_http_app()) as old, \             loopback.serve(shop_tools.create_server().streamable_http_app()) as new:            async with Client(old + "/mcp") as client:                await client.call_tool("quote_refund", {"order_id": "O-2415"})                print("session-keyed issue_refund:", (await client.call_tool("issue_refund", {})).content[0].text)                print("session objects in two calls:", len(sessions_seen))            async with Client(new + "/mcp") as client:                quote = await client.call_tool("quote_refund", {"order_id": "O-2415", "sku": "KG-1050"})                refund = await client.call_tool("issue_refund", {"quote_id": quote.structured_content["quote_id"]})                print("handle issue_refund:", refund.structured_content["status"], refund.structured_content["amount"])asyncio.run(main())
Salidapython stateless-after-migration.py
session-keyed issue_refund: Error executing tool issue_refund: There is no open quote in this session. Call quote_refund first.
session objects in two calls: 2
handle issue_refund: requested 23.98

Ejecutado sin cambios, el puerto falló en su segunda llamada: "Error executing tool issue_refund: There is no open quote in this session. Call quote_refund first." Las dos llamadas provenían de un mismo cliente hacia un mismo proceso, y sin embargo vieron 2 objetos de sesión distintos. En la revisión fijada no existe una conexión a la que pertenezca una sesión, así que el SDK da a cada solicitud la suya. Nada falló al guardar la cotización, y el error solo aparece cuando algo la vuelve a leer. Un servidor que indexara su estado por la cabecera Mcp-Session-Id lo haría peor: en la revisión fijada ningún cliente envía esa cabecera, así que el estado de todos los clientes quedaría bajo la misma clave, None.

Con el manejador, el reembolso se realizó: requested 23.98. Este es el diseño que Diseñar las herramientas en torno a tareas, no a endpoints eligió para el capítulo 3. La guía de la especificación para estos manejadores es que sean opacos y caduquen, y que un servidor con autenticación verifique en cada llamada que quien llama está autorizado a usar el manejador (herramientas). Evitar que el servidor actúe como un diputado confundido vincula los ID de cotización de la tienda con el cliente al que se emitieron. Un manejador en la memoria de un proceso sigue muriendo con ese proceso, así que, una vez que el servidor se ejecuta en réplicas, los manejadores irán en un almacenamiento compartido, como hace Ejecutar réplicas sin sesiones fijas con SQLite.

Regla práctica: Busca en el servidor antiguo cada uso de la sesión, su ID y todo lo que se guarde por conexión, y convierte cada pieza de estado en un manejador que una herramienta devuelve y la siguiente recibe como argumento. Haz que el manejador sea opaco, dale una caducidad que indique la descripción de la herramienta que lo crea, comprueba en cada llamada que quien llama puede usarlo, y guárdalo donde todas las réplicas puedan leerlo. No guardes nada que una llamada posterior necesite en un diccionario indexado por la sesión, ni siquiera para los clientes de la era 2025 que aún lo tengan.

Pasar de HTTP+SSE a Streamable HTTP

Último cambio en la edición 2026.11.11

Las sesiones de Eliminar initialize e IDs de sesión pertenecen a la forma de 2025 de Streamable HTTP. Un segundo transporte, más antiguo, sigue presente en el servidor de la tienda de 2025: su última línea sirve HTTP+SSE, el transporte que la revisión 2025-03-26 reemplazó, cuando SHOP_OLD_HOSTS está definido. En ese transporte, el cliente mantiene abierto un flujo de eventos en un endpoint y envía sus mensajes a un segundo (Streamable HTTP). El SDK 1.x sirve el par en /sse y /messages/ (mcp/server/fastmcp/server.py en la 1.x). La revisión 2025-03-26 puso Streamable HTTP en su lugar (registro de cambios de 2025-03-26), y la revisión fijada lo incluye en la política de ciclo de vida, con una ventana más corta (registro de cambios).

En el servidor, el cambio consiste en eliminar código. El servidor de la tienda ya portado sirve streamable_http_app(), o run(transport="streamable-http"), en un solo endpoint, como en Pasar el servidor de stdio a HTTP, y nada en sus herramientas cambia. Todo cliente de la revisión fijada que se conecte por HTTP usa Streamable HTTP, así que el transporte no es lo que les impide conectarse. Lo que decide cuándo puede retirarse el transporte antiguo son los hosts que todavía se conectan por HTTP+SSE, y por definición son clientes de la era 2025.

Esos hosts tienen dos caminos. Un servidor que deba seguir atendiéndolos puede alojar los endpoints antiguos de SSE y POST junto a su endpoint de Streamable HTTP, algo que la especificación permite desde la revisión 2025-03-26 (Streamable HTTP). El SDK 2.3.0 todavía tiene MCPServer.sse_app(), con las mismas dos rutas que la 1.x, y run(transport="sse") (mcp/server/mcpserver/server.py). Como encontró Inventariar de qué depende el servidor antiguo, ninguno de los dos emite una advertencia de obsolescencia. O bien los hosts se pasan a Streamable HTTP, que el cliente del SDK 1.x ya habla (mcp/client/streamable_http.py en la 1.x).

La fecha de eliminación más temprana que indica el registro para HTTP+SSE es three months after SEP-2596 reaches Final, que puede que ya haya pasado. Eso no significa que el SDK elimine sse_app() ese día, ya que cada SDK decide por su cuenta (ciclo de vida de las funciones). El transporte ya llevaba más de un año obsoleto cuando SEP-2596 fijó la política de ciclo de vida, así que recibió un periodo de gracia de tres meses en lugar de doce, y la página de la propuesta lo marca como Final sin fecha. La fecha significa que un host no puede dar por hecho que el transporte sobreviva a la próxima revisión, y tampoco tú.

El equipo de soporte de la tienda eligió una fecha. Los endpoints antiguos permanecen solo mientras los registros del servidor muestren un host conectándose a /sse, y el equipo comunica al responsable de cada host de ese tipo la fecha en que los endpoints se retiran. Un host que no pueda migrar para entonces puede quedarse en el SDK 1.x contra una implementación 1.x del servidor antiguo, que cubre Portar el código del SDK 1.x al 2.x.

Regla práctica: Elimina el transporte HTTP+SSE del servidor en lugar de portarlo, a menos que tus registros muestren hosts que todavía lo usan. Si los hay, sirve los endpoints antiguos junto al endpoint de Streamable HTTP, registra cada conexión a ellos por cliente y fija una fecha para retirarlos que comuniques al responsable de cada host. Considera el transporte como ya elegible para su retirada, porque su ventana fue de tres meses, no de doce.

Reemplazar sampling, roots y logging

Último cambio en la edición 2026.11.11

Tres de las dependencias que Inventariar de qué depende el servidor antiguo encontró tienen dos cambios superpuestos, y conviene separarlos. El primero es un mecanismo. Un servidor de 2025 enviaba su propia petición al cliente en medio de una llamada (elicitation/create, sampling/createMessage, roots/list) y esperaba la respuesta. La revisión fijada dice que ese patrón "ya no está soportado" y que se trata de un cambio incompatible. Ahora un servidor pregunta mediante una Petición de Múltiples Vueltas, devolviendo una solicitud de entrada cuyos valores pueden ser un ElicitRequest, un CreateMessageRequest o un ListRootsRequest (Peticiones de Múltiples Vueltas). El segundo son las propias funciones. Roots, sampling y logging están obsoletas, con rutas de migración en el registro: roots hacia parámetros de herramienta, URIs de recurso o configuración del servidor; sampling hacia la integración directa con la API de un proveedor de modelos; logging hacia stderr en stdio, o OpenTelemetry (funciones obsoletas).

Así que una Petición de Múltiples Vueltas reemplaza el envío, no sampling. Un servidor que traslada su sampling/createMessage a una solicitud de entrada sigue dependiendo de una función obsoleta. Elicitation es la única de las tres que no está obsoleta, así que es la única que vale la pena trasladar a la ronda de ida y vuelta y conservar.

El issue_refund de la era 2025 enviaba su confirmación con ctx.elicit, lo que falla en la revisión fijada, como mostró Ver por qué un servidor sin estado no puede esperar una respuesta. El port pregunta con un resolvedor. Un parámetro declarado Annotated[Release, Resolve(confirm)] se rellena ejecutando confirm antes de la herramienta, y cuando confirm devuelve Elicit(...), el SDK pregunta a la persona en el host (Pedir entrada estructurada con elicitation). confirm pregunta solo cuando la API de la tienda retiene el reembolso para confirmación. Citamos el pedido O-2289, cuyo reembolso supera el límite de la política, llamamos a issue_refund una vez a mano para ver la primera vuelta, y luego dejamos que Client ejecute las vueltas con el responsable simulado del capítulo 5, que dice que sí.

replace-pushed-requests.py Python 3.12.15 · cryptography 50.0.2 · httpx2 2.16.2 · jsonschema 4.26.0 · mcp 2.3.0 · mcp-types 2.3.0 · pydantic 2.14.3 · starlette 1.10.0 · uvicorn 0.54.0 Superado
"""Ports the 2025 server's pushed confirmation to a resolver that serves both eras, and its log line to stderr. The prose'spoint rests on the first round's result and the question it asks, and the refund's status after the lead's yes."""import asyncioimport loggingimport osfrom typing import Annotatedfrom mcp import Clientfrom mcp.server.mcpserver import Elicit, Resolvefrom pydantic import BaseModelfrom lib import confirmations, loopback, shop_api, shop_toolsserver, held = confirmations.shop_server(version="0.12.0")   # chapter 3's other tools; held is its issue_refundlog = logging.getLogger("shop-support")                       # to stderr, not to the clientclass Release(BaseModel):    release: booldef confirm(quote_id: confirmations.QuoteId) -> Elicit[Release] | Release:    refund = held.fn(quote_id)                                # the same quote always gives the same refund    if refund.status != "needs_confirmation":        return Release(release=False)                         # nothing held, so nothing to ask    # returning Elicit asks the person at the host; the SDK sends the question in the client's form    return Elicit(f"Refund {refund.amount} on order {refund.order_id}? It is above the policy limit.", Release)@server.tool(description=shop_tools.DESCRIPTIONS["issue_refund"], annotations=held.annotations)def issue_refund(quote_id: confirmations.QuoteId, answer: Annotated[Release, Resolve(confirm)]) -> shop_tools.Refund:    refund = held.fn(quote_id)    if refund.status == "needs_confirmation" and answer.release:        refund = confirmations.release(refund)    log.info("refund %s is %s", refund.refund_id, refund.status)    return refundasync def main() -> None:    with loopback.serve(shop_api.create_app()) as api_url:        os.environ.update(shop_api.server_env(api_url))      # the server runs in this process        with loopback.serve(server.streamable_http_app()) as url:            async with Client(url + "/mcp", elicitation_callback=confirmations.say_yes) as client:                quote = (await client.call_tool("quote_refund", {"order_id": "O-2289"})).structured_content                first = await client.session.call_tool("issue_refund", {"quote_id": quote["quote_id"]},                                                        allow_input_required=True)   # returns the input request, not an answer                print("first round:", first.result_type)                print("first round asks:", ", ".join(r.method for r in first.input_requests.values()))                refund = await client.call_tool("issue_refund", {"quote_id": quote["quote_id"]})   # Client answers with the lead's yes                print("refund after the lead's yes:", refund.structured_content["status"])asyncio.run(main())
Salidapython replace-pushed-requests.py
first round: input_required
first round asks: elicitation/create
refund after the lead's yes: requested

La primera vuelta llegó como input_required, con una pregunta, elicitation/create: la misma solicitud que el servidor de 2025 enviaba, ahora dentro de un resultado. Tras el sí del responsable, el estado del reembolso fue requested. El resolvedor también funciona con clientes de la era 2025, porque el SDK envía sus preguntas en la forma que usa la revisión del cliente (mcp/server/mcpserver/resolve.py). Atender a clientes antiguos y nuevos durante la ventana ejecuta ambos.

La línea de registro del port usa el logging de Python, no ctx.info. MCPServer configura el logging hacia stderr al construirse (mcp/server/mcpserver/utilities/logging.py), así que la línea va a los registros propios del servidor y nunca al cliente. En stdio, stdout transporta solo los mensajes del protocolo, y stderr es el lugar de los registros de un servidor (stdio). Trazar llamadas con OpenTelemetry cubre la otra vía.

Sampling desaparece por completo. El triage_ticket de la era 2025 pedía al modelo del host, mediante sampling, qué herramienta necesita un ticket, y el port elimina esa herramienta. El propio modelo del host ya lee cada ticket y elige las herramientas (Trabajar la cola de tickets), así que el servidor pedía al host que hiciera lo que el host ya hace. Un servidor que necesita un modelo para su propio trabajo llama a un proveedor de modelos con sus propias credenciales, lo que además le permite elegir y pagar el modelo.

save_restock_report pedía al cliente sus roots y escribía en el primero. Su port recibe la carpeta como parámetro y la comprueba frente a las carpetas que permite la configuración del servidor, en SHOP_EXPORT_DIRS, después de resolver la ruta, de modo que .. no pueda salirse.

roots-to-a-parameter.py Python 3.12.15 · cryptography 50.0.2 · httpx2 2.16.2 · jsonschema 4.26.0 · mcp 2.3.0 · mcp-types 2.3.0 · pydantic 2.14.3 · starlette 1.10.0 · uvicorn 0.54.0 Superado
"""Replaces the 2025 server's roots with a folder parameter that the server checks against its own allow-list. The prose'spoint rests on the two export lines: the allowed folder saves, and the path that climbs out is refused."""import asyncioimport osfrom pathlib import Pathfrom mcp import Clientfrom mcp.server.mcpserver import MCPServerfrom mcp.server.mcpserver.exceptions import ToolErrorfrom lib import loopback, restock, shop_apiserver = MCPServer("shop-support", version="0.12.0")EXPORT_DIRS = [Path(d).resolve() for d in os.environ.get("SHOP_EXPORT_DIRS", "exports").split(",")]   # the allow-list; a relative entry resolves from the working directory@server.tool(description="Recount stock and save the restock report as CSV in export_dir, a folder the server allows.")async def save_restock_report(export_dir: str) -> str:    folder = Path(export_dir).resolve()                  # "exports/../private" resolves outside exports    if folder not in EXPORT_DIRS:            # an exact match, so a subfolder of an allowed folder is refused too        raise ToolError(f"{export_dir} isn't an export folder. Use one of: {', '.join(d.name for d in EXPORT_DIRS)}.")    report = await restock.run(below=30, seconds=0)   # reports SKUs under 30 units; seconds=0 skips the per-SKU wait    folder.mkdir(exist_ok=True)    (folder / "restock.csv").write_text("sku,units\n" + "".join(f"{r.sku},{r.units}\n" for r in report.reorder))    return f"Saved {len(report.reorder)} products to reorder in {export_dir}/restock.csv."async def main() -> None:    with loopback.serve(shop_api.create_app()) as api_url:        os.environ.update(shop_api.server_env(api_url))      # the server runs in this process        async with Client(server) as client:            for folder in ("exports", "exports/../private"):                saved = await client.call_tool("save_restock_report", {"export_dir": folder})                print(f"export to {folder}:", saved.content[0].text)asyncio.run(main())
Salidapython roots-to-a-parameter.py
export to exports: Saved 5 products to reorder in exports/restock.csv.
export to exports/../private: Error executing tool save_restock_report: exports/../private isn't an export folder. Use one of: exports.

La carpeta permitida funcionó: "Saved 5 products to reorder in exports/restock.csv." La ruta que sale fuera no: "Error executing tool save_restock_report: exports/../private isn't an export folder. Use one of: exports." Ahora el host o el modelo pasan la carpeta, y el servidor, no el cliente, decide dónde puede escribir.

Regla práctica: Traslada cada elicitation enviada a un resolvedor, que sirve a ambas eras. Elimina sampling en lugar de trasladarlo: deja que el modelo del host haga el trabajo de modelo, o llama a un proveedor desde el servidor con las credenciales propias del servidor. Convierte roots en un parámetro verificado contra una lista de permitidos en la configuración del servidor, y envía las líneas de registro a stderr y a tus trazas, nunca al cliente.

Reemplazar el registro dinámico de clientes

Último cambio en la edición 2026.11.11

La última dependencia obsoleta que encontró el inventario está en el host, no en el servidor, pero decide si el host del equipo de soporte puede obtener un token para el servidor migrado. El host de 2025 se registraba a sí mismo ante cada servidor de autorización con el que se encontraba, mediante OAuth Dynamic Client Registration:

"""How the support team's 2025 host got tokens for shop-support: it registered itself with each authorization server."""
from mcp.client.auth import OAuthClientProvider
from mcp.shared.auth import OAuthClientMetadata

auth = OAuthClientProvider(
    server_url="https://mcp.fernhill.example/mcp",
    client_metadata=OAuthClientMetadata(client_name="Support desk", redirect_uris=["http://127.0.0.1:3030/callback"]),
    storage=token_store, redirect_handler=open_browser, callback_handler=wait_for_code,
)

El OAuthClientProvider de SDK 1.x se registra de esta manera cuando no se le proporciona un client_metadata_url (mcp/client/auth/oauth2.py en 1.x). La revisión fijada depreca el Dynamic Client Registration en favor de los Client ID Metadata Documents, que la revisión 2025-11-25 ya recomendaba, y lo mantiene por compatibilidad con versiones anteriores (changelog; changelog de 2025-11-25). Su eliminación más temprana es el first revision released on or after 2027-07-28.

Un Client ID Metadata Document hace que el identificador del cliente sea una URL https:// donde el host publica sus propios metadatos, de modo que ningún servidor de autorización tiene que registrarlo antes. Identificar el cliente con un documento de metadatos construye uno para el host de la tienda y muestra el orden en que la revisión fijada clasifica las opciones: credenciales preregistradas, luego un documento de metadatos y, por último, el registro.

La migración es un solo argumento. El host pasa la URL de su documento como client_metadata_url, y el OAuthClientProvider de SDK 2.x usa entonces el documento cuando el servidor de autorización anuncia client_id_metadata_document_supported. Cuando el servidor no lo anuncia, el proveedor recurre al registro sin avisar, como mostró el ejemplo del capítulo 8, y el código de registro del SDK en 2.3.0 no emite ninguna advertencia de obsolescencia. Por tanto, el servidor de autorización es la mitad de la migración. Tiene que anunciar el soporte de documentos de metadatos, y debe mantener su endpoint de registro solo durante el periodo de transición y solo para los hosts que no puedan publicar un documento.

Hay dos reglas de la revisión fijada que importan mientras el registro siga vigente. Un cliente DEBE indexar las credenciales que guarda por el emisor del servidor de autorización y registrarse de nuevo cuando cambie el servidor de autorización (changelog; registro de clientes). Un cliente que se registra DEBE enviar un application_type adecuado, que DEBERÍA ser native para un host que se ejecuta en la máquina del usuario con una redirección de loopback, como es este caso (changelog; registro de clientes). Un host de 2025 que guardaba un identificador de cliente por cada URL de servidor MCP se rompe con la primera regla el día en que la tienda cambie su servidor de autorización.

Regla práctica: Publica un Client ID Metadata Document para cada host y pasa su URL como client_metadata_url. Haz que cada servidor de autorización que operes anuncie el soporte para él, mantén su endpoint de registro solo hasta que los hosts que lo necesitan se hayan trasladado, y registra qué tipo de identificador de cliente se emitió con cada token, para poder ver cuándo ha cesado el tráfico de registro.

Porta el código de la SDK 1.x a la 2.x

Último cambio en la edición 2026.11.11

Las secciones anteriores cambiaron lo que hace el servidor de la tienda. Los cambios de la SDK que Inventaría de qué depende el servidor antiguo encontró son un trabajo aparte, y son los que impiden que el archivo antiguo arranque en la 2.x. Dos hechos determinan ese trabajo. El primero es que la línea 1.x sigue en mantenimiento. La primera versión 2.x y una versión 1.x se publicaron el 2026-07-28, el día de la revisión fijada, y la versión 1.x del 2026-09-07, mcp==1.30.0, es una "maintenance release of the 1.x line" (PyPI; notas de la versión). La guía de migración indica que la línea 1.x sigue recibiendo correcciones críticas de errores y parches de seguridad, y que nadie ha publicado una fecha de fin (guía de migración). El segundo hecho es que ambas líneas forman la única distribución mcp, así que un despliegue ejecuta una u otra, nunca las dos.

La guía enumera los cambios que rompen compatibilidad. Los que afectan a un servidor como el de la tienda: mcp.server.fastmcp.FastMCP es mcp.server.mcpserver.MCPServer; McpError es MCPError(code, message, data); los campos usan snake_case (input_schema, is_error); el cliente HTTP es httpx2, no httpx; streamablehttp_client desaparece en favor de streamable_http_client; host, port, stateless_http y json_response pasaron del constructor a run() y streamable_http_app(); instructions ya no es el segundo argumento posicional; las variables de entorno MCP_* ya no se leen; se elimina el transporte WebSocket; y ctx.log recibe data, no message (guía de migración).

La mayoría de estos fallan de forma ruidosa, que es lo que conviene. Uno no. Ejecutamos las líneas de configuración del servidor de la era 2025 con 2.3.0 y observamos la importación, la excepción que lanzaba y el constructor. Después construimos el servidor dos veces, una con los argumentos tal como están escritos y otra portados, y preguntamos a cada uno qué ve un cliente.

port-to-sdk-2.py Python 3.12.15 · mcp 2.3.0 Superado
"""Tries the 2025 server's setup lines on SDK 2.x: two breaks fail with an error, and one fails silently. The prose's point,that the second positional argument now sets the title, rests on the two title and instructions lines a client sees."""import asynciofrom mcp import Clientfrom mcp.server.mcpserver import MCPServerINSTRUCTIONS = "Answers the support team's questions about orders, refunds and stock."try:    from mcp.server.fastmcp import FastMCP          # the 2025 server's first importexcept ModuleNotFoundError as error:    print("import FastMCP:", str(error).split(". ", 1)[1].split("; see")[0])   # the message after its first sentencetry:    from mcp.shared.exceptions import McpError      # what 1.x tools raised for protocol errorsexcept ImportError as error:    print("import McpError:", str(error).split(" (")[0])   # drops the parentheticaltry:    MCPServer("shop-support", instructions=INSTRUCTIONS, port=8000, stateless_http=False)   # port and stateless_http moved to run() and streamable_http_app() in 2.xexcept TypeError as error:    print("port on the constructor:", error)as_written = MCPServer("shop-support", INSTRUCTIONS)                     # 1.x's second argument was instructionsported = MCPServer("shop-support", instructions=INSTRUCTIONS, version="0.12.0")   # a keyword, so the string can't become the titleasync def main() -> None:    for label, server in (("as written", as_written), ("ported", ported)):        async with Client(server) as client:            print(f"{label} title:", client.server_info.title)            print(f"{label} instructions:", client.instructions)asyncio.run(main())
Salidapython port-to-sdk-2.py
import FastMCP: This is mcp 2.x, where FastMCP was renamed to MCPServer (from mcp.server.mcpserver import MCPServer) and other APIs changed
import McpError: cannot import name 'McpError' from 'mcp.shared.exceptions'
port on the constructor: MCPServer.__init__() got an unexpected keyword argument 'port'
as written title: Answers the support team's questions about orders, refunds and stock.
as written instructions: None
ported title: None
ported instructions: Answers the support team's questions about orders, refunds and stock.

La importación falló con un mensaje que indica el cambio de nombre y la importación que debe usarse en su lugar: "This is mcp 2.x, where FastMCP was renamed to MCPServer (from mcp.server.mcpserver import MCPServer) and other APIs changed" (mcp/server/fastmcp.py, que existe solo para lanzarlo). McpError falló con "cannot import name 'McpError' from 'mcp.shared.exceptions'", y el constructor con "MCPServer.init() got an unexpected keyword argument 'port'". Cada uno señala la línea que hay que cambiar.

El constructor tal como estaba escrito no falló. En la 2.x el segundo argumento posicional es title (mcp/server/mcpserver/server.py), así que las instrucciones del servidor se convirtieron en su título. Un cliente vio el título "Answers the support team's questions about orders, refunds and stock." y ninguna instrucción (None), y un host que coloca las instrucciones de un servidor en el contexto del modelo perdería esas instrucciones en silencio. Con instructions= pasado por palabra clave, el título del servidor portado es None y sus instrucciones llegan. El número de puerto pasa a la última línea, como server.run(transport="streamable-http", port=8000).

Los cambios silenciosos comparten una forma: un argumento que sigue pasando la comprobación de tipos, o un ajuste que nada lee, como las variables de entorno MCP_*. Encuéntralos cruzando la lista de la guía con el código, no esperando a que aparezcan errores, y comprueba qué ve un cliente con una prueba como la que construye el servidor dos veces.

Regla práctica: Mantén un servidor de la era 2025 fijado a mcp<2 hasta que su port pase sus pruebas, y después porta en un solo cambio: las importaciones y renombrados que señalan los errores, y luego cada cambio silencioso de la guía de migración, comprobado con una prueba frente a lo que ve un cliente. Después fija la versión 2.x exactamente, y trata cada versión 2.x como un cambio que hay que probar, ya que las advertencias y los valores por defecto de la SDK cambian entre versiones.

Esta parte aún no está traducida, así que está en inglés.

Serve old and new clients through the window

Último cambio en la edición 2026.11.14

The ported server from Replace sampling, roots and logging answers clients at the pinned revision. The support team's hosts don't all move on one day, and a 2025-era host can't move forward on its own: it sends initialize and expects an answer. The pinned revision allows a dual-era server, which serves both eras on the same endpoint. An initialize request selects the 2025 semantics for that process on stdio or that session on HTTP, and a request with the pinned revision's _meta is served statelessly. A server that serves only the pinned revision SHOULD name the versions it supports in its error to initialize, because a 2025 client can't discover them any other way (versioning). On the other side, a 2.x Client in its default mode tries server/discover first and falls back to initialize (mcp/client/_probe.py; Call the tool from a client).

At 2.3.0, MCPServer.streamable_http_app() is dual-era with nothing to configure. It reads each request's MCP-Protocol-Version header: a request with no header, or with a version from 2024-11-05 to 2025-11-25, goes to the 2025 handler with its sessions, and anything else goes to the stateless handler (mcp/server/streamable_http_manager.py). The 2025 path keeps its sessions in the memory of the process that made them, so 2025-era clients keep their stickiness requirements (what's new).

We serve the ported server's app as replica a, recorded with chapter 6's lib.wire.record_http, and a second copy of it as replica b. A client in the default mode and a client in mode="legacy", which speaks the 2025 handshake, each quote a refund above the policy's limit and issue it on replica a, with the scripted lead saying yes. Then we send the 2025 client's session ID to each replica.

serve-two-revisions.py Python 3.12.15 · cryptography 50.0.2 · httpx2 2.16.2 · jsonschema 4.26.0 · mcp 2.3.0 · mcp-types 2.3.0 · pydantic 2.14.3 · starlette 1.10.0 · uvicorn 0.54.0 Superado
"""Serves the ported refund confirmation from one app to a 2026-07-28 client and a 2025-11-25 client, then sends the 2025client's session ID to a second replica. The prose's point rests on the two "question came as" lines (one resolver, twoforms), the two refund lines, and the two session lines: the replica that made the session answers, and the other returns a 404."""import asyncioimport osimport httpx2from mcp import Clientfrom lib import confirmations, http_mcp, loopback, shop_api, wireLEGACY = {"MCP-Protocol-Version": "2025-11-25", "Accept": "application/json, text/event-stream"}   # a 2025 version routes to the 2025 handlerdef asked_how(exchanges: list[dict]) -> str:    messages = [m for e in exchanges for m in e["messages"]]    if any(m.get("method") == "elicitation/create" for m in messages):        return "a request the server pushed mid-call"    return "an input request in a result" if any(m.get("result", {}).get("resultType") == "input_required"                                                 for m in messages) else "never"async def main() -> None:    server = http_mcp.load_server("replace-pushed-requests.py")     # the ported issue_refund, with its resolver    with loopback.serve(shop_api.create_app()) as api_url:        os.environ.update(shop_api.server_env(api_url))        with loopback.serve(wire.record_http(server.streamable_http_app(), "a.jsonl")) as a, \             loopback.serve(http_mcp.load_server("replace-pushed-requests.py").streamable_http_app()) as b:            for mode, order in (("auto", "O-2289"), ("legacy", "O-1085")):     # both above the policy limit                seen = len(wire.read_http_trace("a.jsonl"))   # this client's exchanges come after this count                async with Client(a + "/mcp", mode=mode, elicitation_callback=confirmations.say_yes) as client:                    quote = (await client.call_tool("quote_refund", {"order_id": order})).structured_content                    refund = await client.call_tool("issue_refund", {"quote_id": quote["quote_id"]})                    # the first response from this client that set a session ID                    session = next((e["response_headers"]["mcp-session-id"] for e in wire.read_http_trace("a.jsonl")                                    [seen:] if "mcp-session-id" in e["response_headers"]), None)                    print(f"{mode} revision:", client.protocol_version)                    print(f"{mode} session header:", "set" if session else "none")                    for replica, url in (("a", a), ("b", b)) if session else ():   # no session, nothing to send                        sent = httpx2.post(url + "/mcp", headers={"Mcp-Session-Id": session, **LEGACY},                                           json={"jsonrpc": "2.0", "id": 9, "method": "tools/list"})                        listed = "tools listed" if "check_stock" in sent.text else sent.json()["error"]["message"]                        print(f"2025 session on replica {replica}: HTTP {sent.status_code},", listed)                print(f"{mode} question came as:", asked_how(wire.read_http_trace("a.jsonl")[seen:]))  # this client's exchanges, as replica a logged them                print(f"{mode} refund:", refund.structured_content["status"])asyncio.run(main())
Salidapython serve-two-revisions.py
auto revision: 2026-07-28
auto session header: none
auto question came as: an input request in a result
auto refund: requested
legacy revision: 2025-11-25
legacy session header: set
2025 session on replica a: HTTP 200, tools listed
2025 session on replica b: HTTP 404, Session not found
legacy question came as: a request the server pushed mid-call
legacy refund: requested

The default client settled on 2026-07-28, got no session header (none), and its question came as an input request in a result. Its refund ended requested.

The 2025 client settled on 2025-11-25, got a session header (set), and its question came as a request the server pushed mid-call. Its refund ended requested, and so did the default client's.

One resolver served both eras, and no code in issue_refund checks which one it is in. That is simpler than the ctx.protocol_version check around ctx.elicit() that See why a stateless server can't wait for an answer allows. A hand-built input request, like chapter 5's, doesn't serve both: a 2025 client receives it as an invalid result (What goes wrong in production in chapter 5).

The 2025 session worked on replica a, which answered HTTP 200, tools listed, and failed on replica b, which answered HTTP 404, Session not found. A 2026 client has no session to lose. What it needs from replicas is handles they all reach, as Run replicas without sticky sessions showed. Behind a load balancer, then, 2025-era traffic needs routing by Mcp-Session-Id to the replica that made the session, while the rest goes anywhere. The SDK's other choice, stateless_http=True, removes the sessions for 2025 clients but takes away their cancellation and their server-to-client requests (What goes wrong in production in chapter 6). For the shop that would break the pushed confirmation that the 2025 client had answered, so we recommend sticky routing for the 2025 path, kept as small as the remaining clients allow.

Working rule: Serve both eras from one streamable_http_app() through the window, write every question a tool asks as a resolver, and route requests that carry Mcp-Session-Id to the replica that minted it. Count requests by era. When the 2025 count has stayed at zero for as long as your slowest host takes to upgrade, serve the pinned revision only, and answer initialize with an error that names the versions you support, as the specification asks.

Qué sale mal en producción

Último cambio en la edición 2026.11.11

Una migración falla en los huecos entre las dos eras: un cliente ve el servidor antiguo, un proxy ve el nuevo y una advertencia no dice nada. Estos son los fallos que conviene vigilar.

Una sesión de 2025 llega a otra réplica. La señal es 404 con "Session not found" solo en clientes de la era 2025, después de un despliegue o de un escalado, como en la réplica b de Sirve a clientes antiguos y nuevos durante la transición. Un cliente de 2025 que sigue su revisión inicia una sesión nueva al recibir un 404 (transportes de 2025-11-25), así que el síntoma puede ser estado perdido y no un error. Enruta por Mcp-Session-Id y cuenta los 404 por cliente.

Un proxy descarta la cabecera de versión. La aplicación del SDK elige la era solo a partir de MCP-Protocol-Version, y su código fuente indica que el enrutamiento por el cuerpo es un paso posterior (mcp/server/streamable_http_manager.py). Un proxy que elimina las cabeceras que no reconoce envía una request de la era 2026 por la ruta de 2025, que espera primero un handshake. La señal son fallos de clientes con la revisión fijada que solo pasan por ese proxy. Haz que todos los proxies reenvíen las cabeceras de MCP, como enumera Lee un intercambio HTTP.

Los códigos de error cambiaron. Un recurso que falta es -32602 en la revisión fijada, no -32002, aunque los clientes DEBERÍAN seguir aceptando -32002 (recursos). La revisión añade -32020 para cabeceras que no coinciden con el cuerpo, -32021 para una capacidad de cliente ausente y -32022 para una versión de protocolo no soportada (registro de cambios). Un host que se ramifica según los códigos antiguos trata los códigos que añade la revisión fijada como desconocidos. Busca en el código del cliente cada código numérico antes de que el servidor cambie.

Advertencias que enseñan a ignorar las advertencias. MCPDeprecationWarning es un UserWarning, así que se imprime por defecto (novedades), y un servidor que todavía usa sampling, roots o logging la escribe en sus registros. Desactivarla en bloque también oculta la siguiente deprecación. Filtra cada advertencia solo por su mensaje, una vez que la funcionalidad esté en tu inventario con una fecha.

Silencio sobre HTTP+SSE y el registro. El SDK en 2.3.0 no advierte sobre ninguno de los dos, como encontró el inventario. Un servidor puede superar sus pruebas sin advertencias y aun así perder a sus hosts más antiguos cuando el transporte desaparezca. Mantén en CI el escaneo de Inventaria de qué depende el servidor antiguo, y trata una versión posterior del SDK que añada estas advertencias como un motivo para revisar las fechas.

Leer la eliminación más temprana como la fecha final. Un equipo que planea dejar sampling o roots el 2027-07-28 no tiene margen, porque la primera revisión publicada en esa fecha o después podría eliminarlos. Un equipo que interpreta la fecha como el día en que desaparecen también puede retirar una funcionalidad que su SDK sigue soportando durante más tiempo. Planifica según los clientes a los que sirves: el registro da la fecha más temprana, y tus registros dan la real.

Regla práctica: Demuestra que el port funciona a través de la ruta real del proxy antes de que reciba tráfico, con cuatro pruebas: un cliente de 2025 completa una confirmación, un cliente de 2026 completa la misma, una sesión de 2025 sobrevive a un despliegue y la cabecera de versión llega al servidor. Después vigila las requests por era, los 404 por cliente y cada advertencia de deprecación, hasta que el recuento de 2025 llegue a cero.

Decisiones que tomó este capítulo

  • El servidor de la era 2025 es un listado, no un ejemplo en ejecución. lib.legacy lo conserva como texto para el SDK 1.x, y los ejemplos solo ejecutan el port a la 2.x, porque un mismo entorno no puede alojar ambas versiones.
  • El inventario clasifica las dependencias en eliminadas, obsoletas y cambios del SDK, con la fecha de eliminación más temprana del registro para cada función obsoleta, leída como la fecha más temprana y nunca como fecha de fin.
  • El análisis se ejecuta en CI a lo largo de la ventana, porque el SDK advierte sobre el muestreo, las raíces y el registro, pero no sobre HTTP+SSE ni sobre el registro de clientes.
  • El estado por sesión se convierte en identificadores: la cotización es el quote_id del capítulo 3, que el cliente devuelve y que se almacena donde todas las réplicas lo leen.
  • HTTP+SSE se elimina. El servidor de la tienda sirve solo Streamable HTTP y mantiene los endpoints antiguos únicamente mientras sus registros muestren que algún host los usa.
  • La elicitación pasa a un resolvedor, que sirve a ambas eras. El muestreo se elimina: el modelo del host clasifica los tickets. Las raíces se convierten en el parámetro export_dir, validado contra SHOP_EXPORT_DIRS. El registro se envía a stderr y a las trazas.
  • El host usa un Client ID Metadata Document mediante client_metadata_url, y los servidores de autorización mantienen el registro solo para los hosts que no pueden publicarlo.
  • El paso a la 2.x es un único cambio, protegido por mcp<2 hasta que pasen sus pruebas, con instructions= por palabra clave y la configuración de transporte en run().
  • Una aplicación de doble era atiende a ambas eras durante la ventana de transición, con enrutamiento persistente por Mcp-Session-Id para el tráfico de 2025 y sin stateless_http.

Este capítulo, en esta edición

Edición 2026.11.14Ejemplos verificados el 19 de nov de 2026Superan la prueba 6 de 6 ejemplos ejemplos de este capítulo

Traducido del libro en inglés, edición 2026.11.14.

Cita esta sección

Formato

Cada formato cita el libro en inglés, que esta traducción sigue.

Cada formato nombra esta edición. Su enlace abre la edición actual, donde el encabezado de cada sección indica cuándo cambió su texto por última vez. Las fechas de acceso y de recuperación son el día en que lo abres.

En esta página

Capítulo 12 de 12: Migrar un servidor de la era 2025

  1. Inventory what the old server depends on
  2. Eliminar initialize y los ID de sesión
  3. Pasar de HTTP+SSE a Streamable HTTP
  4. Reemplazar sampling, roots y logging
  5. Reemplazar el registro dinámico de clientes
  6. Porta el código de la SDK 1.x a la 2.x
  7. Serve old and new clients through the window
  8. Qué sale mal en producción
  9. Decisiones que tomó este capítulo

Volver arribaTodos los capítulos