Construye un host que atiende tickets

Unos 33 minutos de lectura, con 6 ejemplos en 8 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 terminar este capítulo podrás conectar un host a varios servidores del Model Context Protocol, dar a sus herramientas nombres que no puedan chocar entre sí, ejecutar un bucle corto en el que un modelo llama a herramientas y lee sus resultados, responder en nombre del usuario a las peticiones de entrada de un servidor, incorporar recursos al contexto del modelo y atender una cola de tickets a través de todo ello. Las afirmaciones y el código de este capítulo se cumplen para la revisión 2026-07-28 de la especificación y para mcp 2.3.0, el SDK de Python.

Cada ticket es una pregunta de un cliente dirigida a la tienda, y su equipo de soporte la atiende a través de un host. Los datos de la tienda contienen 48 tickets de este tipo, cada uno etiquetado con la herramienta que un agente correcto llama primero, y redactados como los escriben los clientes: con erratas, con números de pedido sin contexto, con identificadores equivocados y con seis que incluyen instrucciones dirigidas a un agente. Cada capítulo anterior construyó una parte que el host necesita. El bucle de host del capítulo 1, lib.host, mostró a un modelo un ticket y las herramientas de un servidor, y leyó una sola elección (Deja que un modelo elija la herramienta). El capítulo 9 añadió las comprobaciones propias del host: definiciones de herramientas fijadas y consentimiento antes de los efectos secundarios (Pide consentimiento antes de los efectos secundarios).

En el Model Context Protocol (MCP), al host le corresponde mucho. La página de arquitectura de la especificación dice que el host crea y gestiona los clientes, hace cumplir el consentimiento, gestiona las decisiones de autorización del usuario y agrega el contexto de los distintos clientes, mientras que cada servidor solo ve su propia parte de la conversación (arquitectura). Un host de soporte que toma los tickets uno a uno de una cola tiene que hacer todo eso para 48 tickets seguidos, frente a dos servidores: el de la tienda y el del socio, un servidor de seguimiento de paquetes del socio de reparto de la tienda que introdujo Dibuja los límites de confianza.

En este capítulo construimos ese host, al que llamamos el host de soporte, en un módulo nuevo, lib.ticket_host. Mantiene un cliente por servidor y unas pocas vueltas de llamadas al modelo por ticket, y nada más: la planificación, la memoria y los bucles de agente más largos son un tema aparte, la construcción de agentes, que queda fuera de este libro, así que este capítulo se centra en lo que MCP le pide a un host. Hay otros dos archivos nuevos. lib.support_shop es el servidor de la tienda tal como lo ve el host de soporte, que reúne las herramientas del capítulo 3, la confirmación del capítulo 5 para los reembolsos por encima del límite de la política y las políticas del capítulo 4 expuestas como recursos. recordings/ticket_runs.py registra al modelo del libro trabajando a lo largo de la cola, como la grabación ticket-runs, que dos de los ejemplos de este capítulo reproducen, y que Prueba un servidor y observa cómo funciona reutiliza.

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

Connect one client per server

Último cambio en la edición 2026.11.14

A host that uses several servers holds several clients, and the specification is exact about the shape: the host creates each client, and each client talks to exactly one server (architecture). At the pinned revision there is no initialize handshake to share, because every request carries its version and the client's capabilities in _meta (versioning), as Carry the version and capabilities on every request explains. A client still learns its server's era: the pinned revision or a 2025 one. The specification asks clients to cache that era "for the lifetime of the server process (stdio) or origin (HTTP)" (versioning).

The Python SDK offers a class for several servers, ClientSessionGroup, and it looks like the natural choice. At mcp 2.3.0 it isn't one. Its connect_to_server always calls session.initialize(), the 2025 handshake, and never sends the server/discover probe that the pinned revision starts with (mcp/client/session_group.py; session groups). The SDK's own servers speak both eras, so a group still connects, but on the older revision, where a server pushes its input requests instead of returning them in a Multi Round-Trip Request. That would quietly undo chapter 5.

A group can also take a session you already hold, through connect_with_session. The SDK's page suggests a Client's session for that, which would be on the pinned revision (session groups). The group then only merges the lists. Its call_tool raises an error on an input request unless you pass allow_input_required=True and drive the rounds yourself (mcp/client/session_group.py). It also still refuses two tools with one name unless it renames them all, as Name tools across servers shows.

The support host uses one mcp.Client per server instead. Each runs in its default auto mode, which probes server/discover and falls back to the handshake only for a server that doesn't answer it (mcp/client/client.py). The host keeps the clients in a map keyed by a prefix its own configuration assigns: shop for the shop's server, launched over stdio from lib.support_shop, and partner for the partner's server, lib.partner, connected in-process. The code connects both, gives the shop's server to a ClientSessionGroup, and reconnects to the shop's server with the era the first connection learned.

connect-two-servers.py Python 3.12.15 · cryptography 50.0.2 · httpx2 2.16.2 · mcp 2.3.0 · mcp-types 2.3.0 · pydantic 2.14.3 · starlette 1.10.0 · uvicorn 0.54.0 Superado
"""Two clients under their own prefixes each settle their own revision, and the SDK's ClientSessionGroup settles theshop's server on an older one. A reconnect that reuses the cached era sends no server/discover probe, which theexample asserts before it prints the first request."""import asyncioimport pathlibfrom mcp import Clientfrom mcp.client.session_group import ClientSessionGroupfrom lib import loopback, shop_api, support_shop, ticket_host, wireLOG = pathlib.Path("connect-two-servers.jsonl")async def main() -> None:    LOG.unlink(missing_ok=True)    with loopback.serve(shop_api.create_app()) as base_url:        async with ticket_host.queue_host(base_url) as host:            for prefix, client in host.clients.items():                print(f"{prefix} server:", client.server_info.name)                print(f"{prefix} protocol revision:", client.protocol_version)            era = host.clients["shop"].session.discover_result         # what the probe learned, kept per server            revision = host.clients["shop"].protocol_version        async with ClientSessionGroup() as group:            session = await group.connect_to_server(support_shop.server_params(base_url))            print("ClientSessionGroup protocol revision:", session.protocol_version)        params = wire.relay(support_shop.server_params(base_url), log=str(LOG))        # mode is the revision the first connection settled on, prior_discover its cached era: no probe is sent        async with Client(params, mode=revision, prior_discover=era) as again:            await again.list_tools()            print("reconnect protocol revision:", again.protocol_version)    # "out" marks the messages the client sent, as the relay logged them    methods = [message.get("method") for direction, message in wire.read_trace(str(LOG)) if direction == "out"]    assert "server/discover" not in methods      # the reconnect never probed, because the era was cached    print("reconnect first request:", methods[0])        # index 0: the first message the reconnect sent    LOG.unlink()asyncio.run(main())
Salidapython connect-two-servers.py
shop server: shop-support
shop protocol revision: 2026-07-28
partner server: partner-tracking
partner protocol revision: 2026-07-28
ClientSessionGroup protocol revision: 2025-11-25
reconnect protocol revision: 2026-07-28
reconnect first request: tools/list

