MCP end to end

Unos 25 minutos de lectura, con 5 ejemplos en 7 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

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

By the end of this chapter you can put an existing HTTP API behind a Model Context Protocol server over stdio, call its tool from a client, read every message the two exchange, and let a model choose the tool through a small host. Every example runs on one machine; the chapter's claims hold for revision 2026-07-28 of the specification and for mcp 2.3.0, the Python SDK.

A customer writes to Fernhill Supply, a small online shop for kitchen and garden goods, to ask where an order is. The answer lives in Fernhill Supply's systems, not in the ticket, so a model in the support team's host can answer only if something lets it look the order up. This chapter takes on that problem, and Meet the shop and its API introduces the shop in full.

The Model Context Protocol (MCP) is how an application that uses a model gets tools and data from programs it didn't write. Three roles share the work, and the book keeps their names exact. The host is the application the user works in, such as a support desk or a coding assistant. A client is the host's connection to one server. A server exposes capabilities, such as tools a model can call (specification overview). The messages between a client and a server are JSON-RPC 2.0.

This chapter builds a rough version of the whole thing: an API, a server with one tool, a client, a wire trace and one recorded model choice. Each later chapter makes one of those parts solid.

Conoce la tienda y su API

Último cambio en la edición 2026.11.11

Un servidor MCP rara vez parte de cero. La mayoría de los equipos que lo necesitan ya tienen una API HTTP con sus propios datos, autenticación y clientes, y la función del servidor es poner parte de ella al alcance de un modelo. Así que lo primero que debes tener es la API que vas a envolver, en funcionamiento y accesible desde tus ejemplos.

Cada capítulo trabaja con esta tienda, Fernhill Supply, a la que llamamos la tienda. La tienda es ficticia y no representa a ningún negocio real; su dominio, fernhill.example, es un nombre reservado que nunca se resuelve. Su equipo de soporte responde tickets de clientes, y la mayoría de los tickets requiere consultar los sistemas de la tienda: dónde está un pedido, si un producto tiene existencias o cuánto costaría un reembolso. La meta del libro es un host que lea esos tickets y llame a las herramientas de la tienda para responderlos.

La tienda ya cuenta con el "antes" que envuelve cada capítulo: la API de la tienda, una API HTTP para pedidos, existencias y reembolsos que verifica una clave de API en el encabezado X-API-Key. Sus registros son los datos de la tienda, generados por el código del propio libro a partir de una semilla fija, de modo que cada ejecución ve los mismos clientes, pedidos y tickets. Tres módulos compartidos en examples/lib/ contienen esta configuración, para que los ejemplos sean breves:

  • lib.shop_data genera los datos de la tienda. load_shop() devuelve sus clientes, productos, niveles de existencias, pedidos, reembolsos y tickets como dataclasses de Python.
  • lib.shop_api es la API de la tienda, una aplicación Starlette sobre esos datos.
  • lib.loopback sirve una aplicación en 127.0.0.1 en un puerto libre y la detiene cuando termina el bloque.

Antes de envolver la API, ejecútala como lo haría cualquier cliente: una vez con la clave, una vez sin ella y una vez para un pedido que no existe.

start-the-shop-api.py Python 3.12.15 · httpx2 2.16.2 · starlette 1.10.0 · uvicorn 0.54.0 Superado
"""Start the shop's existing HTTP API on loopback and call it three ways: with its key, without it, and for an order that doesn't exist. The point rests on the `without key` line, which shows the API refuses a caller it can't identify."""import httpx2from lib import loopback, shop_apifrom lib.shop_data import SHOP_SEED, load_shopshop = load_shop()  # one fixed seed, so every run sees the same customers, orders and ticketsprint("seed:", SHOP_SEED)print("customers:", len(shop.customers))print("products:", len(shop.products))print("orders:", len(shop.orders))print("tickets:", len(shop.tickets))with loopback.serve(shop_api.create_app()) as base_url:  # serves on 127.0.0.1 at a free port until the block ends    # the API checks this header; DEMO_API_KEY is the key the shop's API accepts    response = httpx2.get(f"{base_url}/orders/O-2476", headers={"X-API-Key": shop_api.DEMO_API_KEY})    order = response.json()    print("with key:", response.status_code)    print("order status:", order["status"])    print("shipped on:", order["shipped_on"])    print("total:", order["total"])    print("without key:", httpx2.get(f"{base_url}/orders/O-2476").status_code)  # no header at all    # O-7144 is a well-formed ID that the generated orders do not contain    print("unknown order:", httpx2.get(f"{base_url}/orders/O-7144",                                       headers={"X-API-Key": shop_api.DEMO_API_KEY}).status_code)
Salidapython start-the-shop-api.py
seed: 4217
customers: 240
products: 64
orders: 1500
tickets: 48
with key: 200
order status: shipped
shipped on: 2026-06-24
total: 99.00
without key: 401
unknown order: 404

