Prueba un servidor y observa cómo se ejecuta
Unos 33 minutos de lectura, con 6 ejemplos en 8 secciones.
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
En esta página
- Prueba las herramientas en memoria
- Revisa los esquemas como un contrato
- Reproducir ejecuciones registradas del host
- Traza las llamadas con OpenTelemetry
- Mide con qué frecuencia se elige la herramienta correcta
- Cambia herramientas sin romper clientes
- Qué sale mal en producción
- Decisiones que tomó este capítulo
Al final de este capítulo podrás probar las herramientas de un servidor del Model Context Protocol en memoria y por HTTP, detectar un cambio de esquema que rompería a los clientes antes de publicarlo, reproducir una ejecución grabada del host como prueba de regresión, trazar las llamadas a herramientas con OpenTelemetry, medir con qué frecuencia el modelo elige la herramienta correcta y retirar una herramienta sin romper a los clientes que la usan. Las afirmaciones sobre el protocolo se cumplen para la revisión 2026-07-28 de la especificación, y las afirmaciones sobre el SDK corresponden al SDK de Python, mcp 2.3.0.
Construye un host que trabaja con tickets terminó con el host que usa el equipo de soporte de la tienda, lib.ticket_host, que atiende los 48 tickets de la tienda usando dos servidores, el de la tienda y el de seguimiento de paquetes del socio, con las respuestas del modelo tomadas de la grabación ticket-runs. Una grabación es una salida guardada del modelo en examples/data/recorded/, de modo que la ejecución se reproduce igual en cualquier máquina sin llamar al modelo.
Esa ejecución dejó dos problemas. El host eligió la herramienta inicial correcta para 36 of 48 tickets, pero nada indicaba cuáles había errado ni por qué. En los tickets de reembolso, el modelo escribía a los clientes como si sus reembolsos ya estuvieran hechos, mientras que solo 0 of 7 de los tickets que pedían reembolso llegaron a issue_refund. El servidor y el host de la tienda cambian constantemente: se reescribe una descripción, se renombra un campo, se reemplaza una herramienta. Cualquiera de esos cambios puede romper a un cliente sin que falle ni una sola llamada del lado del servidor.
Para construir controles sobre ellos, un equipo obtiene varias cosas del Model Context Protocol (MCP): esquemas tipados para cada herramienta, contexto de traza en el _meta de cada solicitud y notificaciones de cambio para la lista de herramientas. Este capítulo construye los controles de la tienda sobre esas bases. Tres módulos nuevos contienen la configuración. lib.testing ejecuta un módulo de pytest e imprime una línea estable por prueba. lib.contract compara dos versiones de los esquemas de una herramienta. lib.queue_replay reproduce la ejecución de la cola del capítulo 10 y verifica lo que promete cada respuesta frente a las llamadas que hizo el host. Dos de los ejemplos de este capítulo reproducen la grabación ticket-runs; los demás no usan ningún modelo, y el capítulo no hace llamadas propias a ningún modelo.
Prueba las herramientas en memoria
Una prueba de las herramientas de un servidor debe ejecutarse sin puerto y sin subproceso, para poder correr en cada cambio. El Client del SDK de Python te lo permite: si le pasas un objeto de servidor en lugar de una URL o de parámetros de lanzamiento, se conecta al servidor dentro del mismo proceso. La guía de pruebas del SDK lo presenta como la forma de probar un servidor, con la línea "No subprocess. No port. Nothing on a wire" (testing). En la mode="auto" predeterminada, la conexión es un par de objetos DirectDispatcher, que entregan cada solicitud al manejador del servidor como un objeto de Python, sin flujos, sin el encuadre JSON-RPC y sin el intercambio de inicialización (handshake) (mcp/client/client.py, _connect_inproc; mcp/shared/direct_dispatcher.py).
Hay dos detalles que importan en una prueba. raise_exceptions=True hace que un fallo fuera del cuerpo de una herramienta, como un error en un manejador, llegue con su mensaje real en lugar de un "Internal server error" saneado. No cambia lo que hace la excepción propia de una herramienta: eso sigue siendo un resultado con is_error=True, como con cualquier cliente (testing). Además, el SDK imprime con un sello la identidad del servidor en el _meta de cada resultado, así que una prueba que compara resultados completos debe borrar antes result.meta (misma página). Hacer aserciones sobre los campos que interesan a la prueba evita tanto ese sello como la biblioteca de instantáneas (snapshots) de la guía del SDK, inline-snapshot, que el libro no fija. Las pruebas asíncronas no necesitan ningún plugin extra: anyio, del que depende el SDK, incluye un plugin de pytest que ejecuta cualquier prueba marcada con pytest.mark.anyio (AnyIO testing).
Lo que la ruta en memoria omite importa tanto como lo que cubre. Sin capa HTTP, una prueba en memoria nunca se encuentra con las comprobaciones que un servidor Streamable HTTP hace sobre las cabeceras, Origin y Host, nunca ve un evento enviado por el servidor y nunca transporta contexto de traza, como muestra Trace calls with OpenTelemetry. La documentación del SDK añade que la ruta en proceso no entrega notificaciones independientes, como un cambio en la lista de herramientas (client caching). Una suite completamente en memoria puede pasar mientras todos los clientes HTTP fallan.
Las pruebas de la tienda se ejecutan contra el servidor del capítulo 3, lib.shop_tools, de Design tools a model can use, con la API de la tienda en loopback para cada prueba, servida por el fixture shop_api_env de lib.testing. Tres pruebas se ejecutan en memoria: el estado de un pedido llega como campos estructurados, un pedido desconocido llega como un tool execution error que menciona find_orders, y un ID de pedido con un formato incorrecto se rechaza antes de que se ejecute la herramienta. La cuarta sirve las mismas herramientas por Streamable HTTP en loopback y envía un tools/call cuyo encabezado Mcp-Name nombra una herramienta distinta de la de su cuerpo: una solicitud que el cliente del SDK nunca envía y que un cliente en memoria no puede expresar. Ejecutado como script, el archivo ejecuta sus propias pruebas con pytest 9.2.0.
1"""Four pytest tests of the shop's tools: three through the SDK's in-process client, and one over Streamable HTTP on2loopback, which reaches a check an in-memory test never makes. The prose's point rests on the unknown-order test's3line and on the last line, which counts the passes."""4import pytest5from mcp import Client67from lib import http_mcp, loopback, shop_tools8from lib.testing import anyio_backend, run, shop_api_env910pytestmark = pytest.mark.anyio # runs the async tests on anyio's pytest plugin111213async def test_order_status_fields(shop_api_env): # shop_api_env serves the shop's API on loopback for this test14 # raise_exceptions=True: a bug outside a tool's body raises here, with its own message15 async with Client(shop_tools.create_server(), raise_exceptions=True) as client:16 result = await client.call_tool("get_order_status", {"order_id": "O-1873"})17 assert not result.is_error18 assert result.structured_content["order_id"] == "O-1873"19 assert result.structured_content["status"] == "delivered"202122async def test_unknown_order_is_a_tool_error(shop_api_env):23 async with Client(shop_tools.create_server(), raise_exceptions=True) as client:24 result = await client.call_tool("quote_refund", {"order_id": "O-7144"})25 assert result.is_error # raise_exceptions doesn't make it raise26 assert "find_orders" in result.content[0].text # the model is told what to do instead272829async def test_malformed_order_id_is_refused(shop_api_env):30 async with Client(shop_tools.create_server(), raise_exceptions=True) as client:31 result = await client.call_tool("get_order_status", {"order_id": "1873"})32 assert result.is_error33 text = result.content[0].text # only argument validation writes this error:34 assert "order_id" in text and "string_pattern_mismatch" in text # the field and pydantic's pattern check353637def test_http_refuses_a_mismatched_header(shop_api_env):38 with loopback.serve(shop_tools.create_server().streamable_http_app()) as base_url:39 # the header names check_stock while the body calls get_order_status: the mismatch the server must refuse40 reply = http_mcp.post(base_url + "/mcp", "tools/call", {"name": "get_order_status",41 "arguments": {"order_id": "O-1873"}}, headers={"Mcp-Name": "check_stock"})42 assert reply.status_code == 40043 assert reply.json()["error"]["code"] == -32020 # the JSON-RPC code the server returns for the mismatch444546if __name__ == "__main__":47 run(__file__)
python test-tools-in-memory.pytest_order_status_fields: passed
test_unknown_order_is_a_tool_error: passed
test_malformed_order_id_is_refused: passed
test_http_refuses_a_mismatched_header: passed
tests passed: 4 of 4
Una herramienta que falla es un resultado sobre el que un modelo puede actuar. La ejecución informa 4 of 4, y la prueba del pedido desconocido passed con raise_exceptions=True activado: la herramienta lanzó ToolError, y el cliente recibió un resultado ordinario con la marca de error activada y el consejo del servidor en su texto, que es lo que un modelo necesita para corregirse (Report failures as tool results).
El ID mal formado nunca llegó a la herramienta. La prueba afirma que el error menciona order_id y string_pattern_mismatch de pydantic, que solo escribe la validación de argumentos. El SDK validó los argumentos contra el modelo de parámetros de la herramienta, del que se genera su esquema de entrada, antes de llamar a la herramienta (mcp/server/mcpserver/server.py, _handle_call_tool). La prueba HTTP cubre la capa que las otras omiten: el servidor rechazó la cabecera no coincidente con estado 400 y el error JSON-RPC -32020, como describe Read one HTTP exchange, antes de que se ejecutara cualquier código de la herramienta.
Regla práctica: Prueba cada herramienta en memoria con Client(server, raise_exceptions=True), y afirma sobre los campos structured_content y sobre is_error, no sobre resultados completos. Mantén al menos una prueba por cada transporte que distribuyas que pase por él en loopback, para las comprobaciones de cabecera, origen y streaming que una prueba en memoria no alcanza, y pon ahí también las pruebas de propagación de trazas y de cambios en la lista.
Revisa los esquemas como un contrato
Las pruebas en memoria de la sección anterior comprueban que una herramienta hace lo que dice su propia versión. No comprueban que la nueva versión siga siendo compatible con los clientes que usan la anterior. Un cliente depende de una herramienta a través de sus esquemas: envía argumentos que su copia de inputSchema acepta, y lee los campos que su copia de outputSchema promete. Cuando una herramienta declara un esquema de salida, el servidor DEBE devolver contenido estructurado que se ajuste a él, y los clientes DEBERÍAN validarlo (tools, "Structured Content").
El cliente del SDK de Python sí valida, y lo hace contra su propia copia. Mantiene un validador compilado por herramienta, construido a partir del esquema de salida de la última tools/list que incorporó, y solo lo reemplaza cuando un listado posterior trae un esquema distinto (mcp/client/session.py, _output_schema_validator y _absorb_tool_listing). Un resultado sin error que no coincide genera RuntimeError en quien hizo la llamada (mcp/client/session.py, validate_tool_result). Así, un servidor que renombra un campo de salida rompe a cada cliente conectado que listó sus herramientas antes de la nueva versión, en el momento en que cada uno vuelve a llamar a la herramienta, y el servidor no detecta nada anormal.
En el caso de la tienda, la versión 2 del servidor renombra el campo on_hand por almacén de check_stock a count. Para ver la rotura, un cliente se conecta en memoria a la versión 1 y lista las herramientas. Mantiene su conexión mientras el servidor cambia check_stock por la versión 2, como haría un despliegue gradual. Después, el cliente llama a la herramienta, vuelve a listarla y la llama de nuevo. Por último, una prueba de contrato ejecuta las dos comprobaciones que se hacen antes de publicar una versión: lib.contract.breaking_changes, una comparación de los esquemas de ambas versiones, y una validación del resultado real de la versión 2 contra el esquema de salida publicado de la versión 1 con jsonschema, la biblioteca que usa el cliente.
1"""What a client connected before a release sees when the release renames check_stock's on_hand to count, and what2the contract checks report about the same change. The prose's point rests on the client's error line, which names3the missing field, and on the contract check's line."""4import asyncio56from mcp import Client7from pydantic import BaseModel89from lib import confirmations, contract, shop_tools10from lib.testing import shop_api_here111213class Warehouse(BaseModel):14 warehouse: str15 count: int # release 1 called it on_hand16 last_counted: str171819class StockReport(BaseModel):20 sku: str21 available: int22 warehouses: list[Warehouse]232425def check_stock(sku: shop_tools.Sku) -> StockReport:26 report = confirmations.chapter3_tools()["check_stock"].fn(sku) # release 1's tool does the reading27 return StockReport(sku=sku, available=report.available, warehouses=[Warehouse(28 warehouse=w.warehouse, count=w.on_hand, last_counted=str(w.last_counted)) for w in report.warehouses])293031async def main() -> None:32 server = shop_tools.create_server()33 with shop_api_here(): # the server's tools run in this process34 async with Client(server) as client:35 listing = await client.list_tools()36 print("release 1's tools/list cache hint:", f"ttlMs {listing.ttl_ms}")37 server.remove_tool("check_stock") # the release, swapped in while connected38 server.add_tool(check_stock, description=shop_tools.DESCRIPTIONS["check_stock"])39 try:40 await client.call_tool("check_stock", {"sku": "KG-1031"})41 except RuntimeError as error:42 print("client that listed before the release:", error.args[0].splitlines()[0]) # the message's first line43 new = next(tool for tool in (await client.list_tools()).tools if tool.name == "check_stock") # the release 2 schema44 result = await client.call_tool("check_stock", {"sku": "KG-1031"})45 print("client after listing again:", "result" if not result.is_error else "tool error")46 old = next(tool for tool in listing.tools if tool.name == "check_stock")47 print("contract check:", "; ".join(contract.breaking_changes(old, new)) or "no breaking change")48 validator = contract.validator(old.output_schema)(old.output_schema) # by the dialect the schema declares49 print("validator for release 1's schema:", type(validator).__name__ + ", as it declares",50 old.output_schema.get("$schema", "no $schema"))51 # the first error the schema finds in release 2's real result52 print("release 2's result against release 1's schema:", next(validator.iter_errors(result.structured_content)).message)535455asyncio.run(main())
python schema-change-breaks-a-client.pyrelease 1's tools/list cache hint: ttlMs 0
client that listed before the release: Invalid structured content returned by tool check_stock: 'on_hand' is a required property
client after listing again: result
contract check: output warehouses[].on_hand: removed
validator for release 1's schema: Draft202012Validator, as it declares no $schema
release 2's result against release 1's schema: 'on_hand' is a required property
La lista de herramientas de la versión 1 llevaba la pista de caché predeterminada del SDK, ttlMs 0, así que la lista quedaba obsoleta en cuanto llegaba, y el cliente seguía validando contra ella. La llamada posterior a la publicación falló dentro del cliente: "Invalid structured content returned by tool check_stock: 'on_hand' is a required property". El servidor había devuelto un resultado correcto de la versión 2. Cuando el cliente volvió a listar las herramientas, la misma llamada devolvió un result. Un TTL de cero no protege a un cliente conectado, porque el validador sigue el último listado y no la caché: un cliente que lista una vez al arrancar mantiene ese esquema mientras se ejecuta.
Ambas comprobaciones de contrato detectaron el cambio sin necesidad de un cliente. La comparación de esquemas informó de output warehouses[].on_hand: removed, y validar el resultado de la versión 2 contra el esquema de la versión 1 falló con el mensaje propio del cliente: "'on_hand' is a required property". La comparación es una ayuda para quien revisa: compara rutas de campos, tipos y entradas requeridas, y su docstring indica lo que deja fuera, como los patrones y los enums. La validación es la prueba que conviene conservar, porque comprueba la salida real del servidor contra el esquema exacto que tienen los clientes.
Los cambios que rompen compatibilidad no son simétricos. En la salida, eliminar, renombrar o cambiar el tipo de un campo rompe a los clientes, y añadir un campo opcional no. En la entrada, añadir un argumento requerido rompe a los llamadores antiguos, y eliminar uno los rompe en silencio, porque el servidor del SDK descarta sin error los argumentos que no reconoce, como muestra Treat ticket text as untrusted data. La revisión fijada permite cualquier palabra clave de JSON Schema 2020-12 en ambos esquemas, y lee como 2020-12 un esquema sin $schema (tools). Un esquema puede nombrar otro dialecto en $schema, y los clientes y servidores DEBEN validar según el dialecto declarado, o según 2020-12 cuando no se declara ninguno (base protocol, "JSON Schema Usage"). Por eso conviene elegir el validador a partir del esquema, como hace el cliente del SDK con jsonschema y su validator_for (mcp/client/session.py, _output_schema_validator). lib.contract.validator hace lo mismo en las comprobaciones de la tienda, con 2020-12 como valor predeterminado. pydantic no escribe $schema, así que el esquema de la versión 1 recibió Draft202012Validator, as it declares no $schema.
Regla práctica: Guarda en el repositorio la respuesta de tools/list de la última versión y, en CI, valida cada resultado estructurado que produzcan tus pruebas tanto contra el esquema nuevo como contra ese, cada uno según el dialecto que declare y según 2020-12 cuando no declare ninguno. Trata un campo de salida eliminado, renombrado o con otro tipo, y una nueva entrada requerida, como un cambio que rompe compatibilidad: añade el campo nuevo junto al antiguo, o añade una herramienta nueva, y retira la forma antigua mediante un periodo de transición (Change tools without breaking clients). No confíes en un TTL corto para proteger a los clientes que ya están conectados.
Reproducir ejecuciones registradas del host
Las pruebas de herramientas y las pruebas de contrato cubren el servidor. El host de soporte de Construye un host que trabaja con tickets tiene una lógica propia entre el modelo y los servidores: enruta nombres, pide consentimiento, devuelve resultados y limita los turnos, y un cambio ahí puede hacer que cada ticket salga mal sin que falle ninguna herramienta. Una reproducción cubre esa capa. Ejecuta el host real contra los servidores reales, con las respuestas del modelo tomadas de una grabación, de modo que una prueba pueda afirmar qué hizo el host con cada ticket.
Una reproducción prueba el host y los servidores frente a salidas fijas del modelo. No prueba el modelo: un modelo distinto, o el mismo con otro muestreo, necesita una nueva grabación. Y solo se sostiene mientras los mensajes sigan como se grabaron. ReplayModel de lib.host busca cada respuesta por el SHA-256 de los mensajes exactos, que incluyen cada definición de herramienta y cada resultado de herramienta hasta ese momento, y lanza RecordingMismatch cuando difieren (Ejecuta el bucle del host). Así, una reproducción funciona también como un cable trampa: cualquier cambio en lo que vería el modelo la detiene, y un equipo decide entonces si graba de nuevo.
La reproducción también ofrece una segunda lectura de los resultados de la cola. Trabaja la cola de tickets descubrió que el modelo decía a los clientes que sus reembolsos estaban en camino por pedidos que nunca reembolsó. Una respuesta es la afirmación del modelo, y el registro de llamadas del host es el registro de lo que ocurrió, de modo que el host puede compararlos antes de que una respuesta llegue a un cliente. lib.queue_replay contiene una versión pequeña de esa comprobación, construida sobre la comprobación de frases con la que contó el capítulo 10, ticket_host.promises_refund, que busca frases como "will be refunded" o "we'll refund". Reutilizarla mantiene iguales los recuentos de este capítulo y los del capítulo 10, es decir, la misma medición. Su unbacked_refund es verdadero cuando la última respuesta de una ejecución hace esa promesa y ninguna llamada issue_refund de la ejecución devolvió un resultado. La lista de frases es una regla práctica escrita contra las respuestas de esta grabación, no un clasificador, y la documentación del módulo indica lo que se le escapa.
queue_replay.replay_queue reproduce toda la cola, con el host de soporte configurado exactamente como lo configura work-the-ticket-queue del capítulo 10. La ejecución imprime la secuencia de herramientas de un ticket, cuenta los reembolsos y las respuestas que prometen uno, y reproduce el primer ticket después de añadir una frase a la descripción de quote_refund.
1"""Replay chapter 10's queue run, the recording ticket-runs, through the support host, and check each reply's promise2against the host's call log. The prose's point rests on the refund lines, which compare refunds issued with replies3that promise one, and on the last line, which shows what a one-sentence rewording does to the replay."""4import asyncio56from lib import queue_replay, shop_tools, ticket_host7from lib.host import RecordingMismatch8from lib.shop_data import load_shop91011def reword_quote_refund(host) -> None: # the server's next release adds a sentence to one description12 changed = {**shop_tools.DESCRIPTIONS}13 changed["quote_refund"] += " Quotes are in the order's currency."14 host.listed["shop"] = shop_tools.with_descriptions(host.listed["shop"], changed)151617async def main() -> None:18 tickets = {ticket.ticket_id: ticket for ticket in load_shop().tickets}19 runs = await queue_replay.replay_queue()20 print("tickets replayed:", len(runs))21 print("T-0009 tools:", " then ".join(turn.tool for turn in runs["T-0009"].calls)) # its calls, in order22 print("refunds issued:", sum(queue_replay.refunded(run) for run in runs.values()))23 # the phrase check from chapter 10, a rule of thumb: see the module's docstring for what it misses24 promised = [ticket_id for ticket_id, run in runs.items() if ticket_host.promises_refund(run.answer)]25 # a promise with no refund behind it: no issue_refund call in the run returned a result26 unbacked = [ticket_id for ticket_id in promised if queue_replay.unbacked_refund(runs[ticket_id])]27 print("replies that promise a refund:", len(promised))28 print("of which no call made:", len(unbacked))29 for tag in ("issue_refund", "quote_refund"): # the tickets tagged with each refund tool30 group = [t for t in tickets.values() if t.expected_tool == tag]31 print(f"{tag} tickets flagged:", f"{sum(t.ticket_id in unbacked for t in group)} of {len(group)}")32 print("flagged:", ", ".join(unbacked))33 try:34 await queue_replay.replay_queue(change=reword_quote_refund, tickets=[tickets["T-0001"]])35 except RecordingMismatch:36 print("after rewording quote_refund, T-0001 replays:", "no, RecordingMismatch")373839asyncio.run(main())
python replay-ticket-runs.pytickets replayed: 48
T-0009 tools: shop.quote_refund then shop.find_orders
refunds issued: 0
replies that promise a refund: 11
of which no call made: 11
issue_refund tickets flagged: 6 of 7
quote_refund tickets flagged: 5 of 9
flagged: T-0007, T-0020, T-0029, T-0034, T-0036, T-0037, T-0040, T-0042, T-0045, T-0046, T-0048
after rewording quote_refund, T-0001 replays: no, RecordingMismatch
Los 48 tickets se reprodujeron todos, y el ticket T-0009 siguió el camino que siguió en el capítulo 10: shop.quote_refund then shop.find_orders. Una afirmación sobre esa secuencia es una prueba de regresión del host. Si un cambio en el enrutamiento o en el manejo de errores devolviera de otra forma el primer error de ejecución de herramienta, el segundo turno del modelo ya no coincidiría con la grabación, y la reproducción se detendría.
lib.queue_replay marca las promesas que ninguna llamada respalda, y un host debería enviar esas respuestas a una persona en lugar de al cliente. El host emitió 0 reembolsos, pero 11 respuestas prometen uno, y 11 de ellas no tienen ningún reembolso detrás.
De los tickets que piden un reembolso, 6 of 7 están marcados, y de los tickets que solo preguntan qué sería un reembolso, 5 of 9 lo están, y en cada una la respuesta decía al cliente que el dinero estaba en camino. La única solicitud de reembolso no marcada, T-0024, terminó con el modelo preguntando qué producto quería decir el cliente, lo que no promete nada. Los tickets marcados son T-0007, T-0020, T-0029, T-0034, T-0036, T-0037, T-0040, T-0042, T-0045, T-0046, T-0048.
La reformulación del final muestra el cable trampa. Después de añadir una frase a una descripción, la reproducción del primer ticket dio no, RecordingMismatch. El prompt de cada ticket contiene la descripción de todas las herramientas, así que cambiar cualquier descripción cambia todos los prompts. Ese es el costo de las reproducciones, y también su utilidad: una descripción reformulada es el cambio que puede alterar lo que elige el modelo, y la reproducción no lo deja pasar sin medirlo.
Regla práctica: Reproduce en CI una ejecución registrada de toda la cola, afirma sobre la secuencia de herramientas de cada ticket y ejecuta una comprobación que compare las promesas de cada respuesta con las llamadas que devolvieron un resultado. Mantén fijos los IDs generados y los relojes en los servidores contra los que se ejecuta una reproducción, o se detendrá por razones que no son cambios. Luego trata RecordingMismatch como una señal, no como una prueba inestable: cuando cambies una descripción, un prompt o la salida de una herramienta, graba de nuevo con el script de grabación y compara las puntuaciones de la nueva ejecución con las de la anterior antes de publicar.
Traza las llamadas con OpenTelemetry
Las pruebas se ejecutan antes de una versión; las trazas muestran lo que hace un servidor después. OpenTelemetry es la forma habitual de obtenerlas: una aplicación crea spans, cada uno una operación con nombre y duración, con atributos y un padre, y un exportador los envía a un backend de trazado. MCP añade una cosa propia. En la revisión fijada, las claves _meta, traceparent, tracestate y baggage están reservadas para el contexto de traza, y sus valores DEBEN seguir los formatos W3C Trace Context y Baggage (protocolo base). Así la traza de un cliente y la de un servidor se unen en una sola, sea cual sea el transporte.
El SDK de Python traza sin configuración en el código de tu servidor. Cada servidor instala OpenTelemetryMiddleware, que envuelve cada mensaje entrante en un span SERVER y no hace nada hasta que se instalan un SDK de OpenTelemetry y un exportador (mcp/server/lowlevel/server.py; OpenTelemetry). El código fuente marca el middleware como provisional, así que sus detalles pueden cambiar en una versión menor 2.x. En el lado del cliente, las rutas JSON-RPC, que son URL, stdio y el modo en memoria heredado, abren un span CLIENT llamado MCP send {method} {target} e inyectan traceparent en el _meta de la petición, y el servidor lo extrae como padre de su span (mcp/shared/jsonrpc_dispatcher.py, mcp/shared/_otel.py). La ruta en proceso de Prueba herramientas en memoria no envía JSON-RPC, así que no crea span de cliente ni inyecta nada.
La tienda quiere una traza por cada llamada a una herramienta, localizable por nombre de herramienta y que muestre si falló. El script instala el SDK de OpenTelemetry, opentelemetry-sdk 1.45.2, con un InMemorySpanExporter, que guarda los spans terminados en una lista que una prueba puede leer (opentelemetry/sdk/trace/export/in_memory_span_exporter.py). El script sirve las herramientas del capítulo 3 de Diseña herramientas que un modelo puede usar sobre Streamable HTTP en loopback dentro del mismo proceso, de modo que los spans del cliente y del servidor caen en la misma lista. Llama a find_orders y luego a quote_refund para un pedido que no existe. Después hace dos veces la misma llamada find_orders en memoria, la segunda dentro de un span propio de la prueba.
1"""The OpenTelemetry spans the SDK emits for the shop's tool calls, over Streamable HTTP on loopback and in memory.2The prose's point rests on two printed lines: the HTTP server span, which shows the trace context crossing the wire,3and the in-memory server span parents, which show what happens without it."""4import asyncio56from mcp import Client7from opentelemetry import trace8from opentelemetry.sdk.trace import TracerProvider9from opentelemetry.sdk.trace.export import SimpleSpanProcessor10from opentelemetry.sdk.trace.export.in_memory_span_exporter import InMemorySpanExporter11from opentelemetry.semconv._incubating.attributes.mcp_attributes import McpMethodNameValues1213from lib import loopback, shop_tools14from lib.testing import shop_api_here1516spans = InMemorySpanExporter()17trace.set_tracer_provider(provider := TracerProvider())18provider.add_span_processor(SimpleSpanProcessor(spans)) # each span, as it ends, into memory192021def finished(name: str) -> list: # every finished span with this name, in the order they ended22 return [span for span in spans.get_finished_spans() if span.name == name]232425def parent(span) -> str:26 return next((s.name for s in spans.get_finished_spans() if span.parent and s.context.span_id ==27 span.parent.span_id), "none") # "none" for a span with no parent, or whose parent never finished282930async def main() -> None:31 server = shop_tools.create_server()32 with shop_api_here(), loopback.serve(server.streamable_http_app()) as base_url:33 async with Client(base_url + "/mcp") as client:34 await client.call_tool("find_orders", {"customer_id": "C-0127"})35 await client.call_tool("quote_refund", {"order_id": "O-7144"}) # a tool error36 print("HTTP spans:", ", ".join(sorted(span.name for span in spans.get_finished_spans())))37 # the test makes one call of each, so the first finished span of each name is the call's38 call, error = finished("tools/call find_orders")[0], finished("tools/call quote_refund")[0]39 print("HTTP server span:", call.name, f"({call.kind.name}), parent: {parent(call)}")40 for key in sorted(set(call.attributes) - {"jsonrpc.request.id"}): # the request ID changes on every run41 print(f"attribute {key}:", call.attributes[key])42 print("tool error span status:", error.status.status_code.name)43 print("tool error span error.type:", error.attributes["error.type"])44 spans.clear()45 async with Client(server) as client:46 await client.call_tool("find_orders", {"customer_id": "C-0127"})47 # a span of the test's own, which the in-memory server falls back to as the parent48 with trace.get_tracer("shop-tests").start_as_current_span("test find_orders"):49 await client.call_tool("find_orders", {"customer_id": "C-0127"})50 print("in-memory spans:", ", ".join(sorted(span.name for span in spans.get_finished_spans())))51 print("in-memory server span parents:", ", ".join(parent(s) for s in finished("tools/call find_orders")))52 # the pinned conventions predate the pinned revision, and this list has no server/discover53 assert "server/discover" not in {m.value for m in McpMethodNameValues}545556asyncio.run(main())
python trace-a-tool-call.pyHTTP spans: MCP send server/discover, MCP send tools/call find_orders, MCP send tools/call quote_refund, MCP send tools/list, server/discover, tools/call find_orders, tools/call quote_refund, tools/list
HTTP server span: tools/call find_orders (SERVER), parent: MCP send tools/call find_orders
attribute gen_ai.operation.name: execute_tool
attribute gen_ai.tool.name: find_orders
attribute mcp.method.name: tools/call
attribute mcp.protocol.version: 2026-07-28
tool error span status: ERROR
tool error span error.type: tool_error
in-memory spans: server/discover, test find_orders, tools/call find_orders, tools/call find_orders, tools/list
in-memory server span parents: none, test find_orders
Por HTTP los spans llegaron en parejas, cada span de servidor emparejado con un span de cliente del mismo método: MCP send server/discover, MCP send tools/call find_orders, MCP send tools/call quote_refund, MCP send tools/list, server/discover, tools/call find_orders, tools/call quote_refund, tools/list. El cliente listó las herramientas antes de su primera llamada, porque valida el resultado contra el esquema de salida. La traza muestra el span del servidor para la llamada, tools/call find_orders (SERVER), parent: MCP send tools/call find_orders, así que el contexto de traza cruzó en _meta.
Sus atributos indican el método, tools/call, la operación, execute_tool, la herramienta, find_orders, y la revisión (mcp/server/_otel.py).
El span de la cotización fallida tiene el estado ERROR y el error.type tool_error, aunque la llamada devolvió un resultado y no un error JSON-RPC, así que un backend de trazado puede contar los errores de ejecución de herramientas sin leer los cuerpos de los resultados.
Una prueba de propagación de trazas necesita HTTP o stdio, porque en memoria el servidor no tiene nada que extraer. En memoria no hubo spans de cliente, solo los spans del servidor y el propio de la prueba, test find_orders: server/discover, test find_orders, tools/call find_orders, tools/call find_orders, tools/list. Los padres de los dos spans del servidor fueron none, test find_orders, en ese orden. Como no hay nada que extraer, el servidor recurre al span actual, y solo el span propio de la prueba le dio uno (mcp/shared/_otel.py, extract_trace_context).
Los nombres que emite un servidor son la parte que hay que tratar con cuidado. Las convenciones semánticas de OpenTelemetry para MCP tienen el estado Development; recomiendan nombres de span de la forma {mcp.method.name} {target} y definen métricas como mcp.server.operation.duration (convenciones semánticas de MCP, consultadas el 2026-10-31). También se han trasladado: la página a la que enlaza la especificación de MCP muestra un aviso de que las convenciones de GenAI pasaron a un repositorio propio, que no tiene una versión etiquetada (aviso de traslado). Los spans de servidor del SDK siguen la nomenclatura recomendada. Su nombre de span de cliente, MCP send …, no la sigue, y el SDK no emite métricas: el código fuente de mcp 2.3.0 nunca crea un meter. El paquete de convenciones fijado, opentelemetry-semantic-conventions 0.66b2, es anterior a la revisión fijada. Su lista de nombres de método tiene initialize y logging/setLevel, todavía define mcp.session.id y no tiene server/discover (opentelemetry/semconv/_incubating/attributes/mcp_attributes.py).
Para los registros, la revisión fijada depreca los mensajes de logging propios de MCP, notifications/message, y remite a los servidores a la salida de error estándar en stdio y a OpenTelemetry en los demás casos (registro de cambios). Sustituye sampling, roots y logging explica el cambio.
Regla práctica: Instala un SDK de OpenTelemetry y un exportador en cada servidor y host que ejecutes, y deja que el middleware del SDK genere los spans de servidor. Construye los paneles sobre los atributos que emite el SDK, mcp.method.name, gen_ai.tool.name y error.type, y etiquétalos como siguiendo una convención en estado Development de una versión concreta, porque los nombres pueden cambiar. No valides los nombres de método contra el paquete de convenciones fijado. Prueba la propagación sobre un transporte real, y envuelve las llamadas en memoria en un span propio cuando una prueba necesite un padre.
Mide con qué frecuencia se elige la herramienta correcta
La repetición de Repite las ejecuciones grabadas del anfitrión pregunta si el anfitrión sigue haciendo lo que hacía. Una segunda pregunta es con qué frecuencia el modelo elige bien con las herramientas y descripciones que le da la tienda. La medida habitual para empezar es la precisión en la selección de herramientas: la proporción de casos en los que la primera llamada del modelo usa la herramienta que usaría un agente correcto, a menudo llamada precisión top-1. Los benchmarks también puntúan los argumentos. El Berkeley Function Calling Leaderboard, por ejemplo, comprueba el nombre y los argumentos de cada llamada en conjunto frente a los esperados, comparando sus árboles de sintaxis abstracta (BFCL).
Un número obtenido de una grabación fija mide algo acotado: los nombres y descripciones de las herramientas de la tienda, frente a un modelo, Qwen3-4B-Instruct-2507, cuantizado como Q4_K_M y muestreado con una temperatura de 0.7 (Trabaja la cola de tickets), con el único prompt y la única semilla del libro, sobre los 48 tickets que escribió el libro.
Es una sola muestra de esa configuración, y los grupos son pequeños: el más pequeño tiene 8 tickets, así que un ticket supone una parte grande de su puntuación. No dice nada sobre los modelos en general, y cualquier cambio en una descripción exige una nueva grabación antes de que el número signifique algo, algo que impone el RecordingMismatch de la repetición. Cada ticket lleva la herramienta que un agente correcto llamaría primero. El script puntúa con ticket_host.expected_first_tool, como hace el capítulo 10: una solicitud de reembolso cuenta como correcta cuando empieza por quote_refund, porque issue_refund necesita antes una cotización del reembolso.
Para puntuar la repetición, el script toma la primera llamada a herramienta de cada ticket e imprime la precisión global, por herramienta esperada y para cada confusión. En las llamadas correctas que nombran un pedido, puntúa también el argumento order_id de dos maneras: frente al ID tal como lo escribió el ticket, y frente al pedido que el cliente quería decir. Las dos difieren en los 5 tickets en los que un cliente escribió mal el número.
1"""Score the first tool call of every ticket in chapter 10's queue run against the tool each ticket is tagged with,2overall, per tag and by confusion, and check the order IDs of the right calls. The prose's point rests on the3accuracy lines, the per-tag line for refunds, and the two order-ID lines, which differ."""4import asyncio5from collections import Counter67from lib import queue_replay, ticket_host8from lib.shop_data import load_shop91011async def main() -> None:12 tickets = load_shop().tickets13 runs = await queue_replay.replay_queue()14 scored = [] # (ticket, expected tool, first tool called)15 for ticket in tickets:16 calls = runs[ticket.ticket_id].calls17 # the first call, or None when the host made none; a refund ticket expects quote_refund first18 scored.append((ticket, ticket_host.expected_first_tool(ticket), calls[0] if calls else None))19 right = [(t, call) for t, expected, call in scored if call and call.tool == expected]20 print("first tool right:", f"{len(right)} of {len(scored)}")21 print("top-1 accuracy:", f"{len(right) / len(scored):.2f}")22 for expected, count in sorted(Counter(expected for _, expected, _ in scored).items()):23 hits = sum(1 for t, e, call in scored if e == expected and call and call.tool == expected)24 print(f"expected {expected}:", f"{hits} of {count}")25 confusions = Counter((expected, call.tool if call else "no tool") for _, expected, call in scored26 if not call or call.tool != expected)27 for (expected, chosen), count in confusions.most_common():28 print(f"expected {expected}, called {chosen}:", count)29 with_order = [(t, call) for t, call in right if t.order_id and "order_id" in call.arguments] # right calls naming an order30 as_written = sum(call.arguments["order_id"] == t.cited_order_id for t, call in with_order) # the ID the ticket gave31 meant = sum(call.arguments["order_id"] == t.order_id for t, call in with_order) # the customer's order32 print("right tool, order ID as the ticket wrote it:", f"{as_written} of {len(with_order)}")33 print("right tool, order the customer meant:", f"{meant} of {len(with_order)}")34 # tickets whose cited ID isn't the order the customer meant35 typos = [(t, e, call) for t, e, call in scored if t.cited_order_id and t.cited_order_id != t.order_id]36 print("tickets with a mistyped order ID:", len(typos))37 print("of which the right tool was called:", sum(1 for _, e, call in typos if call and call.tool == e))38 for t, _, call in [(t, e, call) for t, e, call in typos if not call or call.tool != e]:39 print(f"mistyped {t.ticket_id}, first tool:", call.tool if call else "no tool")40 print("smallest expected-tool group, tickets:", min(Counter(e for _, e, _ in scored).values()))41 manifest = queue_replay.manifest()42 print("recorded model:", manifest["model"].split("/")[-1]) # the model's name, without its publisher's path43 print("recorded quantization:", manifest["quantization"])444546asyncio.run(main())
python tool-choice-accuracy.pyfirst tool right: 36 of 48
top-1 accuracy: 0.75
expected shop.check_stock: 10 of 10
expected shop.find_orders: 8 of 8
expected shop.get_order_status: 12 of 14
expected shop.quote_refund: 6 of 16
expected shop.quote_refund, called shop.get_order_status: 8
expected shop.get_order_status, called partner.track_parcel: 2
expected shop.quote_refund, called shop.find_orders: 2
right tool, order ID as the ticket wrote it: 18 of 18
right tool, order the customer meant: 14 of 18
tickets with a mistyped order ID: 5
of which the right tool was called: 4
mistyped T-0042, first tool: shop.get_order_status
smallest expected-tool group, tickets: 8
recorded model: Qwen3-4B-Instruct-2507
recorded quantization: Q4_K_M
La primera herramienta fue correcta en 36 of 48 tickets, una precisión top-1 de 0.75, el mismo 36 of 48 que contó el capítulo 10.
La cifra global oculta dónde están los errores. Las preguntas de stock obtuvieron 10 of 10 y las búsquedas de pedidos 8 of 8, pero los tickets de reembolso solo 6 of 16, y la mayoría de los fallos, 8, fueron a parar a get_order_status, aunque su descripción dice que para un reembolso se use quote_refund, y la de quote_refund dice que hay que llamarla primero. Ese par de descripciones es el siguiente que hay que trabajar, y la cola es el conjunto de tickets que hay que volver a grabar cuando cambien. Las dos preguntas de estado que fueron a parar a partner.track_parcel son el caso del número de seguimiento del capítulo 10 (Trabaja la cola de tickets).
Los argumentos muestran por qué importa la referencia. Con la herramienta correcta, el modelo usó el ID del pedido tal como lo escribió el ticket en 18 of 18 llamadas, y el pedido que el cliente quería decir en 14 of 18 llamadas.
Los fallos son erratas de los clientes. De los tickets con erratas, 4 llegaron a la herramienta correcta y se puntúan aquí; el otro, T-0042, fue primero a shop.get_order_status, así que cuenta entre las herramientas incorrectas. Ningún modelo puede ver a través de una errata sin buscar los pedidos del cliente. Puntuado contra lo que quería el cliente, el modelo parece descuidado; puntuado frente a lo que se le dio, es fiel. La brecha corresponde al flujo del anfitrión, que debería comprobar un pedido frente al cliente del ticket antes de actuar sobre él.
Los benchmarks publicados apuntan en la misma dirección. Un preprint, RAG-MCP, informa de que recuperar una lista corta de herramientas antes de que el modelo elija elevó la precisión de selección del 13.62 % al 43.13 % en sus tareas de benchmark, puntuadas por un modelo que actúa como juez (RAG-MCP). MCP-Bench, sobre 28 servidores en vivo y 250 herramientas, informa de retos persistentes en tareas cuyas instrucciones no nombran la herramienta (MCP-Bench). Cada uno es un único preprint sobre sus propias tareas, y ninguno dice nada sobre las cifras de la tienda.
Regla práctica: Puntúa cada ejecución grabada según la primera herramienta por etiqueta, no solo en conjunto, y puntúa los argumentos por separado: frente a lo que el ticket dio al modelo y frente a la verdad. Trabaja primero las descripciones detrás de la confusión más grande, vuelve a grabar y compara las puntuaciones por etiqueta entre las dos grabaciones. Indica el modelo, el prompt y el conjunto de tickets junto a cada puntuación, y nunca compares puntuaciones de configuraciones distintas.
Cambia herramientas sin romper clientes
El test de contrato de Verifica esquemas como contrato indica cuándo un cambio rompe clientes; no indica cómo hacer el cambio. La especificación tampoco lo hace. Una definición de herramienta no tiene campo de deprecación, y nada en la revisión fijada marca una herramienta como en vías de retirada (herramientas). Lo que sigue es práctica: la recomendación del libro, construida a partir de piezas que la especificación sí define, no una función del protocolo.
Hay tres de esas piezas. Un cliente pide los cambios en la lista de herramientas con subscriptions/listen y recibe aviso de cada uno por ese flujo (suscripciones), como muestra Avisa a los clientes cuando cambie un recurso para recursos. Un resultado de tools/list lleva una pista de caché, ttlMs, y una notificación de cambio invalida una lista en caché que aún está vigente; los clientes PUEDEN (MAY) volver a pedirla antes de tiempo cuando una llamada falle como si la herramienta hubiera cambiado, por ejemplo con un método desconocido o parámetros inválidos (caché). Y un error de ejecución de herramienta es lo que los clientes SHOULD entregar al modelo para que pueda corregirse (herramientas, "Error Handling"). A partir de esas piezas, el libro recomienda este procedimiento: añade la nueva herramienta junto a la antigua; marca la antigua como "Deprecated: use …" en su descripción; anuncia el cambio; reduce el TTL mientras el cambio está en curso; mantén la antigua herramienta funcionando durante una ventana; y, pasada la ventana, respóndela con un error de ejecución que nombre el reemplazo.
La tienda sustituye find_orders por find_orders_v2, que además puede filtrar por SKU. Para recorrer las tres versiones (releases), el script sirve las herramientas del capítulo 3 de Diseña herramientas que un modelo pueda usar por Streamable HTTP en loopback, con un TTL de un minuto en la lista de herramientas, y conecta dos clientes: uno que escucha los cambios de lista y otro que solo usa caché. La versión 2 añade find_orders_v2 y reformula find_orders, y el servidor publica el cambio. La versión 3 reemplaza find_orders por una función que lanza ToolError. Un cliente en memoria no serviría aquí, porque la ruta en proceso no entrega los cambios de lista (Prueba herramientas en memoria).
1"""Retire find_orders in favour of find_orders_v2 over three releases, watched by a listening client and a caching2client. The prose's point rests on the caching client's list and on the last line, the error the old name returns3after the window."""4import asyncio56from mcp import Client7from mcp.server.caching import CacheHint8from mcp.server.mcpserver import MCPServer9from mcp.server.mcpserver.exceptions import ToolError10from mcp.server.subscriptions import InMemorySubscriptionBus, ToolsListChanged1112from lib import confirmations, loopback, shop_tools13from lib.testing import shop_api_here1415bus, tools = InMemorySubscriptionBus(), confirmations.chapter3_tools()16server = MCPServer("shop-support", version="0.11.0", tools=list(tools.values()), subscriptions=bus,17 cache_hints={"tools/list": CacheHint(ttl_ms=60_000, scope="public")}) # a minute: short while a change is under way18old = tools["find_orders"]192021def find_orders_v2(customer_id: shop_tools.CustomerId, sku: shop_tools.Sku | None = None) -> shop_tools.OrderList:22 """Search one customer's orders, newest first, optionally only those with one product's SKU."""23 found = old.fn(customer_id, limit=50)24 return found.model_copy(update={"orders": [o for o in found.orders if sku is None or sku in o.skus]})252627def retired(customer_id: shop_tools.CustomerId) -> shop_tools.OrderList:28 raise ToolError("find_orders was retired. Call find_orders_v2 with the same customer_id.")293031async def replace_find_orders(fn, description: str) -> None:32 server.remove_tool("find_orders")33 server.add_tool(fn, name="find_orders", title=old.title, description=description, annotations=old.annotations)34 await bus.publish(ToolsListChanged()) # to every client listening for list changes353637async def main() -> None:38 with shop_api_here(), loopback.serve(server.streamable_http_app()) as base_url:39 async with Client(base_url + "/mcp") as listening, Client(base_url + "/mcp") as cached:40 listing, _ = await cached.list_tools(), await listening.list_tools() # both cache release 1's list41 print("release 1:", f"{len(listing.tools)} tools, ttlMs {listing.ttl_ms}")42 async with listening.listen(tools_list_changed=True) as changes: # a stream that carries list-change events43 server.add_tool(find_orders_v2) # release 2: the replacement first44 await replace_find_orders(old.fn, "Deprecated: use find_orders_v2. " + old.description)45 print("event:", type(await anext(changes)).__name__)46 print("listening client sees:", ", ".join(t.name for t in (await listening.list_tools()).tools))47 print("cached client sees:", ", ".join(t.name for t in (await cached.list_tools()).tools))48 during = await cached.call_tool("find_orders", {"customer_id": "C-0127"})49 print("find_orders during the window:", "tool error" if during.is_error else "result")50 await replace_find_orders(retired, "Retired: use find_orders_v2.") # release 3: the old name now errors51 after = await cached.call_tool("find_orders", {"customer_id": "C-0127"})52 print("find_orders after the window:", after.content[0].text)535455asyncio.run(main())
python deprecate-a-tool.pyrelease 1: 5 tools, ttlMs 60000
event: ToolsListChanged
listening client sees: get_order_status, quote_refund, issue_refund, check_stock, find_orders_v2, find_orders
cached client sees: find_orders, get_order_status, quote_refund, issue_refund, check_stock
find_orders during the window: result
find_orders after the window: Error executing tool find_orders: find_orders was retired. Call find_orders_v2 with the same customer_id.
La versión 1 listaba 5 tools, ttlMs 60000. Cuando se publicó la versión 2, el cliente que escuchaba recibió ToolsListChanged. El SDK descarta una lista en caché antes de entregar al cliente ese evento (mcp/client/client.py), así que la siguiente lista del cliente que escucha mostró ambas herramientas: get_order_status, quote_refund, issue_refund, check_stock, find_orders_v2, find_orders.
El cliente que usa caché no oyó nada y sirvió desde su caché la lista de la versión 1: find_orders, get_order_status, quote_refund, issue_refund, check_stock. Su llamada a find_orders durante la ventana aún devolvió un result. Un modelo detrás de un cliente con caché no se entera de find_orders_v2 hasta que expire el TTL o el cliente vuelva a pedir la lista, por eso el TTL debe ser corto mientras un cambio está en curso, y por eso la herramienta antigua tiene que seguir funcionando.
Tras la versión 3, la llamada del cliente con caché a find_orders devolvió un error de ejecución con el que el modelo puede actuar: "Error executing tool find_orders: find_orders was retired. Call find_orders_v2 with the same customer_id.". Una herramienta eliminada habría producido en cambio el error de herramienta desconocida del SDK, que indica al modelo que el nombre era incorrecto pero no qué llamar (Informa de los fallos como resultados de herramienta). El SDK devuelve ese error como error de ejecución de herramienta, aunque la especificación trata una herramienta desconocida como error de protocolo (mcp/server/mcpserver/tools/tool_manager.py; herramientas, "Error Handling").
La lista del cliente que escucha muestra además un efecto secundario: find_orders pasó al final. MCPServer lista las herramientas en el orden en que se añadieron, así que el intercambio en vivo de la versión, que quita la herramienta y la vuelve a añadir, la desplaza (Cachea los resultados de listas). Un cambio de orden altera el inicio de cada prompt que renderiza la lista, que es lo que compara la caché de prompts de un proveedor de modelos. Un servidor que se reinicia con el código nuevo lista las herramientas en el orden en que su código las registra, así que añade las herramientas nuevas al final y deja las existentes donde están.
Regla práctica: Retira una herramienta en tres versiones: añade el reemplazo y marca la herramienta antigua como obsoleta en su descripción, mantén ambas funcionando durante una ventana que anuncies, y luego responde al nombre antiguo con un error de ejecución que nombre el reemplazo. Reduce ttlMs en tools/list mientras el cambio está en curso, publica un aviso de cambio de lista en cada versión y abre un flujo de subscriptions/listen en cada host que controles. Indica en tu registro de cambios que la ventana es una política tuya, ya que el protocolo no define ninguna.
Qué sale mal en producción
Las comprobaciones de aquí se ejecutan sobre un solo proceso en una sola máquina. En producción, las mismas señales llegan de muchas réplicas y clientes, y cada una puede confundirte a su manera.
Los spans se multiplican más de lo que un backend puede indexar. El SDK nombra un span de servidor según el método y la herramienta, lo que mantiene el número de nombres distintos tan pequeño como la lista de herramientas. Un ID de pedido, una URI de recurso o un ID de cliente dentro de un nombre de span crea un nombre por cada valor; por eso las convenciones de MCP guardan la URI del recurso en un atributo (Convenciones semánticas de MCP). La señal es una factura de trazado que crece con el tráfico en lugar de con las funcionalidades.
Las trazas contienen los datos de la tienda. El SDK no registra argumentos ni resultados de herramientas en sus spans (mcp/server/_otel.py), y las convenciones marcan gen_ai.tool.call.arguments como opt-in (misma fuente). Los argumentos de la tienda contienen ID de cliente y de pedido, y un argumento solo dice lo que envió quien llama. Para registrar quién actuó, toma el sujeto del token verificado, que en el host de soporte es el miembro del personal, junto con el cliente del registro del ticket que comprobó el servidor (Evita que el servidor actúe como un confused deputy). Añade argumentos a los spans solo detrás de un ajuste, y mantenlos fuera de cualquier backend que la política de tratamiento de datos de la tienda no cubra.
Las convenciones se mueven bajo tus paneles. Las convenciones de MCP tienen el estado «Development» y han cambiado de repositorio una vez (aviso de traslado), y el middleware del SDK está marcado como provisional (mcp/server/lowlevel/server.py). Una versión del SDK que renombra un atributo vacía un panel sin ningún error. Mantén los nombres de los atributos en un solo lugar de tu configuración, y revísalos en cada actualización del SDK, como harías con cualquier disparador de actualización.
Las réplicas no coinciden durante un despliegue. En un despliegue progresivo, una réplica sirve el esquema de la versión 1 mientras la siguiente sirve el de la versión 2, y un cliente que listó desde una y llama a la otra recibe el RuntimeError de Comprueba los esquemas como un contrato. La señal son errores de validación en el cliente que suben durante un despliegue y bajan cuando termina. Publica primero los cambios aditivos, y elimina la forma antigua solo cuando todas las réplicas sirvan la nueva y haya pasado la ventana.
La grabación envejece. Una repetición sigue pasando mientras cambia el modelo detrás del host de producción, de modo que las puntuaciones de la grabación se alejan de lo que ven los clientes. Vuelve a grabar en cada cambio de modelo, como recomienda Trabaja con la cola de tickets, y ejecuta la misma comprobación de promesas sin respaldo sobre una muestra de ejecuciones de producción, ya que una repetición no puede encontrar un fallo que el modelo grabado nunca cometió.
Regla práctica: Antes de confiar en una traza o en una puntuación, comprueba qué cubre: qué transporte, qué modelo y qué versión de cada esquema. Mantén los nombres de span acotados y los argumentos fuera de los spans por defecto, fija los nombres de atributos que usan tus paneles a una versión concreta de la convención, y ejecuta la prueba de contrato y la repetición con cada versión antes de que llegue a una réplica.
Decisiones que tomó este capítulo
- Las herramientas se prueban en memoria con
Client(server, raise_exceptions=True), verificando los campos, con una prueba de bucle de retorno por transporte para lo que la ruta en proceso omite. - pytest se ejecuta con el plugin propio de anyio, y sin
inline-snapshot, que el libro no fija.lib.testingimprime una línea por prueba para que la salida sea estable. - Los esquemas de la última versión son el contrato. CI valida los nuevos resultados contra ellos con el validador del dialecto declarado por cada esquema, 2020-12 por defecto, y
lib.contractcompara los esquemas para su revisión. - La grabación
ticket-runsdel capítulo 10 se reproduce, no se vuelve a grabar. UnRecordingMismatchtras un cambio en la descripción significa que hay que grabar de nuevo. - El host contrasta las respuestas con su registro de llamadas. Una respuesta que promete un reembolso que ninguna llamada realizó pasa a una persona; la comprobación por palabras clave de
lib.queue_replayes una regla práctica. - Las trazas provienen del middleware del SDK, con los atributos que emite etiquetados como una convención con estado Development, y la propagación se prueba sobre HTTP.
- La elección de herramienta se puntúa por etiqueta, y los argumentos por separado, con
expected_first_tool, como puntúa el capítulo 10. Los identificadores de pedido se puntúan tanto contra el texto del ticket como contra el pedido que el cliente quería decir. - Las herramientas se retiran a lo largo de tres versiones, con un TTL corto y un cambio en la lista en cada una, y un error de ejecución que nombra el reemplazo después de la ventana. El procedimiento es la práctica del libro, no la especificación.
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.