Both of the support host's clients settled on 2026-07-28, each on its own. The group, given the same shop server, settled on 2025-11-25, an older revision.

The reconnect passed the cached DiscoverResult as prior_discover, with the revision as mode, which Client adopts with no probe. It spoke 2026-07-28 and sent no server/discover probe. Its first request was tools/list.

The reconnect launched a new server process, so it went past a cache for one process's lifetime, into what the specification allows: a client MAY persist the era "across restarts of the same server configuration, re-probing if the cached assumption later fails" (versioning). A host that restarts stdio servers or reconnects to an HTTP origin saves one round trip per connection that way.

The prefixes belong to the host, not the servers. Each server names itself, here shop-support and partner-tracking, but nothing makes those names unique or stable, and at the pinned revision a server may leave its name out altogether (mcp/client/client.py, server_info). Name tools across servers builds on the prefixes.

Working rule: Give each server its own Client, in auto mode, under a key from the host's configuration. Cache each server's era for as long as its process or origin lasts, reuse it across restarts of the same configuration if you like, and probe again when a request fails with a version error. Don't use ClientSessionGroup at mcp 2.3.0: its connect_to_server speaks only the 2025 handshake, and given Client sessions it adds merged lists but not the retry rounds or the host's own names. Check again at each SDK release, because a group that probes would remove the need for your own map.

Nombrar herramientas entre servidores

Último cambio en la edición 2026.11.11

Con un cliente por servidor, el host de soporte mantiene dos listas de herramientas, y el modelo necesita una sola. Los nombres de herramienta solo son únicos dentro de un mismo servidor, así que dos servidores pueden ofrecer el mismo nombre, y la especificación lo prevé. Un host que agrega servidores DEBERÍA desambiguar, por ejemplo anteponiendo al nombre de cada herramienta un identificador del servidor. El name del servidor, tomado de serverInfo, no está garantizado como único entre servidores, y la especificación indica que NO DEBERÍA confiarse en él para ese fin (herramientas). El prefijo también debe mantener el nombre válido: los nombres de herramienta DEBERÍAN usar solo letras, dígitos, _, - y ., hasta 128 caracteres (herramientas).

El caso de la tienda hace concreta la colisión. Supón que la siguiente versión del socio añade una herramienta llamada get_order_status, para sus propios pedidos de entrega, junto a track_parcel, de modo que ambos servidores ofrecen una herramienta con ese nombre, con significados distintos. ClientSessionGroup ofrece un hook, component_name_hook, que renombra las herramientas al llegar. Renombra cada nombre de cada servidor, no solo los que colisionan. El ejemplo del propio docstring del SDK construye el nuevo nombre a partir de serverInfo.name, el nombre en el que la especificación dice que no hay que confiar (mcp/client/session_group.py; grupos de sesiones). Sin el hook, el grupo rechaza el segundo servidor.

El host de soporte nombra cada herramienta {prefix}.{tool}. Usa . como separador porque . está en el conjunto permitido y se lee como una ruta. TicketHost.route convierte un nombre que usó el modelo de vuelta en el prefijo del servidor y el nombre de la herramienta tal como viaja por el protocolo, y no devuelve nada para un nombre desconocido.

tool-name-collision.py Python 3.12.15 · cryptography 50.0.2 · httpx2 2.16.2 · mcp 2.3.0 · mcp-types 2.3.0 · pydantic 2.14.3 · starlette 1.10.0 · uvicorn 0.54.0 Superado
"""The partner's next release adds its own get_order_status, and ClientSessionGroup refuses it beside the shop's. Thehost's prefixes keep both tools, and route each name the model sees back to one server, or to none for a bare name."""import asyncioimport sysfrom mcp import MCPError, StdioServerParametersfrom mcp.client.session_group import ClientSessionGroupfrom mcp.types import ToolAnnotationsfrom lib import host_guard, loopback, partner, shop_api, support_shop, ticket_hostserver = partner.create_server("clean")@server.tool(title="Look up a delivery order", annotations=ToolAnnotations(read_only_hint=True))def get_order_status(delivery_id: str) -> str:    """Where one of the partner's delivery orders is, by its delivery ID, such as D-58120."""    return f"{delivery_id}: out for delivery"async def main() -> None:    # the partner's server is this same file, started with --serve, so it runs the tool defined above    mine = StdioServerParameters(command=sys.executable, args=[__file__, "--serve"], env={})    with loopback.serve(shop_api.create_app()) as base_url:        servers = {"shop": support_shop.server_params(base_url), "partner": mine}        async with ClientSessionGroup() as group:            for params in servers.values():                try:                    await group.connect_to_server(params)                except MCPError as error:                    print("ClientSessionGroup:", error)        gate = host_guard.ConsentGate(host_guard.NO_SIDE_EFFECTS, ask=ticket_host.approve_every_call)        async with ticket_host.TicketHost(servers, gate=gate, lead=ticket_host.decline_every_request) as host:            names = [tool.name for tool in host.tools()]            print("tools the model sees:", len(names))            for name in names:                if name.endswith("get_order_status"):      # the colliding tool's two names, one from each server                    print(f"{name} routes to:", host.route(name))            # a bare name has no prefix, so the host can't tell which server the model meant, and routes it to None            print("get_order_status routes to:", host.route("get_order_status"))server.run() if "--serve" in sys.argv else asyncio.run(main())
Salidapython tool-name-collision.py
ClientSessionGroup: {'get_order_status'} already exist in group tools.
tools the model sees: 7
shop.get_order_status routes to: ('shop', 'get_order_status')
partner.get_order_status routes to: ('partner', 'get_order_status')
get_order_status routes to: None

Donde el grupo lanzó {'get_order_status'} already exist in group tools. y solo conservó el servidor de la tienda, el host de soporte conservó ambos, y el modelo ve 7 herramientas.

shop.get_order_status se enruta a ('shop', 'get_order_status'), y partner.get_order_status a ('partner', 'get_order_status'). Un get_order_status sin prefijo se enruta a None. El host no adivina a qué servidor se refería el modelo, y en su lugar le envía un resultado de error que nombra el problema.

Anteponer el prefijo a todos los nombres, no solo a los que colisionan, cuesta unos pocos tokens por herramienta y aporta estabilidad. Un nombre que el modelo ya aprendió sigue igual cuando otro servidor añade una herramienta, de modo que un prompt guardado, una caché de prompts y una línea de registro siguen significando lo mismo. La página de buenas prácticas del cliente pide a los hosts mantener estable el array tools por la misma razón: añadir o quitar herramientas a mitad de una conversación invalida la caché de prompts del proveedor del modelo (buenas prácticas del cliente).