La semilla es 4217, y la salida junto al ejemplo cuenta los clientes, productos, pedidos y tickets que produce esa semilla. Los correos están en example.com, los teléfonos se enmascaran a dos dígitos, y el pago muestra únicamente "card ending" con los últimos cuatro dígitos de una tarjeta de prueba publicada. La ficha de datos en examples/data/shop/README.md enumera todos los campos.

Con la clave, la API responde 200: el pedido O-2476 tiene el estado shipped y se envió el 2026-06-24, por un total de €99.00. La tienda expresa todos los precios en euros, y su API envía los importes como decimales simples, sin código de moneda.

Sin la clave responde 401, y un pedido que no existe recibe 404. Esas tres respuestas son el contrato que el servidor MCP debe respetar. El servidor guardará la clave, llamará al mismo endpoint, GET /orders/{order_id}, y convertirá sus respuestas en algo que un modelo pueda leer; no volverá a implementar la lógica de los pedidos.

Regla práctica: envuelve la API que ya ejecutas y mantenla como sistema de registro. El servidor MCP debe ser un adaptador ligero que llame a la API con sus propias credenciales y traduzca las respuestas, de modo que la validación, la autorización y los registros de la API sigan funcionando para todos los clientes, no solo para los modelos. Construye directamente sobre la base de datos solo cuando no exista una API que envolver, y en ese caso mantén las reglas de negocio en un único lugar que compartan ambos tipos de cliente.

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

Wrap one endpoint as a tool

Último cambio en la edición 2026.11.14

The shop's API from the previous section answers "what is the status of order O-2476" for any HTTP client. To answer that for a model, the shop needs an MCP server that exposes the lookup as a tool: a named action with a description and a JSON Schema for its inputs, which a model can decide to call (tools). The server publishes its tools in tools/list, and a client runs one with tools/call.

In the Python SDK the server class is MCPServer, imported from mcp.server.mcpserver. The SDK's 1.x releases called it FastMCP, and at 2.3.0 importing mcp.server.fastmcp fails with a pointer to the migration guide. You register a tool with @server.tool(), parentheses included, since the bare @server.tool raises a TypeError that asks for them (mcp source, mcp/server/mcpserver/server.py). The SDK takes the tool's name from the function, its description from the docstring and its input schema from the type hints. server.run() serves over stdio, where the client starts the server as a subprocess and the two exchange messages on standard input and output, which is run()'s default.

The shop's first server is called shop-orders, and its one tool, get_order_status, wraps GET /orders/{order_id}. It reads the API's address and key from its environment, so they never appear in the code or on the wire. Server examples follow one pattern: the file defines the server, and with no arguments it starts a client that launches the same file with --serve and lists the tools. Run it to see the tool the way a model receives it.

order-status-server.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 shop's first MCP server: one tool, get_order_status, that wraps GET /orders/{order_id} on the shop's API. The point rests on the description and schema lines, the only parts of the tool a model reads."""import asyncioimport jsonimport osimport sysimport httpx2from mcp import Client, StdioServerParametersfrom mcp.server.mcpserver import MCPServerfrom mcp.server.mcpserver.exceptions import ToolErrorserver = MCPServer("shop-orders", version="0.1.0")@server.tool()def get_order_status(order_id: str) -> dict:    """Look up one of the shop's orders by its ID, such as O-1873: its status, dates, lines and total."""    # read on each call: a missing variable raises KeyError here, and the SDK reports only a generic error    response = httpx2.get(f"{os.environ['SHOP_API_URL']}/orders/{order_id}",                          headers={"X-API-Key": os.environ["SHOP_API_KEY"]},                          timeout=5.0)  # seconds; a slow shop API fails this call instead of holding the worker    # the shop answers 404 for an order it doesn't have, so the model gets a message it can act on    if response.status_code == 404:        raise ToolError(f"The shop has no order {order_id}. Order IDs look like O-1873.")    response.raise_for_status()  # any other failure, such as a wrong key, stays on the server as an HTTPError    return response.json()async def show_tools() -> None:    from lib import loopback, shop_api    with loopback.serve(shop_api.create_app()) as base_url:        # the API's address and key are the only variables the server gets        params = StdioServerParameters(command=sys.executable, args=[__file__, "--serve"],                                       env=shop_api.server_env(base_url))        async with Client(params) as client:            for tool in (await client.list_tools()).tools:                print("tool:", tool.name)                print("description:", tool.description)                print("input schema:", json.dumps(tool.input_schema))if __name__ == "__main__":    if "--serve" in sys.argv:        server.run()                  # stdio is the default transport    else:        asyncio.run(show_tools())
Salidapython order-status-server.py
tool: get_order_status
description: Look up one of the shop's orders by its ID, such as O-1873: its status, dates, lines and total.
input schema: {"type": "object", "properties": {"order_id": {"title": "Order Id", "type": "string"}}, "required": ["order_id"], "title": "get_order_statusArguments"}

What the client sees is the tool's definition. Its name is get_order_status, its description is the docstring word for word, and its input schema says that order_id is a required string. The SDK built that schema from the order_id: str hint and added title fields of its own, such as "Order Id". The model reads only the description and the schema, so the docstring is written for a model: what the tool does, what an ID looks like and what comes back. Write descriptions the model reads measures how much that wording matters.

The function is a plain def that makes a blocking HTTP call, and at 2.3.0 the SDK runs synchronous tools on a worker thread, so a slow call to the shop's API doesn't stall the server's other requests (migration guide). The function also raises ToolError on a 404, and the SDK passes a ToolError's message to the client as a failed tool result. Any other exception becomes a generic Error executing tool message, and its text stays on the server (mcp/server/mcpserver/tools/base.py). Call the tool from a client shows both kinds of failure.

The server needs no HTTP library of its own, because the SDK depends on httpx2, a fork of HTTPX, at 2.3.0 (migration guide). The tool uses only httpx2.get(), the response's status_code, raise_for_status() and json(), which work as they do in HTTPX.

Working rule: Start with one read-only tool for one endpoint, and write its docstring for a model: what it does, what its inputs look like, what it returns. Raise ToolError with a message that tells the model what to do differently, and let unexpected exceptions stay generic so internal details never leave the server. Past a handful of endpoints, shape the tools around the tasks the model has to do rather than one per endpoint (Shape tools around tasks, not endpoints).

Llama a la herramienta desde un cliente

Último cambio en la edición 2026.11.11

Envuelve un endpoint como herramienta definió shop-orders pero nunca lo ejecutó, porque un servidor stdio solo se ejecuta cuando algo lo lanza. En el caso de la tienda, ese algo es el host, y la parte del host que se comunica con un servidor es un cliente. Sobre stdio, un cliente inicia el servidor como un subproceso, escribe solicitudes en su entrada estándar y lee las respuestas de su salida estándar (transporte stdio).

En la revisión fijada no hay handshake ni sesión. Cada solicitud es independiente y lleva la versión del protocolo y las capacidades del cliente en su campo _meta, y la especificación dice que un servidor "NO DEBE depender de solicitudes previas sobre la misma conexión para establecer contexto" (protocolo base). La misma página también dice que una conexión abierta, como un proceso stdio, no es una conversación ni una sesión. Las revisiones hasta 2025-11-25 abrían cada conexión con un handshake initialize; Elimina initialize e identificadores de sesión explica cómo dejarlo.

El cliente de alto nivel del SDK de Python es mcp.Client, y dado un StdioServerParameters lanza el comando como subproceso. En su mode="auto" predeterminado primero envía server/discover en la revisión fijada. Recurre al antiguo handshake initialize siempre que la prueba expire o falle con cualquier error, excepto un -32022 cuya lista de versiones no comparte ninguna con la del cliente, el caso que explica Maneja una versión que el servidor no soporta (mcp/client/client.py, mcp/client/_probe.py). Un servidor de la era 2025 responde a server/discover con un error, así que recibe el antiguo handshake. Usa Client, no un initialize() llamado a mano sobre un ClientSession de bajo nivel, que siempre habla el handshake anterior a 2026 (guía de migración).

El comando es sys.executable, el Python que ejecuta el ejemplo, en lugar de "python", para que el servidor se ejecute en el mismo entorno con los mismos paquetes fijados, sea cual sea el Python que aparezca primero en el PATH. La dirección y la clave de la API de la tienda van en env= de forma explícita, porque el cliente stdio no pasa el entorno del proceso padre. En Linux y macOS solo pasa HOME, LOGNAME, PATH, SHELL, TERM y USER, además de lo que le indiques (mcp/client/stdio.py). El cliente también se identifica como shop-host, para que los registros del servidor y el tráfico muestren quién llamó.

El siguiente ejemplo hace tres llamadas para mostrar los fallos desde el lado del cliente: una para un pedido real, otra para un ID de pedido que no existe y otra desde un segundo cliente que olvida el entorno.