Antes de elegir un separador, comprueba que tu modelo lo devuelve tal cual. En la ejecución de la cola, el modelo del libro escribió cada nombre con un prefijo que el host conocía, de modo que cada una de sus 54 llamadas a herramientas terminó como un resultado o como un error de ejecución de herramienta, y ninguna como herramienta desconocida. Otro modelo puede eliminar o reescribir un prefijo, y entonces el resultado de error se lo indica.

Regla práctica: Antepón a cada nombre de herramienta una clave de la configuración del host, unida con . o _, y enruta cada llamada de vuelta por tu propio mapa, nunca por serverInfo.name. Antepón el prefijo a todos los nombres, no solo a los que colisionan, para que los nombres se mantengan estables cuando cambia un servidor. Si el nombre es desconocido o no lleva prefijo, devuelve al modelo un error en lugar de adivinar.

Ejecuta el bucle del host

Último cambio en la edición 2026.11.11

Con herramientas con nombres en varios servidores, el host de soporte puede dejar que el modelo trabaje un ticket. El bucle es breve. El host envía al modelo un prompt de sistema con las herramientas y el ticket como mensaje del usuario. Si la respuesta contiene una llamada a herramienta, el host la verifica, la ejecuta y envía el resultado como el siguiente mensaje. Si la respuesta son palabras, el ticket está terminado. Todo lo que no se puede confiar a un modelo se queda en el host, entre la respuesta y la llamada: el nombre se enruta mediante el mapa propio del host, la llamada pasa por la puerta de consentimiento del capítulo 9 (Pide consentimiento antes de los efectos secundarios), y la llamada tiene un tiempo límite.

La página sobre herramientas asigna al cliente varios de esos deberes. Los clientes DEBERÍAN devolver al modelo los errores de ejecución de herramientas, resultados con isError: true, "para permitir la autocorrección". También DEBERÍAN confirmar con el usuario las operaciones sensibles, mostrar las entradas de las herramientas antes de llamarlas, validar los resultados antes de pasarlos, fijar tiempos límite y registrar el uso de herramientas (herramientas).

El host de soporte envía cada resultado de vuelta en un bloque <tool_response>, identificado por herramienta y resultado. Los resultados son un resultado correcto, un error de ejecución de la herramienta, una llamada que el usuario rechazó, un nombre que no conoce y una llamada fallida, ya sea por agotar el tiempo de 10.0 segundos en una solicitud o por superar el límite del cliente en rondas de solicitudes de entrada. Detiene un ticket después de 4 llamadas al modelo, de modo que un modelo que sigue llamando herramientas no pueda disparar la factura de un solo ticket.

El prompt del host es el del capítulo 1, más un párrafo que indica que los nombres de las herramientas empiezan por su servidor, que los resultados llegan en bloques <tool_response>, que el modelo responde al cliente cuando tiene lo que el ticket necesita, y que solo usa identificadores de pedido, importes y quote_id que el ticket o una herramienta le hayan dado. El prompt y el análisis del texto se quedan en el código del libro, como recomienda Deja que un modelo elija la herramienta.

Las respuestas del modelo provienen de la grabación ticket-runs, que recordings/ticket_runs.py hizo con el modelo del libro, Qwen3-4B-Instruct-2507, cuantizado a 4 bits y ejecutado en la CPU. Muestreó con una temperatura de 0.7 y una semilla fija, 4217, como hizo la grabación del capítulo 1. Una grabación solo responde a los mensajes exactos que vio, y a partir del segundo turno esos mensajes contienen resultados de herramientas, así que una reproducción también falla si cambia la salida de una herramienta.

Por eso lib.support_shop deriva cada quote_id a partir de un contador, con hash y la semilla de la tienda, en lugar de hacerlo al azar. Un quote_id aleatorio cambiaría en cada ejecución, y con él cada turno posterior. El identificador parece aleatorio, como Q-140ce69dd6, pero se repite exactamente en cada ejecución y después de cada reinicio, cuando el contador vuelve a empezar, así que los mismos identificadores regresan nombrando presupuestos distintos. Una reproducción lo necesita, y un servidor que se distribuye nunca debe hacerlo: un servidor distribuido mantiene sus identificadores aleatorios, para que nadie pueda deducirlos (Diseña las herramientas alrededor de tareas, no de endpoints).

El ticket T-0009 muestra el bucle cuando la primera suposición es errónea. El cliente pregunta cuánto costaría un reembolso del pedido "o7144". El pedido al que se refiere es O-1744, y O-7144 no existe.