call-order-status.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
"""Launch the shop's server over stdio and call get_order_status for a real order and a wrong one, then for a server started without the shop's variables. The asserts pin the error flags the prose states: a real order is not an error, and a wrong ID is."""import asyncioimport jsonimport sysfrom mcp import Client, StdioServerParametersfrom mcp.types import Implementationfrom lib import loopback, shop_apiSHOP_HOST = Implementation(name="shop-host", version="0.1.0")  # the name the server's logs and the wire showasync def main() -> None:    with loopback.serve(shop_api.create_app()) as base_url:        env = {"SHOP_API_URL": base_url, "SHOP_API_KEY": shop_api.DEMO_API_KEY}  # the only two variables the server reads        # relative to the examples folder, where examples run, so the server file is found        params = StdioServerParameters(command=sys.executable, args=["order-status-server.py", "--serve"], env=env)        async with Client(params, client_info=SHOP_HOST) as client:            print("protocol revision:", client.protocol_version)            print("server:", client.server_info.name, client.server_info.version)            result = await client.call_tool("get_order_status", {"order_id": "O-2476"})            assert result.is_error is False        # a real order comes back as a result, not an error            # the tool returns the order as JSON text in its first content block            print("order status:", json.loads(result.content[0].text)["status"])            wrong = await client.call_tool("get_order_status", {"order_id": "O-7144"})            assert wrong.is_error is True          # an unknown order is a failed tool result, not an exception            print("wrong ID says:", wrong.content[0].text)        # no env=, so the server starts without the shop's variables and its tool fails at the first call        no_env = StdioServerParameters(command=sys.executable, args=["order-status-server.py", "--serve"])        async with Client(no_env, client_info=SHOP_HOST) as client:            broken = await client.call_tool("get_order_status", {"order_id": "O-2476"})            print("without env says:", broken.content[0].text)asyncio.run(main())
Salidapython call-order-status.py
protocol revision: 2026-07-28
server: shop-orders 0.1.0
order status: shipped
wrong ID says: Error executing tool get_order_status: The shop has no order O-7144. Order IDs look like O-1873.
without env says: Error executing tool get_order_status

La primera llamada funciona. El pedido real llega como un resultado normal, no como un error, con estado shipped, la misma respuesta que dio la API de la tienda directamente. En el proceso, el cliente y el servidor acordaron la revisión 2026-07-28, y la respuesta server/discover dio al cliente el nombre y la versión del servidor, shop-orders 0.1.0.

El ID incorrecto, O-7144, llega como un resultado marcado y no como una excepción, y su texto es el mensaje ToolError, con un prefijo añadido por el SDK. Un modelo que lee "Los ID de pedido tienen la forma O-1873" puede volver a preguntar al cliente. La tercera llamada falla de otra manera. El servidor se inició sin SHOP_API_URL, así que la herramienta lanzó un KeyError, y el cliente solo recibió Error executing tool get_order_status. El KeyError en sí fue a la salida de error estándar del servidor, donde un operador puede encontrarlo y un modelo no. Esa separación es deliberada, porque coloca una variable faltante en los registros del servidor y nunca en la conversación.

Regla práctica: Conecta con mcp.Client, lanza los servidores stdio con sys.executable y un env= explícito, y dale un nombre al cliente. Pasa cada variable que el servidor necesite y nada más de tu entorno, para que ningún servidor vea secretos destinados a otro programa. Cuando una herramienta falle solo con el mensaje genérico del SDK, lee la salida de error estándar del servidor antes de cambiar el cliente.

Lee los mensajes en el cable

Último cambio en la edición 2026.11.11

El cliente de la sección anterior ocultaba cada mensaje tras call_tool(). Cuando un servidor se comporta de forma incorrecta, o necesitas saber qué envía realmente la revisión fijada, lee los mensajes. Sobre stdio, cada mensaje es una línea de JSON-RPC en la entrada o salida estándar del servidor, sin saltos de línea incrustados. El servidor "MUST NOT" escribir en su stdout nada que no sea un mensaje MCP válido, y sus registros van a la salida de error estándar (transporte stdio).

Un rastro fiel necesita un subproceso real. El cliente en proceso del SDK, Client(server) dado un objeto de servidor, despacha las llamadas directamente en su modo automático predeterminado, sin enviar ningún JSON-RPC (mcp/client/client.py), así que no puede mostrarte el cable. El impresor de rastros del libro, lib.wire, coloca en cambio un pequeño relevo entre el cliente y el servidor: el cliente lanza el relevo, el relevo lanza el servidor real y copia cada línea en ambos sentidos sin cambios mientras la añade a un registro.

wire.print_trace() imprime después ese registro en orden, con mensajes numerados, flechas para la dirección (-> del cliente al servidor, <- de vuelta) e identificadores de petición renumerados para que la salida sea estable. Los valores bajo nombres que parecen secretos se imprimen como [redacted]; este rastro no tiene ninguno.

Para ver el cable, ejecuta la llamada para el pedido O-2476 del ejemplo de cliente a través del relevo. Tres de sus mensajes se imprimen completos, y los demás en una sola línea cada uno.

trace-first-call.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
"""Record every message the client and the shop's server exchange for one tool call, and print them in order. The point rests on the methods line: the exchange has no initialize."""import asyncioimport pathlibimport sysfrom mcp import Client, StdioServerParametersfrom mcp.types import Implementationfrom lib import loopback, shop_api, wireasync def main() -> None:    with loopback.serve(shop_api.create_app()) as base_url:        server = StdioServerParameters(command=sys.executable, args=["order-status-server.py", "--serve"],                                       env=shop_api.server_env(base_url))        pathlib.Path("wire.jsonl").unlink(missing_ok=True)   # the relay appends, so start each run empty        # the relay starts the server and copies every line both ways, appending each one to the log        params = wire.relay(server, log="wire.jsonl")        async with Client(params, client_info=Implementation(name="shop-host", version="0.1.0")) as client:            await client.list_tools()            await client.call_tool("get_order_status", {"order_id": "O-2476"})    # messages 1, 5 and 6 print in full; the rest on one line, with strings cut at 48 characters    messages = wire.print_trace("wire.jsonl", full=(1, 5, 6), depth=4, max_string=48)    print("messages:", len(messages))    print("methods:", ", ".join(m["method"] for m in messages if "method" in m))  # results carry no methodasyncio.run(main())
Salidapython trace-first-call.py
1. -> request server/discover (id 1)
{
  "jsonrpc": "2.0",
  "id": 1,
  "method": "server/discover",
  "params": {
    "_meta": {
      "io.modelcontextprotocol/protocolVersion": "2026-07-28",
      "io.modelcontextprotocol/clientInfo": {
        "name": "shop-host",
        "version": "0.1.0"
      },
      "io.modelcontextprotocol/clientCapabilities": {}
    }
  }
}
2. <- result (id 1) result: {"cacheScope": "private", "capabilities": "{…}", "resultType": "complete", "supportedVersions": "[…]", "ttlMs": 0, "_meta": "{…}"}
3. -> request tools/list (id 2) params: {"_meta": "{…}"}
4. <- result (id 2) result: {"cacheScope": "private", "resultType": "complete", "tools": "[…]", "ttlMs": 0, "_meta": "{…}"}
5. -> request tools/call (id 3)
{
  "jsonrpc": "2.0",
  "id": 3,
  "method": "tools/call",
  "params": {
    "name": "get_order_status",
    "arguments": {
      "order_id": "O-2476"
    },
    "_meta": {
      "io.modelcontextprotocol/protocolVersion": "2026-07-28",
      "io.modelcontextprotocol/clientInfo": {
        "name": "shop-host",
        "version": "0.1.0"
      },
      "io.modelcontextprotocol/clientCapabilities": {}
    }
  }
}
6. <- result (id 3)
{
  "jsonrpc": "2.0",
  "id": 3,
  "result": {
    "content": [
      {
        "text": "{\n  \"order_id\": \"O-2476\",\n  \"customer_id\": \"C-0…",
        "type": "text"
      }
    ],
    "isError": false,
    "resultType": "complete",
    "_meta": {
      "io.modelcontextprotocol/serverInfo": {
        "name": "shop-orders",
        "version": "0.1.0"
      }
    }
  }
}
messages: 6
methods: server/discover, tools/list, tools/call

Aquí no hay ningún handshake: no aparece initialize. El intercambio son 6 mensajes, y los métodos, en orden, son server/discover, tools/list, tools/call. Leyéndolos uno a uno:

  1. server/discover es la primera petición. Sus params contienen solo _meta, con tres entradas: io.modelcontextprotocol/protocolVersion, io.modelcontextprotocol/clientInfo con el nombre shop-host, y io.modelcontextprotocol/clientCapabilities, que está vacío porque este cliente no declara ninguna capacidad. Todo servidor debe implementar server/discover (descubrimiento).
  2. Su resultado enumera supportedVersions y las capabilities del servidor, y el _meta propio del servidor contiene io.modelcontextprotocol/serverInfo. El resultado también tiene resultType y dos indicaciones de caché, ttlMs y cacheScope, que explica Almacena en caché los resultados de lista.
  3. tools/list lleva el mismo _meta otra vez.
  4. Su resultado contiene la definición de la herramienta que imprimió el ejemplo de servidor.
  5. tools/call nombra la herramienta y da sus arguments, y una vez más incluye la versión del protocolo, el nombre del cliente y sus capacidades.
  6. Su resultado contiene el pedido como texto en content, con isError en falso y resultType en "complete".

Tres peticiones, cada una indicando quién pregunta y con qué revisión, porque ninguna petición puede apoyarse en la anterior.

Cada resultado lleva resultType, y "complete" marca una respuesta ordinaria. El otro tipo, una solicitud de entrada a mitad de una llamada, es el tema de Devuelve una solicitud de entrada en lugar de un resultado. Un cliente trata como completo un resultado sin ese campo, procedente de un servidor más antiguo (protocolo base). El servidor del SDK añade él mismo resultType y el sello serverInfo (mcp/server/runner.py).

Hay algo que falta a propósito en el rastro: la clave de API de la tienda. Llegó al servidor a través del entorno del subproceso, y el servidor la envió solo a la API de la tienda. La especificación quiere que los servidores stdio obtengan las credenciales del entorno, y no que sigan el flujo OAuth que Autoriza clientes con OAuth enseña para HTTP (protocolo base).