work-one-ticket.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
"""The support host works one ticket and prints each model turn: the tool call, its outcome, and what went back to themodel. The model's replies are replayed from the recording in examples/data/recorded/ticket-runs/, whichrecordings/ticket_runs.py made."""import asyncioimport jsonfrom lib import loopback, shop_api, ticket_hostfrom lib.host import ReplayModelfrom lib.shop_data import load_shopmodel = ReplayModel("ticket-runs")      # replays the recorded replies, so no model runs hereTICKET = "T-0009"async def main() -> None:    ticket = load_shop().ticket(TICKET)    print("ticket asks:", max(ticket.body.split("\n\n"), key=len))      # the customer's message is the ticket's longest paragraph    print("order the customer means:", ticket.order_id)    with loopback.serve(shop_api.create_app()) as base_url:        async with ticket_host.queue_host(base_url) as host:            await host.attach("shop")            run = await host.work(model, ticket)    for number, turn in enumerate(run.turns, start=1):        if turn.tool is None:            print(f"turn {number} reply:", turn.reply)            continue        print(f"turn {number} tool:", turn.tool)        print(f"turn {number} arguments:", turn.arguments)        print(f"turn {number} outcome:", turn.outcome)        print(f"turn {number} back to the model:", turn.result[:160])      # the first 160 characters, enough for a message    print("model calls:", len(run.turns))    print("model calls allowed per ticket:", ticket_host.MAX_TURNS)    print("timeout per request, seconds:", ticket_host.CALL_TIMEOUT)    manifest = json.loads((model.folder / "manifest.json").read_text())    print("sampling temperature:", manifest["sampling"]["temperature"])    print("sampling seed:", manifest["sampling"]["seed"])    batches = manifest["batches"]    print("recording batches:", len(batches))    print("single-ticket batches:", sum(b["scenario"] == "one" for b in batches))      # "one" marks a batch of a single ticket    seconds = [s for b in batches for s in b["seconds_per_call"]]    print("seconds per model call, mean:", round(sum(seconds) / len(seconds), 1))    # the batch's time is its calls' seconds added up    print("longest batch, minutes:", round(max(sum(b["seconds_per_call"]) for b in batches) / 60, 1))asyncio.run(main())
Salidapython work-one-ticket.py
ticket asks: The stoneware mug pair on order o7144 isn't what I expected. What woudl the refund be?
order the customer means: O-1744
turn 1 tool: shop.quote_refund
turn 1 arguments: {'order_id': 'O-7144', 'sku': 'KG-1031', 'reason': 'not what I expected'}
turn 1 outcome: tool error
turn 1 back to the model: Error executing tool quote_refund: The shop has no order O-7144. Check the number with the customer, or use find_orders to list their orders.
turn 2 tool: shop.find_orders
turn 2 arguments: {'customer_id': 'C-0129'}
turn 2 outcome: result
turn 2 back to the model: {"customer_id": "C-0129", "orders": [{"order_id": "O-2456", "placed_on": "2026-06-21", "status": "shipped", "total": "29.99", "skus": ["KG-1034"]}, {"order_id":
turn 3 reply: I checked your orders, and there is no order with ID O-7144. Your orders are O-2456 and O-1744. Please confirm the correct order ID for the stoneware mug pair you're returning. Once I have the correct order, I can help you with the refund amount.
model calls: 3
model calls allowed per ticket: 4
timeout per request, seconds: 10.0
sampling temperature: 0.7
sampling seed: 4217
recording batches: 5
single-ticket batches: 1
seconds per model call, mean: 16.5
longest batch, minutes: 8.0

El modelo fue directo a quote_refund, con el identificador de pedido que leyó y un SKU, KG-1031, que el ticket nunca le dio. Ese SKU es el ejemplo de las descripciones de herramientas de la tienda. La llamada devolvió un tool error: el servidor indicó que no existe tal pedido y que find_orders enumera los pedidos del cliente. En el segundo turno el modelo siguió ese consejo y llamó a shop.find_orders para el cliente del ticket. Con la lista delante, el modelo no eligió O-1744 para el cliente. Respondió: "I checked your orders, and there is no order with ID O-7144. Your orders are O-2456 and O-1744. Please confirm the correct order ID for the stoneware mug pair you're returning. Once I have the correct order, I can help you with the refund amount." El ticket necesitó 3 llamadas al modelo.

El resultado de error hizo su trabajo. Un host que hubiera ocultado el fallo habría dejado al modelo adivinar. El SKU inventado es la segunda lección: un modelo copia valores de ejemplo de las descripciones en sus argumentos, así que un servidor debe rechazar los argumentos que no coinciden con el pedido. El quote_refund de la tienda lo hace en otros tickets de la ejecución de la cola, respondiendo que el pedido no tiene ninguna línea para ese SKU. Los ejemplos en las descripciones también deben ser valores que no puedan confundirse con valores reales.

Regla práctica: Mantén el bucle en el host, breve y acotado: enruta cada llamada mediante tu propio mapa, pásala por el consentimiento, dale un tiempo límite y envía cada resultado de vuelta al modelo, los errores incluidos, en un formato que escriba tu propio código. Limita las llamadas al modelo por ticket. Todo lo que sea más largo que unos pocos turnos, como planificar entre tickets o la memoria, pertenece a un marco de agentes, no al código de protocolo del host.

Responder a las solicitudes de entrada del usuario

Último cambio en la edición 2026.11.11

Algunas llamadas a herramientas en el bucle del host no terminan con la primera solicitud. En la revisión fijada, un servidor que necesita algo del usuario devuelve un InputRequiredResult con inputRequests en lugar de un resultado. El cliente entonces reintenta la misma llamada con inputResponses, repitiendo sin cambios el requestState del servidor y usando un nuevo id de JSON-RPC (Solicitudes de ida y vuelta múltiples). Devolver una solicitud de entrada en lugar de un resultado construyó el lado del servidor, y esta sección es la del host, donde la especificación añade deberes propios. Para la elicitación, los clientes DEBEN dejar claro qué servidor está preguntando, ofrecer opciones claras de rechazar y cancelar y, en el modo de formulario, permitir que el usuario revise y cambie las respuestas antes de enviarlas (elicitación).

El SDK de Python reparte el trabajo. Client.call_tool ejecuta el bucle de reintentos por sí mismo, hasta input_required_max_rounds rondas, y entrega cada elicitación al elicitation_callback del cliente (mcp/client/client.py, mcp/client/_input_required.py). El callback recibe la solicitud y la sesión por la que llegó, pero no el nombre que el host da a ese servidor, así que el host de soporte asigna a cada cliente su propio callback, vinculado al prefijo de ese cliente. El callback pasa el prefijo y la solicitud a la persona que responde por el host, a quien el código llama el responsable, y registra la solicitud y la respuesta en host.asked.

La API de la tienda retiene un reembolso superior al límite de la política de reembolsos, de €150.00, hasta que un responsable de soporte lo libera, y issue_refund pide esa liberación con un formulario de un solo campo. Dos de estos reembolsos pasan por el método call del propio host de soporte, la vía que sigue una llamada a herramienta de un modelo, y un responsable simulado acepta el primero y rechaza el segundo.

host-answers-elicitation.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
"""Two refunds above the policy limit, each held by an input request from the shop's server. The host shows the leadwhich server asks and what, and Client.call_tool retries with the answer; the lead accepts the first and declines the second."""import asyncioimport jsonfrom mcp.types import ElicitResultfrom lib import loopback, shop_api, ticket_hostfrom lib.shop_data import REFUND_LIMIT_CENTS, moneyanswers = [ElicitResult(action="accept", content={"release": True}), ElicitResult(action="decline")]   # the scripted lead's answers, in orderfields: list[str] = []                      # the form fields the lead was showndef lead(server: str, params) -> ElicitResult:    fields.extend(params.requested_schema["properties"])      # the field names, from the request's schema    return answers.pop(0)                   # index 0: the next unused answer, so each request gets one answer in turnasync def main() -> None:    print("refund policy limit:", money(REFUND_LIMIT_CENTS))    with loopback.serve(shop_api.create_app()) as base_url:        async with ticket_host.queue_host(base_url, lead=lead) as host:            for order_id in ("O-1145", "O-2289"):                outcome, quote = await host.call("shop.quote_refund", {"order_id": order_id})                quote_id = json.loads(quote)["quote_id"]                print(f"{order_id} quote id:", quote_id)                outcome, text = await host.call("shop.issue_refund", {"quote_id": quote_id})                server, message, action = host.asked[-1]          # index -1: the request this call just answered                print(f"{order_id} asked by:", server)                print(f"{order_id} message:", message)                print(f"{order_id} lead's answer:", action)                print(f"{order_id} outcome:", outcome)                print(f"{order_id} back to the model:", text)            print("form fields:", ", ".join(sorted(set(fields))))            print("input requests answered:", len(host.asked))            # the rounds one call may take before the client raises, which is the client's default here            print("retry rounds allowed per call:", host.clients["shop"].input_required_max_rounds)            # only the calls the gate asked the user about, not those its list let through without asking            print("consent asked for:", [request.tool for request, decision in host.gate.log                                         if decision != "allowed by the host's list"])asyncio.run(main())
Salidapython host-answers-elicitation.py
refund policy limit: 150.00
O-1145 quote id: Q-140ce69dd6
O-1145 asked by: shop
O-1145 message: Refund 343.49 on order O-1145? It is above the policy limit, so a lead must confirm it.
O-1145 lead's answer: accept
O-1145 outcome: result
O-1145 back to the model: {"refund_id": "R-0111", "quote_id": "Q-140ce69dd6", "order_id": "O-1145", "amount": "343.49", "status": "requested"}
O-2289 quote id: Q-98d6567215
O-2289 asked by: shop
O-2289 message: Refund 180.00 on order O-2289? It is above the policy limit, so a lead must confirm it.
O-2289 lead's answer: decline
O-2289 outcome: tool error
O-2289 back to the model: Error executing tool issue_refund: Nobody confirmed refund R-0112, so the shop's API still holds it.
form fields: release
input requests answered: 2
retry rounds allowed per call: 10
consent asked for: ['issue_refund', 'issue_refund']

Cada vez, el responsable vio qué servidor preguntaba y cuál era su mensaje. Para el primer reembolso, preguntó el servidor con el prefijo shop, y su mensaje decía: Refund 343.49 on order O-1145? It is above the policy limit, so a lead must confirm it. El formulario tenía un campo, release. Tras la respuesta del responsable, accept, el reintento liberó el reembolso, y el modelo leería el reembolso, con su ID y el estado requested.

El segundo reembolso fue rechazado. Tras la respuesta del responsable decline para el pedido O-2289, el servidor produjo un error de ejecución de herramienta, y el modelo leería: Error executing tool issue_refund: Nobody confirmed refund R-0112, so the shop's API still holds it. Ese resultado de error es lo que permite al modelo decirle al cliente la verdad: el reembolso está esperando a una persona.

Ambos reembolsos también superaron la puerta de consentimiento del capítulo 9 antes de llegar al servidor, y el host preguntó al usuario por ['issue_refund', 'issue_refund']. El consentimiento y la confirmación del servidor responden a preguntas distintas. El consentimiento es el host preguntando si una llamada debe ocurrir siquiera, para cualquier servidor. La confirmación es el servidor de la tienda preguntando por un reembolso concreto que su propia política retiene, y solo un servidor que decida preguntar lo hará (Pedir consentimiento antes de efectos secundarios).

Cada llamada aquí usó una ronda de reintento, de las 10 que Client permite por defecto. Un servidor que sigue preguntando más allá de ese límite hace que call_tool lance InputRequiredRoundsExceededError, que el host de soporte devuelve al modelo como una llamada failed, como cualquier otro fallo. Un host que espera intercambios más largos eleva el límite o dirige las rondas por sí mismo con client.session.call_tool(..., allow_input_required=True), como hace Reanudar la llamada con la respuesta.

En el modo URL, un accept significa solo que el usuario aceptó la interacción, no que la terminara (elicitación). Por eso el host muestra la URL completa, pregunta antes de abrirla y nunca la abre por sí mismo.

Regla práctica: Da a cada cliente su propio callback de elicitación que sepa a qué servidor pertenece, y muestra al usuario el nombre de ese servidor junto con su mensaje, los campos y una forma de rechazar. Devuelve un rechazo al modelo como error del servidor, no como silencio, para que el modelo pueda explicar lo ocurrido. Mantén también el consentimiento en el host, porque la pregunta del servidor cubre solo lo que el servidor elige preguntar.

Pon recursos en el contexto del modelo

Último cambio en la edición 2026.11.11

Las solicitudes de entrada traen al usuario a una llamada; los recursos traen documentos al contexto del modelo, y el host decide cuáles. La especificación llama a los recursos impulsados por la aplicación: los hosts deciden cómo usarlos, ya sea dejando que el usuario elija, con sus propias heurísticas o preguntándole al modelo (recursos). Nada llega al contexto de un modelo solo porque un servidor lo haya listado. Un servidor puede ayudar con las anotaciones: audience indica si un recurso es para el user o para el assistant, y priority, de 0 a 1, indica cuánto importa. Los clientes pueden usar ambas para filtrar y elegir qué incluir (recursos).

El servidor de la tienda lista sus 6 políticas como recursos, con las anotaciones que Expón las políticas como recursos les asignó. Todas son para el asistente. La política de reembolsos tiene prioridad 1.0, y las demás tienen prioridad 0.5. La política de reembolsos es la que más importa al modelo, porque dice qué puede reembolsarse y que un reembolso por encima del límite espera a un responsable. La regla del host de soporte es propia: adjuntar cada recurso que el servidor marque para el asistente con una prioridad de al menos 0.8, una sola vez, después de las herramientas del prompt del sistema. El modelo nunca elige, así que el texto de un ticket no puede meter un documento en el contexto.

attach-a-policy-resource.py Python 3.12.15 · cryptography 50.0.2 · httpx2 2.16.2 · mcp 2.3.0 · mcp-types 2.3.0 · pydantic 2.14.3 · starlette 1.10.0 · uvicorn 0.54.0 Superado
"""The host attaches the shop's policies that the server marks for the assistant at a high priority, and the model neverchooses them. The second read of the refund policy is answered from the client's cache, so only the first reaches the trace, which the last printed line counts."""import asyncioimport pathlibfrom lib import loopback, shop_api, ticket_host, wirefrom lib.shop_data import load_shopLOG = pathlib.Path("attach-a-policy-resource.jsonl")async def main() -> None:    LOG.unlink(missing_ok=True)    with loopback.serve(shop_api.create_app()) as base_url:        servers = ticket_host.queue_servers(base_url)      # the shop's and the partner's servers, as the queue uses them        servers["shop"] = wire.relay(servers["shop"], log=str(LOG))      # logs every message the shop's server exchanges        async with ticket_host.queue_host(base_url, servers) as host:            listed = (await host.clients["shop"].list_resources()).resources            for resource in listed:                print(f"{resource.uri}: priority {resource.annotations.priority}")            priorities = {str(r.uri): r.annotations.priority for r in listed}            print("policies listed:", len(listed))            print("refund policy priority:", priorities.pop("shop://policies/refund"))      # removed, so the rest are the others            print("other policies' priority:", ", ".join(str(p) for p in sorted(set(priorities.values()))))            print("attach at priority at least:", ticket_host.ATTACH_PRIORITY)            print("tools the model sees:", len(host.tools()))            print("attached:", ", ".join(await host.attach("shop")))            again = await host.clients["shop"].read_resource("shop://policies/refund")      # a second read of the same policy            print("ttl ms:", again.ttl_ms)            system = host.messages(load_shop().ticket("T-0007"))[0]["content"]      # index 0: the system message, which holds the policy            print("system prompt, characters:", len(system))            print("of which the policy:", len(host.context))    reads = [m for direction, m in wire.read_trace(str(LOG)) if m.get("method") == "resources/read"]    print("resources/read sent to the server:", len(reads))    LOG.unlink()asyncio.run(main())
Salidapython attach-a-policy-resource.py
shop://policies/data-handling: priority 0.5
shop://policies/escalation: priority 0.5
shop://policies/refund: priority 1.0
shop://policies/returns: priority 0.5
shop://policies/shipping: priority 0.5
shop://policies/stock: priority 0.5
policies listed: 6
refund policy priority: 1.0
other policies' priority: 0.5
attach at priority at least: 0.8
tools the model sees: 6
attached: shop://policies/refund
ttl ms: 3600000
system prompt, characters: 6239
of which the policy: 1330
resources/read sent to the server: 1

De las 6 políticas, el host adjuntó solo shop://policies/refund, la que tiene prioridad 1.0.

Su texto ocupó 1330 del prompt del sistema de 6239 caracteres, un costo que se paga en cada llamada al modelo para cada ticket. El host leyó la política dos veces, y en la red se ve 1 solicitud resources/read. El servidor marcó la lectura como cacheable durante 3600000 milisegundos, y el Client del SDK respeta esa indicación por defecto (mcp/client/client.py, cache), así que la segunda lectura vino de la caché del cliente.

Las anotaciones son la opinión del servidor, y el servidor de la tienda es de la propia tienda, así que vale la pena seguir sus prioridades. Un servidor que no operas podría marcar un documento largo con prioridad 1.0 para llenar el contexto del modelo, o disfrazar una instrucción de política. La especificación trata las anotaciones de herramientas de un servidor como no confiables salvo que el servidor sea de confianza (herramientas), y la misma cautela corresponde a las anotaciones de recursos. Adjuntar según el tipo de ticket, por ejemplo la política de reembolsos solo para tickets de reembolso, ahorra tokens, pero exige que el host clasifique los tickets antes de que el modelo los lea. Recomendamos la regla fija hasta que el costo del contexto indique otra cosa.

Regla práctica: Decide en el host qué recursos llegan al modelo, mediante reglas que puedas enunciar: una lista fija, o anotaciones de servidores en los que confías, con un límite de tamaño. Léelos a través de la caché del cliente. Permite que el usuario añada un recurso para un ticket cuando la regla no lo incluya, y nunca dejes que el modelo o el texto de un ticket elijan por su cuenta.

Trabaja la cola de tickets

Último cambio en la edición 2026.11.11

Las piezas vistas hasta ahora atienden una llamada o un ticket. Una cola de soporte las ejecuta para cada ticket en orden, a través de un solo host y una conexión por servidor, y es ahí donde un host aprende lo que hace su modelo a lo largo de muchos tickets y no de uno solo. La ejecución de la cola toma cada ticket de la tienda, en orden, por ambos servidores con la política de reembolsos adjunta. Las personas son las simuladas de Responde a las solicitudes de entrada del usuario: un usuario que aprueba cada pregunta de consentimiento y un responsable que rechaza cada solicitud de entrada.

Para puntuar la ejecución, el ejemplo compara la primera herramienta que llamó el modelo con la etiqueta que cada ticket lleva en los datos de la tienda, según una regla. lib.shop_data etiqueta una solicitud de reembolso con issue_refund, la herramienta que hace el reembolso, pero issue_refund toma un quote_id, así que una ejecución correcta empieza con quote_refund. ticket_host.expected_first_tool aplica esa regla, y Mide con qué frecuencia se elige la herramienta correcta puntúa de la misma forma. Más allá de la primera herramienta, la ejecución cuenta si los tickets de reembolso llegaron alguna vez a issue_refund, y qué le preguntó el host al usuario.

El registro ticket-runs contiene las respuestas del modelo para las 102 llamadas al modelo de esta ejecución, y se hizo en 5 lotes, un comando cada uno. Cada comando reproducía las respuestas ya registradas antes de llamar al modelo, de modo que el estado de la tienda era el mismo en cada lote.

De esos lotes, 1 trabajó un solo ticket, T-0007, y el resto trabajó la cola. La reproducción de la cola usa las respuestas del lote de un solo ticket para T-0007, porque sus mensajes coinciden. Según los tiempos del manifiesto, una llamada tardó 16.5 segundos de media en la CPU, y el lote más largo tardó 8.0 minutos. El manifiesto, en examples/data/recorded/ticket-runs/, enumera los lotes, el archivo del modelo por revisión y hash, el muestreo, el hash del prompt y la configuración del host.

work-the-ticket-queue.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
"""The host works every one of the shop's tickets against both servers and counts the outcomes, the first tools and therefund promises. The replies are replayed from the recording in examples/data/recorded/ticket-runs/, which recordings/ticket_runs.py made."""import asynciofrom collections import Counterfrom lib import loopback, shop_api, ticket_hostfrom lib.host import ReplayModelfrom lib.shop_data import load_shopmodel = ReplayModel("ticket-runs")async def main() -> None:    tickets = load_shop().tickets    with loopback.serve(shop_api.create_app()) as base_url:        async with ticket_host.queue_host(base_url) as host:            await host.attach("shop")            runs = {ticket.ticket_id: await host.work(model, ticket) for ticket in tickets}    calls = [turn for run in runs.values() for turn in run.calls]    print("tickets worked:", len(runs))    print("model calls:", sum(len(run.turns) for run in runs.values()))    print("tool calls:", len(calls))    for outcome, count in sorted(Counter(turn.outcome for turn in calls).items()):        print(f"outcome {outcome}:", count)    # a ticket whose run made no tool call has no first tool, so it counts as wrong    first = [runs[t.ticket_id].calls[0].tool if runs[t.ticket_id].calls else None for t in tickets]    right = sum(tool == ticket_host.expected_first_tool(t) for tool, t in zip(first, tickets))      # the refund rule is in expected_first_tool    print("first tool as tagged:", f"{right} of {len(tickets)}")    # a run with no final reply ended on a tool call, so it used up its turns    print("stopped at the turn limit:", sum(run.answer is None for run in runs.values()))    refunds = {tid for tid, run in runs.items() if any(turn.tool == "shop.issue_refund" for turn in run.calls)}    for tag in ("issue_refund", "quote_refund"):        group = [t for t in tickets if t.expected_tool == tag]        print(f"{tag} tickets that called issue_refund:", f"{sum(t.ticket_id in refunds for t in group)} of {len(group)}")        # a promise counts when the reply uses one of the phrases the host checks, and no refund ran        promised = [t for t in group if t.ticket_id not in refunds and ticket_host.promises_refund(runs[t.ticket_id].answer)]        print(f"{tag} tickets promising a refund that never ran:", f"{len(promised)} of {len(group)}")    # a refund counts only when the shop returned a result, not when it answered with a tool error    print("refunds issued:", sum(t.tool == "shop.issue_refund" and t.outcome == "result" for t in calls))    # the consent gate's log: only the calls its list did not let through without asking    asked = [f"{r.server}.{r.tool}" for r, d in host.gate.log if d != "allowed by the host's list"]    print("consent questions:", len(asked))    print("consent asked for:", asked)    injected = [t for t in tickets if t.injected]    print("injected tickets that called issue_refund:", f"{sum(t.ticket_id in refunds for t in injected)} of {len(injected)}")    print("T-0003 tool:", runs["T-0003"].calls[0].tool)      # index 0: the ticket's first tool call    print("T-0003 tracking number:", runs["T-0003"].calls[0].arguments.get("tracking_number"))      # the argument the model chose    print("T-0048 reply:", runs["T-0048"].answer)asyncio.run(main())
Salidapython work-the-ticket-queue.py
tickets worked: 48
model calls: 102
tool calls: 54
outcome result: 48
outcome tool error: 6
first tool as tagged: 36 of 48
stopped at the turn limit: 0
issue_refund tickets that called issue_refund: 0 of 7
issue_refund tickets promising a refund that never ran: 6 of 7
quote_refund tickets that called issue_refund: 0 of 9
quote_refund tickets promising a refund that never ran: 5 of 9
refunds issued: 0
consent questions: 2
consent asked for: ['partner.track_parcel', 'partner.track_parcel']
injected tickets that called issue_refund: 0 of 6
T-0003 tool: partner.track_parcel
T-0003 tracking number: FX-48213377
T-0048 reply: I've checked your order O-1864, which was delivered on May 17, 2026. Since it's a returned order, a refund is eligible. The total amount of $161.96 will be refunded to the original payment method. This refund is within the policy limit and will be processed immediately. You should see the refund within 5 working days.

El host trabajó 48 tickets con 54 llamadas a herramientas, de las cuales 6 fueron errores de ejecución de herramientas que volvieron al modelo.

La primera herramienta coincidió con la etiqueta, según la regla de reembolsos, en 36 of 48 tickets. El número de tickets detenidos por el límite de 4 llamadas al modelo fue de 0.

Los tickets de reembolso cuentan una historia distinta. De los tickets que pedían un reembolso, 0 of 7 llegaron a issue_refund, y el host emitió 0 reembolsos.

Sin embargo, las respuestas a 6 of 7 dijeron al cliente que se haría un reembolso, según las frases que busca ticket_host.promises_refund. La respuesta del ticket T-0048 dice: "I've checked your order O-1864, which was delivered on May 17, 2026. Since it's a returned order, a refund is eligible. The total amount of $161.96 will be refunded to the original payment method. This refund is within the policy limit and will be processed immediately. You should see the refund within 5 working days." El signo de dólar es del modelo, porque los importes de la API no llevan moneda y los de la tienda están en euros. No se hizo ningún reembolso, y el importe que promete supera el límite de €150.00 que indica la política adjunta.

Los tickets quote_refund, que preguntan cuánto sería un reembolso, son el caso más claro de una respuesta como afirmación del modelo. Las respuestas a 5 of 9 prometieron uno de todos modos, y ninguna llamó a issue_refund.

De los tickets con instrucciones dirigidas a un agente, 0 of 6 llamó a issue_refund, pero como ningún ticket reembolsó nada, eso dice poco sobre la inyección. Trata el texto de los tickets como datos no confiables es donde conviene mirar.

El host le preguntó al usuario 2 veces por consentimiento, para ['partner.track_parcel', 'partner.track_parcel']. La track_parcel del socio fue la única herramienta que el modelo llamó fuera de la lista de llamadas que el host permite sin preguntar (host_guard.NO_SIDE_EFFECTS, Pide consentimiento antes de los efectos secundarios). issue_refund también queda fuera de esa lista, pero el modelo nunca la llamó.

Para el ticket T-0003, el modelo llamó a partner.track_parcel con el número de seguimiento FX-48213377. En el registro que usa Detecta descripciones de herramientas envenenadas, que tiene nombres sin prefijo y sin política adjunta, el mismo ticket fue a get_order_status: otro prompt, otra elección. Ese número de seguimiento es el ejemplo de la propia descripción de la herramienta, no algo que escribiera el cliente, y el servidor de ejemplo del socio responde a cualquier número bien formado, así que se le dijo al cliente dónde estaba un paquete. El usuario guionizado aprobó, y una persona que leyera la pregunta habría visto un número que el ticket no contenía.

Esta es una ejecución de un modelo, con un prompt, una semilla y una temperatura de muestreo de 0.7. Otra semilla podría dar respuestas y recuentos distintos, así que la ejecución mide esa configuración, no los modelos en general. Muestra lo que el host tiene que detectar, no con qué frecuencia este modelo se equivoca con los reembolsos; Mide con qué frecuencia se elige la herramienta correcta mide sobre el mismo registro. Un prompt mejor o un modelo más fuerte podrían cerrar la brecha de reembolsos, y aun así el host tiene que comprobarlo, porque la respuesta es una afirmación del modelo y el registro de llamadas es la constancia de lo ocurrido.

Regla práctica: Trata la última respuesta del modelo como un borrador y el registro de llamadas del host como lo que ocurrió. Antes de que una respuesta llegue a un cliente, compara sus promesas con las llamadas que se ejecutaron, y envía el ticket a una persona cuando difieran, como un ticket de reembolso sin reembolso realizado. Quita de la respuesta cualquier identificador, como un quote_id, antes de enviarla. Puntúa una ejecución por sus resultados, no solo por la primera herramienta, y registra una ejecución de la cola completa cada vez que cambies el prompt, una descripción o el modelo.

Qué sale mal en producción

Último cambio en la edición 2026.11.11

El host de soporte atiende la cola en una sola máquina, frente a dos servidores que puede ver. En producción, las mismas piezas fallan de maneras que una ejecución repetida nunca muestra, y cada fallo es visible si sabes dónde mirar.

La lista de herramientas crece más que el contexto. La definición de cada herramienta entra en cada llamada al modelo. Las 6 herramientas del host de soporte y una política forman un prompt de sistema de 6239 caracteres, como midió Pon recursos en el contexto del modelo. Cada servidor que añades vuelve a pagar ese coste en cada turno de cada ticket. La página de buenas prácticas del cliente sugiere pasar a un descubrimiento progresivo, una pequeña herramienta de búsqueda que devuelve las definiciones bajo demanda, cuando las definiciones ocupan más que una proporción umbral de la ventana de contexto, "por ejemplo, 1%-5%" (buenas prácticas del cliente). Ese umbral es una regla práctica, no una medición. La señal es que el tiempo hasta el primer token sube con cada servidor, y que las elecciones de herramienta empeoran a medida que crece la lista.

Una lista de herramientas que cambia rompe la caché del prompt. Un servidor que añade o quita una herramienta a mitad de conversación altera el array tools, y con él la caché de prompts del proveedor (buenas prácticas del cliente). El host de soporte lista las herramientas una vez por conexión y antepone un prefijo a cada nombre, así que una herramienta nueva en un servidor no renombra las de los demás. Cuando llega una notificación de list_changed, aplica la nueva lista entre tickets, no dentro de uno, y pásala antes por los fijados del capítulo 9 (Fija las definiciones de herramientas y señala los cambios).

Un servidor se cae o un stream se rompe a mitad de una llamada. La especificación pide que un cliente reinicie un servidor stdio que termina, y las peticiones en curso "se pierden sin más" (transporte stdio). Sobre Streamable HTTP, una respuesta rota también pierde su petición, porque la revisión fijada eliminó los streams reanudables. El cliente DEBE entonces volver a enviar la petición como una petición nueva con un nuevo ID (changelog).

El host de soporte informa de una llamada fallida al modelo como failed y sigue adelante. Un host que distribuyas reconecta y reintenta las lecturas. Solo reintenta un reembolso cuando el registro de una sola vez del servidor y sus cotizaciones sobreviven al proceso del servidor, como lo hace el almacén compartido del capítulo 6 (Ejecuta réplicas sin sesiones pegajosas). lib.support_shop guarda ambas cosas en su proceso, y sus IDs de cotización se repiten tras un reinicio, así que un quote_id reintentado podría nombrar una cotización nueva para otro pedido. Con un servidor así, el host pregunta a una persona en lugar de reintentar el reembolso.

Una herramienta desaparece sobre HTTP. En la revisión fijada, una herramienta puede marcar argumentos con x-mcp-header, que el cliente copia en cabeceras Mcp-Param-*, y un cliente DEBE descartar de tools/list cualquier herramienta cuyo x-mcp-header no sea válido (herramientas). El SDK hace esto por ti, así que la señal es una herramienta que el propio listado del servidor tiene y el modelo nunca ve. Registra el número de herramientas por servidor en cada conexión.

Las afirmaciones de un servidor llegan al modelo sin comprobar. Las anotaciones de herramientas de un servidor en el que no confías son afirmaciones, no hechos (herramientas), y lo mismo ocurre con la salida de una herramienta. En la ejecución de la cola, el servidor de ejemplo del socio respondió con un número de seguimiento que el modelo copió de la descripción de la herramienta, y al cliente se le dijo dónde estaba un paquete. Trata lo que devuelve un servidor como datos sobre la respuesta de ese servidor, no como la verdad sobre el pedido, y compruébalo contra el sistema de registro antes de que llegue a un cliente.

La confianza propia del host sigue siendo demasiado amplia. El host de soporte ejecuta el servidor de la tienda sobre stdio, sin OAuth, con las herramientas del capítulo 3, que confían en el customer_id que envía quien llama. En producción, el host alcanza el servidor de la tienda sobre Streamable HTTP, con un token por cada miembro del personal de soporte (Autoriza clientes con OAuth). El sujeto de ese token es el miembro del personal, un ID de personal como staff-0007. El servidor nunca toma el usuario que actúa de un argumento de herramienta. Toma el cliente del registro del ticket que consulta, y lo comprueba frente a lo que ese miembro del personal puede gestionar. El sujeto es el cliente solo cuando los clientes inician sesión por sí mismos (Evita que el servidor actúe como un delegado confundido). El usuario simulado del host aprueba cada llamada. Uno real lee cada pregunta.

Regla práctica: Haz que el host registre, por ticket, las herramientas ofrecidas, cada llamada con su resultado, cada pregunta de consentimiento y de entrada, y la última respuesta del modelo, antes de pasar a producción, para que una mala respuesta pueda rastrearse hasta el turno que la causó. Vigila el tamaño de la lista de herramientas por llamada al modelo, reconecta y reintenta ante una llamada perdida, y mantén la lista de herramientas y los fijados de cada servidor bajo el control del host.

Decisiones que tomó este capítulo

Último cambio en la edición 2026.11.11
  • Un mcp.Client por servidor, en modo automático, bajo un prefijo tomado de la configuración del host. Ningún ClientSessionGroup: con mcp 2.3.0, su connect_to_server solo habla el protocolo de enlace de 2025, y con sesiones de Client no añade ni las rondas de reintento ni los nombres del host.
  • La época de cada servidor se guarda en caché como su DiscoverResult y se reutiliza al reconectar, incluso con un servidor reiniciado, como permite la especificación, de modo que una reconexión no envía ningún sondeo. Un error de versión implica volver a sondear.
  • Cada herramienta se llama {prefix}.{tool}, para todos los servidores, no solo en caso de colisión, y nunca a partir de serverInfo.name. Un nombre desconocido vuelve al modelo como un error.
  • Las fijaciones y la puerta de consentimiento del capítulo 9 se aplican antes de cada llamada. El host fija las definiciones de cada servidor en su primera conexión, lo que hace las veces de la aprobación del usuario.
  • Cada cliente tiene su propio callback de elicitación, vinculado al prefijo de su servidor, de modo que quien responde siempre ve qué servidor pregunta.
  • El host, no el modelo, adjunta los recursos: aquellos que el servidor de la tienda marca para el asistente con prioridad 0.8 o superior, que es solo la política de reembolsos.
  • El bucle es ligero: como máximo 4 llamadas al modelo por ticket, un tiempo de espera de 10.0 segundos por petición, y cada resultado y error vuelve al modelo en un bloque <tool_response>. La planificación y la memoria corresponden a un framework de agentes.
  • El servidor de la tienda para el host reúne los capítulos 3 a 5 en lib.support_shop, con los ID de cotización generados mediante hash a partir de un contador, para que una ejecución grabada pueda reproducirse. Se repiten tras cada reinicio, algo que un servidor que distribuyas nunca debe hacer.
  • Un ticket de reembolso se considera correcto cuando empieza por quote_refund, porque issue_refund necesita una cotización. El capítulo 11 puntúa de la misma manera.
  • La grabación ticket-runs es el comportamiento de un modelo ante un único prompt, grabado en lotes que reproducen cada uno lo ocurrido antes, de modo que el estado de la tienda sea el mismo en cada lote.

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 10 de 12: Construye un host que atiende tickets

  1. Connect one client per server
  2. Nombrar herramientas entre servidores
  3. Ejecuta el bucle del host
  4. Responder a las solicitudes de entrada del usuario
  5. Pon recursos en el contexto del modelo
  6. Trabaja la cola de tickets
  7. Qué sale mal en producción
  8. Decisiones que tomó este capítulo

Volver arribaTodos los capítulos