Regla práctica: Cuando una llamada se comporta de forma inesperada, traza el cable antes de leer el código del SDK: un relevo que copia y registra líneas funciona con cualquier cliente y cualquier servidor. Nunca escribas en la salida estándar desde un servidor stdio, ni siquiera un print() de depuración, porque el cliente lee allí cada línea como un mensaje. Usa logging, que el SDK envía a la salida de error estándar, o escribe tú mismo en la salida de error estándar.

Deja que un modelo elija la herramienta

Último cambio en la edición 2026.11.11

En el ejemplo de cliente, el código elegía la herramienta y sus argumentos. En el caso de la tienda, eso debe hacerlo un modelo. Las herramientas las controla el modelo. El host le muestra al modelo las herramientas disponibles, y el modelo decide cuál llamar y con qué argumentos (herramientas). El host sigue a cargo de todo lo demás. Construye el prompt, lee la respuesta del modelo, realiza la llamada a través de su cliente y decide qué hacer con el resultado.

El bucle del host del libro, lib.host, es un host pequeño que el libro mismo escribe, para que cada paso sea visible. Aquí realiza un turno: incorpora las herramientas del servidor en el prompt de sistema propio del libro, indicando el nombre, la descripción y el esquema de entrada de cada herramienta, y luego envía ese prompt y un ticket a un modelo y analiza la respuesta. Una respuesta que contenga un bloque <tool_call> con el nombre y los argumentos de una herramienta es una elección; cualquier otra respuesta es una contestación en palabras. El bucle mantiene el prompt y el análisis en el código del libro, no en una biblioteca de modelos, de modo que el mismo código sirva tanto para el modelo real cuando se hace una grabación como para la reproducción en los ejemplos.

Los ejemplos de este libro nunca llaman a un modelo, porque su salida no es determinista y los ejemplos deben ejecutarse sin conexión. Una grabación guarda las respuestas sin procesar del modelo en examples/data/recorded/, hechas una sola vez mediante un script en recordings/, y los ejemplos las reproducen con ReplayModel. La reproducción falla de forma explícita si han cambiado el prompt, el ticket o las herramientas. Cada grabación de este libro usa Qwen3-4B-Instruct-2507, un modelo abierto bajo la licencia Apache-2.0, cuantizado a 4 bits (Q4_K_M, en una conversión GGUF de terceros) y ejecutado en la CPU con llama.cpp, de modo que cualquiera pueda volver a hacer las grabaciones. El script recordings/pick_a_tool.py hizo la grabación de este capítulo, pick-a-tool, contra el mismo servidor y el mismo prompt, y su manifiesto indica la revisión y el hash del archivo del modelo.

La parte incierta es el modelo, así que el ejemplo le da tres tickets: uno cita un ID de pedido tal como lo escribe la tienda, otro da solo un número de pedido, y el tercero pregunta por existencias, algo que ninguna herramienta de este servidor puede responder.

host-picks-a-tool.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 book's host loop shows three tickets and the server's tools to a model, then calls the tool the model chooses, from recorded replies in examples/data/recorded/. The point rests on the three `tool` lines."""import asyncioimport jsonimport sysfrom mcp import Client, StdioServerParametersfrom mcp.types import Implementationfrom lib import loopback, shop_apifrom lib.host import ReplayModel, choose_toolfrom lib.shop_data import load_shopmodel = ReplayModel("pick-a-tool")  # answers only with the replies recorded for these exact messagesasync def main() -> None:    shop = load_shop()    with loopback.serve(shop_api.create_app()) as base_url:        params = StdioServerParameters(command=sys.executable, args=["order-status-server.py", "--serve"],                                       env=shop_api.server_env(base_url))        async with Client(params, client_info=Implementation(name="shop-host", version="0.1.0")) as client:            tools = (await client.list_tools()).tools            for ticket_id in ("T-0003", "T-0010", "T-0015"):                ticket = shop.ticket(ticket_id)                # the longest paragraph of the ticket, which holds the customer's question                print(f"{ticket_id} asks:", max(ticket.body.split("\n\n"), key=len))                choice = choose_tool(model, ticket, tools)                print(f"{ticket_id} tool:", choice.tool or "none")                if choice.tool is None:  # the model answered in words, so there is no call to make                    print(f"{ticket_id} reply:", choice.reply[:72] + "…")  # a reply can run long, so the output shows only its opening                    continue                print(f"{ticket_id} order id:", choice.arguments.get("order_id"))                result = await client.call_tool(choice.tool, choice.arguments)                print(f"{ticket_id} order status:", json.loads(result.content[0].text)["status"])asyncio.run(main())
Salidapython host-picks-a-tool.py
T-0003 asks: Can you tell me when O-1942 will arrive. I need it before the weekend
T-0003 tool: get_order_status
T-0003 order id: O-1942
T-0003 order status: shipped
T-0010 asks: where is my order 2496? its been ages and the tracking page says nothing
T-0010 tool: get_order_status
T-0010 order id: O-2496
T-0010 order status: shipped
T-0015 asks: Do you have enamelled casserole in stock? I'd want two of them
T-0015 tool: none
T-0015 reply: I don't have access to real-time inventory or stock levels for Fernhill …

El modelo eligió la consulta para los dos tickets que necesitan un pedido y se negó en el que necesita existencias. En el ticket T-0003 eligió get_order_status para el pedido que nombra el ticket, y la llamada del host encontró ese pedido shipped. El ticket T-0010 dio solo un número suelto, y aun así el modelo envió O-2496, la forma que muestran tanto la descripción como el prompt. Para la pregunta de existencias en T-0015, el modelo no llamó a ninguna herramienta, none, y dijo con palabras que no podía comprobar las existencias. Ese es el comportamiento correcto para un servidor que solo ofrece consultas de pedidos, y el capítulo 3 añade la herramienta check_stock que necesita el ticket.

Tres elecciones grabadas muestran que el bucle funciona. No miden con qué frecuencia un modelo elige bien. Escribe descripciones que el modelo lea compara descripciones con más tickets, y Mide con qué frecuencia se elige la herramienta correcta mide la precisión sobre toda la cola de tickets.

Este host llama a get_order_status sin preguntar a nadie, lo que se aparta de la especificación. La especificación pone el consentimiento en el host: los hosts "deben obtener el consentimiento explícito del usuario antes de invocar cualquier herramienta", y el propio MCP no puede hacerlo cumplir (visión general de la especificación). La página de herramientas añade que DEBERÍA haber siempre una persona en el bucle, capaz de denegar una llamada a herramienta (herramientas). Lo omitimos aquí porque la herramienta solo lee, desde un servidor que la tienda gestiona, y una llamada errónea no cambia nada. Recomendamos omitirlo solo en ese caso. Pide consentimiento antes de los efectos secundarios, en el capítulo sobre el modelo de seguridad de MCP, añade el paso de consentimiento.

Regla práctica: Mantén el prompt del host y el análisis de la respuesta del modelo en tu propio código, y prueba el bucle con respuestas grabadas en lugar de con un modelo en vivo. Guarda el texto sin procesar del modelo, no los objetos del SDK, para que una nueva versión del SDK no invalide una grabación, y haz que una reproducción falle cuando cambie su entrada. Pasa a un modelo en vivo solo para las ejecuciones de medición que decidan qué descripciones y qué modelo vas a publicar.

Qué sale mal en producción

Último cambio en la edición 2026.11.11

El primer servidor de la tienda funciona en una sola máquina. Al llevarlo a producción, las mismas pocas piezas fallan de unas cuantas maneras, cada una con una señal que conviene vigilar.

Cualquier cosa en la salida estándar rompe el canal. Una biblioteca que imprime un banner, o un print() olvidado durante la depuración, pone en la salida estándar del servidor una línea que no es JSON-RPC, algo que el transporte stdio prohíbe (transporte stdio). El cliente lo muestra como errores de análisis o respuestas perdidas, a menudo solo en la ruta de código que imprime. El registro propio del SDK va a la salida de error estándar (mcp/server/mcpserver/utilities/logging.py), así que dirige también el tuyo hacia allí.

El servidor hereda menos de lo que crees. El cliente stdio pasa una lista corta de variables permitidas y nada más (mcp/client/stdio.py), así que un servidor que funciona desde tu shell falla cuando un host lo lanza. La señal es la que mostró el ejemplo del cliente: un Error executing tool genérico en el cliente y un KeyError en la salida de error estándar del servidor. Pasa todas las variables en env=, y falla al arrancar si falta alguna, no en la primera llamada. El servidor de la tienda lee sus variables dentro de la herramienta a propósito, para que el ejemplo del cliente pudiera mostrar el fallo tardío; un servidor que entregues debería leerlas una sola vez, antes de atender peticiones.

El servidor muere a mitad de una llamada. La especificación pide que el cliente reinicie un servidor stdio que termine, y como el protocolo no guarda estado, «cualquier petición en curso se pierde sin más y el cliente puede reintentarla» (transporte stdio). mcp.Client no reinicia nada en 2.3.0: una llamada en curso falla con un MCPError que dice Connection closed, y el host debe abrir un nuevo Client y reintentar (mcp/client/stdio.py, mcp/shared/jsonrpc_dispatcher.py). Reintentar un get_order_status es inofensivo, pero reintentar un reembolso no lo es, por eso la herramienta de reembolsos de la tienda necesita una comprobación de una sola vez en el servidor (Mantén el estado de ida y vuelta a salvo de manipulaciones). Al apagarse, el cliente cierra la entrada estándar del servidor y espera; el SDK le concede 2 segundos antes de escalar a una señal (mcp/client/stdio.py), así que los servidores deben terminar con prontitud al llegar el fin de la entrada.

Un arranque lento cuesta tiempo y puede cambiar la revisión. El cliente del SDK espera 10 segundos la respuesta a server/discover (mcp/client/session.py). Un servidor que carga un modelo grande o abre muchas conexiones antes de leer su primer mensaje puede perder esa ventana en una máquina fría. El modo automático trata entonces el tiempo agotado como una sonda fallida y envía el antiguo saludo initialize, que no tiene límite de tiempo por defecto (mcp/client/_probe.py). Un servidor construido con este SDK que ya respondió a la sonda tardía rechaza initialize indicando sus versiones admitidas, y el cliente sondea una vez más, así que la conexión se establece con más de 10 segundos de retraso. Un servidor de otro SDK que también responde a initialize puede acabar en una revisión de 2025 sin ningún error. La señal es client.protocol_version, no un servidor caído. Realiza la preparación lenta de forma diferida, o después de que el servidor lea su entrada.

El otro lado habla una revisión de 2025. Client en modo automático recurre al saludo antiguo con un servidor de la era 2025. Tras recurrir al saludo antiguo, la conexión habla la revisión de 2025, así que no están presentes las funciones de la revisión fijada (registro de cambios), y client.protocol_version indica qué revisión obtuviste. Un servidor que no admite la versión del cliente responde con un error, que muestra Gestiona una versión que el servidor no admite. Cuando el error procede del servidor de otra persona, la traza de Lee los mensajes en el cable te indica qué revisión envió cada lado.

Otros lenguajes se quedan atrás o van por delante. La documentación de MCP enumera los SDK oficiales por niveles. El nivel 1 es TypeScript, Python, C#, Go, Rust y Ruby, y los niveles cambian con el tiempo (SDK). Un host en un lenguaje y un servidor en otro pueden implementar de forma distinta los detalles de una revisión, y el cable es el lugar donde se decide cuál es el correcto.

Regla práctica: En la máquina que lanza un servidor stdio en producción, comprueba tres cosas: que nada salvo JSON-RPC llega a la salida estándar, que cada variable que el servidor necesita se pasa explícitamente, y que el servidor responde a server/discover en un plazo de 10 segundos desde su arranque. Conserva la salida de error estándar del servidor en tus registros, porque ahí es donde van sus errores reales.

Decisiones que tomó este capítulo

Último cambio en la edición 2026.11.11
  • Los datos de la tienda provienen de una única semilla y terminan en una fecha fija, de modo que cada ejemplo del libro ve los mismos clientes, pedidos y tickets.
  • La API de la tienda sigue siendo el sistema de registro. El servidor MCP es un adaptador ligero que la llama con su propia clave.
  • Una herramienta de solo lectura, get_order_status, envuelve un único endpoint. Su docstring está escrito para un modelo.
  • Los fallos que el modelo puede resolver lanzan ToolError; las demás excepciones llegan al cliente como un mensaje genérico, y su detalle queda en la salida de error estándar del servidor.
  • Primero stdio, con el transporte por defecto de MCPServer.run(). Streamable HTTP llega en Servir sobre Streamable HTTP.
  • mcp.Client en su modo automático por defecto, nunca un ClientSession inicializado a mano, de modo que el primer mensaje es server/discover en la revisión fijada.
  • Los servidores se lanzan con sys.executable y un env= explícito, y las credenciales viajan en el entorno, nunca por el canal de comunicación (wire).
  • Las trazas provienen de un relé sobre un subproceso stdio real, porque el cliente en proceso no envía JSON-RPC.
  • El prompt y el análisis del bucle del host son código propio del libro, y los ejemplos reproducen grabaciones de Qwen3-4B-Instruct-2507, un modelo abierto ejecutado en la CPU.
  • Una grabación responde solo a los mensajes exactos que vio. Un prompt, ticket o lista de herramientas modificados hace fallar la reproducción en lugar de devolver una respuesta obsoleta.
  • No hay paso de consentimiento en este capítulo, una desviación de la especificación que aceptamos solo para una herramienta de solo lectura en un servidor que gestiona la tienda. El consentimiento llega en Pedir consentimiento antes de los efectos secundarios.

Este capítulo, en esta edición

Edición 2026.11.14Ejemplos verificados el 19 de nov de 2026Superan la prueba 5 de 5 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 1 de 12: MCP end to end

  1. Conoce la tienda y su API
  2. Wrap one endpoint as a tool
  3. Llama a la herramienta desde un cliente
  4. Lee los mensajes en el cable
  5. Deja que un modelo elija la herramienta
  6. Qué sale mal en producción
  7. Decisiones que tomó este capítulo

Volver arribaTodos los capítulos