Lo que MCP añade a una API
Unos 29 minutos de lectura, con 6 ejemplos en 11 secciones.
Traducido con IA. Verificado por personas en inglés. Cómo hacemos los libros
Traducido del libro en inglés, edición 2026.11.14. Lee el original
En esta página
- Separa el host, el cliente y el servidor
- Put each capability in the right primitive
- Las herramientas son acciones que elige el modelo
- Los recursos son datos que elige la aplicación
- Los prompts son plantillas que elige el usuario
- Carry the version and capabilities on every request
- Handle a version the server doesn't support
- Almacenar en caché los resultados de listas
- Keep an HTTP API where MCP adds nothing
- Qué sale mal en producción
- Decisiones que tomó este capítulo
Al terminar este capítulo podrás explicar qué hacen el host, el cliente y el servidor. Podrás colocar cada una de las capacidades de la tienda en la primitiva correcta del Model Context Protocol, leer la versión y las capacidades que transporta cada solicitud y decidir cuándo la tienda debe seguir usando una API HTTP sencilla. Sus afirmaciones y ejemplos se refieren a la revisión 2026-07-28 de la especificación y a mcp, el SDK de Python, en la versión 2.3.0.
Lo que este capítulo necesita de la tienda, la tienda en línea ficticia de Fernhill Supply de artículos para la cocina y el jardín, es una API HTTP cuya consulta de pedidos ya usa el host del equipo de soporte. MCP de extremo a extremo colocó esa consulta detrás de un servidor del Model Context Protocol (MCP), de modo que un modelo del host del equipo de soporte pudiera llamarla. Ese servidor tenía una sola herramienta. El equipo de soporte quiere más: la política de reembolsos, que el host debería tener a mano siempre que un ticket mencione dinero, y una forma estándar de revisar una solicitud de reembolso. Mientras tanto, el equipo de almacén, que lee cada noche los niveles de stock de la misma API, pregunta si también debería migrar a MCP.
Ambas preguntas dependen de lo que MCP añade a una API que ya funciona. Un cliente HTTP se escribe según los endpoints sobre los que su desarrollador ha leído. Un cliente MCP descubre en tiempo de ejecución lo que ofrece un servidor, en una forma que un modelo puede leer, y el protocolo establece quién decide cuándo se usa cada capacidad. Este capítulo examina esas incorporaciones una por una, mide lo que cuestan en la red y termina señalando los casos en los que la tienda no debería pagarlas.
Separa el host, el cliente y el servidor
El servidor de Envuelve un endpoint como herramienta funcionaba detrás de un cliente que manejaba el código de ese capítulo. Antes de que la tienda le añada más cosas, define con precisión qué parte hace qué, porque las garantías de MCP se aplican a los roles, no a los procesos.
La especificación nombra tres roles (arquitectura). El host es la aplicación en la que trabaja el usuario. Crea clientes, mantiene la conversación con el modelo y aplica las políticas de seguridad y el consentimiento. Un cliente es la conexión del host con un servidor: "Cada cliente es creado por el host y se comunica con exactamente un servidor". Un servidor expone capacidades, como herramientas, y no sabe nada más sobre el host. La misma página establece un principio de diseño que se deriva de esa división: un servidor no debe ver la conversación completa ni mirar otros servidores. El host decide qué ve cada servidor, y cualquier cosa que cruce entre servidores ocurre en el host.
El host del equipo de soporte de la tienda desempeña el rol de host y ejecuta el bucle de host del libro. Cada servidor que utiliza tiene su propio cliente: en este capítulo, shop-support, y en Detecta descripciones de herramientas envenenadas un segundo servidor de un socio, que nunca debe enterarse de lo que devolvió el servidor de la tienda. shop-support es el servidor de este capítulo. Conserva la herramienta get_order_status del capítulo 1 y añade un recurso, la política de devoluciones, y un prompt, review_refund, de modo que cada tipo de capacidad aparece una vez. Como en todos los ejemplos de servidor de aquí, el archivo define el servidor y, ejecutado sin argumentos, inicia un cliente que lo lanza con --serve.
Lo primero que hace un cliente es preguntarle al servidor qué ofrece. Una capacidad es algo que un cliente o un servidor declara que soporta, como un servidor que ofrece herramientas o un cliente que puede responder a una solicitud de entrada. En la revisión fijada, eso requiere una sola solicitud, server/discover, cuya respuesta contiene las versiones que el servidor soporta, sus capacidades y su nombre, de modo que un cliente pueda mostrar todo lo que el servidor soporta a partir de esa única respuesta (descubrimiento). Después el cliente enumera cada tipo de capacidad con tools/list, resources/list y prompts/list. En su modo automático por defecto, mcp.Client envía server/discover al abrirse y guarda la respuesta como client.session.discover_result (mcp/client/session.py).
1"""shop-support, the chapter 2 server, offers one tool, one resource and one prompt. Run bare, the file starts it as a2client, which prints what it discovers: the tools, resources and prompts lines are the ones the prose reads."""3import asyncio4import os5import sys67import httpx28from mcp import Client, StdioServerParameters9from mcp.server.caching import CacheHint10from mcp.server.mcpserver import MCPServer11from mcp.server.mcpserver.exceptions import ToolError1213from lib.policies import policy1415# ttl_ms is in milliseconds, so 300_000 is five minutes; "public" lets a shared cache reuse the tool list.16server = MCPServer("shop-support", version="0.2.0",17 cache_hints={"tools/list": CacheHint(ttl_ms=300_000, scope="public")})181920@server.tool()21def get_order_status(order_id: str) -> dict:22 """Look up one of the shop's orders by its ID, such as O-1873: its status, dates, lines and total."""23 response = httpx2.get(f"{os.environ['SHOP_API_URL']}/orders/{order_id}",24 headers={"X-API-Key": os.environ["SHOP_API_KEY"]}, timeout=5.0) # timeout in seconds25 if response.status_code == 404:26 raise ToolError(f"The shop has no order {order_id}. Order IDs look like O-1873.")27 response.raise_for_status()28 return response.json()293031@server.resource("shop://policies/refund", name="refund-policy", mime_type="text/markdown")32def refund_policy() -> str:33 return policy("refund").path.read_text(encoding="utf-8") # examples/data/shop/policies/refund.md343536@server.prompt()37def review_refund(order_id: str) -> str:38 """Review a customer's refund request for one order against the shop's refund policy."""39 return (f"Review the refund request for order {order_id}. Look up the order with get_order_status, read the "40 "refund policy at shop://policies/refund, and say whether the refund needs a person to confirm it.")414243async def main() -> None:44 # No variables are passed: listing never calls the tool, so the server needs none of the shop's API settings.45 async with Client(StdioServerParameters(command=sys.executable, args=[__file__, "--serve"], env={})) as client:46 print("server:", client.server_info.name, client.server_info.version)47 print("protocol revision:", client.protocol_version)48 # auto mode keeps the server/discover answer on the session, so the versions come from there49 print("supported versions:", ", ".join(client.session.discover_result.supported_versions))50 # exclude_none drops the capabilities the server didn't declare, leaving only the ones it offers51 print("capabilities:", ", ".join(sorted(client.server_capabilities.model_dump(exclude_none=True))))52 print("tools:", ", ".join(t.name for t in (await client.list_tools()).tools))53 print("resources:", ", ".join(str(r.uri) for r in (await client.list_resources()).resources))54 print("prompts:", ", ".join(p.name for p in (await client.list_prompts()).prompts))555657if __name__ == "__main__":58 # With --serve this file is the server the client launches; run bare, it is the client.59 server.run() if "--serve" in sys.argv else asyncio.run(main())
python list-what-the-server-offers.pyserver: shop-support 0.2.0
protocol revision: 2026-07-28
supported versions: 2026-07-28
capabilities: prompts, resources, tools
tools: get_order_status
resources: shop://policies/refund
prompts: review_refund
El código del cliente no nombra ninguno de los tres. Los aprendió del servidor, junto con el nombre propio del servidor, shop-support 0.2.0, la revisión que soporta, 2026-07-28, y las capacidades que declara, prompts, resources, tools, impresos junto al ejemplo. Esa es la primera cosa que MCP añade a la API de la tienda: un cliente que no sabe nada de la tienda puede averiguar qué ofrece, con una descripción de cada elemento y, para herramientas y prompts, los argumentos que aceptan, y un host puede mostrárselos a un modelo. El servidor también establece una pista de caché en su lista de herramientas, que explica Almacena en caché los resultados de listas.
Regla práctica: Asigna a cada servidor su propio cliente en el host, y mantén la conversación y cualquier cosa que cruce entre servidores en el código del host, nunca en un servidor. Empieza cada cliente leyendo lo que ofrece el servidor en lugar de suponerlo, de modo que un servidor que cambie sus herramientas no rompa el host. Cuando escribas un servidor, supón que solo ve las solicitudes que se le envían, porque eso es todo lo que la especificación le permite ver.
Esta parte aún no está traducida, así que está en inglés.
Put each capability in the right primitive
The shop-support server from the previous section offers one tool, one resource and one prompt. A server's three primitives are its tools, resources and prompts, and they differ less in what they return than in who decides when they're used. The specification's server overview puts it in a table: prompts are user-controlled, resources are application-controlled, and tools are model-controlled (server features). So the question to ask of each capability is not whether it reads or writes, but who should decide when it runs: the model, the host's own code, or the person at the desk.
The tools page mandates no particular interface for a tool. The resources and prompts pages do the same for their primitives. A host can show them however it likes, but one that respects the control model gives each to the party the table names. The next script uses each of shop-support's three once, the way a host would.
1"""Use each of shop-support's three primitives once, as a host would: the tool for the model, the resource for the2host's code, the prompt for the person at the desk. The prose quotes the order's status, the policy's first line and3the prompt's one required argument."""4import asyncio5import json6import sys78from mcp import Client, StdioServerParameters910from lib import loopback, shop_api111213async def main() -> None:14 with loopback.serve(shop_api.create_app()) as base_url:15 # the server from list-what-the-server-offers, run as its own process with --serve; its env points at the shop's API16 params = StdioServerParameters(command=sys.executable, args=["list-what-the-server-offers.py", "--serve"],17 env=shop_api.server_env(base_url))18 async with Client(params) as client:19 # A tool: the host lists it for the model, and calls it when the model asks.20 result = await client.call_tool("get_order_status", {"order_id": "O-2476"})21 assert result.is_error is False # the lookup must succeed for the prose's claim22 # a tool's result is a list of content blocks; the order arrives as JSON text in the first one23 print("tool says order status:", json.loads(result.content[0].text)["status"])2425 # A resource: the host reads it when its own code decides the model needs it.26 policy = (await client.read_resource("shop://policies/refund")).contents[0] # this server returns one item27 print("resource type:", policy.mime_type)28 print("resource first line:", policy.text.splitlines()[0])2930 # A prompt: the host shows it to the user, who picks it and fills in its arguments.31 listed = (await client.list_prompts()).prompts[0] # the first prompt, the only one shop-support offers32 print("prompt arguments:", "; ".join(f"{a.name}, {'required' if a.required else 'optional'}"33 for a in listed.arguments))34 prompt = await client.get_prompt("review_refund", {"order_id": "O-2476"})35 print("prompt messages:", len(prompt.messages))36 print("prompt role:", prompt.messages[0].role)37 print("prompt starts:", prompt.messages[0].content.text[:44] + "…") # 44 characters: enough to name the order383940asyncio.run(main())
python three-primitives-side-by-side.pytool says order status: shipped
resource type: text/markdown
resource first line: # Refund policy
prompt arguments: order_id, required
prompt messages: 1
prompt role: user
prompt starts: Review the refund request for order O-2476. …
Las herramientas son acciones que elige el modelo
Una herramienta es una acción con nombre, una descripción y un esquema de entrada, y el modelo decide si la llama y con qué datos (herramientas). El host enumera las herramientas para el modelo y ejecuta las llamadas que este solicita. La consulta del pedido O-2476 se realizó sin error, y el estado del pedido llegó como shipped.
La consulta pertenece aquí porque el ticket decide si hace falta. Un cliente cita un número de pedido y pregunta dónde está el paquete; otro pregunta si una sartén viene en 28 cm. Solo algo que lea el ticket puede elegir, y en este host esa tarea le corresponde al modelo. Deja que un modelo elija la herramienta mostró al modelo tomando esa decisión en una grabación.
Regla práctica: Convierte una capacidad en herramienta cuando el modelo deba decidir, a partir de la conversación, si la usa. Eso incluye las consultas que dependen de lo que escribió el cliente, y toda acción que modifique algo, como un reembolso, para la cual el host pide consentimiento antes de la llamada.
Los recursos son datos que elige la aplicación
Un recurso es un dato que un servidor expone bajo un URI, y la aplicación decide cuándo leerlo y qué hacer con él (recursos). El host puede adjuntar un recurso al contexto del modelo, mostrárselo al usuario o indexarlo. shop-support sirve la política de devoluciones de la tienda, uno de los documentos breves de políticas escritos para el libro, bajo shop://policies/refund. Al leerlo se obtuvo texto de tipo text/markdown, cuya primera línea es # Refund policy.
La política de devoluciones es un recurso porque la tienda sabe de antemano cuándo es relevante: en cada ticket sobre dinero. El código del host puede adjuntarla al contexto del modelo para esos tickets sin preguntarle al modelo. Como herramienta, dependería de que el modelo recuerde pedirla, y costaría un turno cada vez. Un recurso no es lo mismo que una herramienta de solo lectura: ambas devuelven datos, pero el lector de un recurso es el código del host, y su resultado puede guardarse en caché según las reglas de Almacenar en caché los resultados de listas. Exponer las políticas como recursos sirve el resto de las políticas de la tienda de la misma manera.
Regla práctica: Haz que un dato sea un recurso cuando el propio código del host puede saber cuándo se necesita, como una política que se aplica a un tipo conocido de ticket, o un registro que el usuario ha abierto. Mantenlo como herramienta cuando solo el modelo, leyendo la conversación, puede saber si hace falta.
Los prompts son plantillas que elige el usuario
Un prompt es una plantilla de mensajes, con argumentos, que define el servidor y que elige el usuario (prompts). La especificación es precisa con la palabra: "controlado por el usuario" se refiere a "quién decide cuándo se usa el prompt, no quién escribe su contenido". El servidor escribe el contenido, y un host normalmente ofrece los prompts en un menú o como comandos. review_refund recibe un argumento, order_id, required. Al completarlo para el pedido O-2476, devolvió 1 mensaje del rol user, que comienza con "Review the refund request for order O-2476. …".
review_refund es un prompt porque una persona del equipo de soporte decide iniciar una revisión de reembolso, normalmente después de leer el ticket, y la tienda quiere que cada revisión siga los mismos pasos. El texto del prompt nombra la herramienta y el recurso que necesita la revisión, así que el modelo parte de la política y del pedido, no de una suposición. Un prompt no es un prompt de sistema que escribe el usuario: la tienda lo escribe una vez, en el servidor, y cada host que se conecta recibe el mismo texto. Empaqueta un flujo de trabajo como prompt convierte review_refund en la revisión completa, con el importe del reembolso como segundo argumento.
Regla práctica: Convierte un flujo de trabajo en prompt cuando una persona debe iniciarlo y cada ejecución debe seguir los mismos pasos, y mantén el texto del prompt en el servidor para que un cambio llegue a todos los hosts a la vez. Si ninguna persona elige cuándo se ejecuta, no es un prompt: haz de los pasos una herramienta, o colócalos en las instrucciones propias del host.
Esta parte aún no está traducida, así que está en inglés.
Carry the version and capabilities on every request
The client in Put each capability in the right primitive made three calls, and the server answered each one without remembering the others, by design. At the pinned revision there's no handshake: every request carries, in its _meta field, the protocol version and the client's capabilities, and those fields "MUST be included on every request" (base protocol). Each request should also carry the client's name and version, and each result the server's.
Three rules on the same page shape how the shop's server uses these fields:
- A request without a required field is rejected with JSON-RPC error
-32602(invalid params), and over HTTP with status 400. - A server must not rely on a capability the client didn't declare on that request. If it needs one, it answers with error
-32021, whose data lists the missing capabilities. clientInfoandserverInfoare self-reported. Implementations "SHOULD NOT rely on them for security decisions", so the shop's server never treats the client's name as an identity.
_meta also carries keys of your own, under a reverse-DNS prefix that ends in /. A prefix whose second label is modelcontextprotocol or mcp is reserved for the protocol, and so are traceparent, tracestate and baggage, which belong to OpenTelemetry (base protocol). The shop's domain is fernhill.example, so its keys start with example.fernhill/.
To see the envelope, the client calls get_order_status through lib.wire, which logs every line between the client and the server. It passes one key of the shop's own, a request ID that support staff can quote. It then sends a tools/list request without the client's capabilities, through a second small module, lib.raw_stdio, which starts a stdio server and writes JSON-RPC lines by hand. The code needs that because mcp.Client never sends a malformed request.
1"""Show the _meta that every request and result carries, add one key of the shop's own, and send a request without2the client's capabilities. The prose's claims about the envelope come from the printed keys and the bare request's error code."""3import asyncio4import json5import sys6from pathlib import Path78from mcp import Client, StdioServerParameters9from mcp.types import Implementation1011from lib import byte_meter, loopback, raw_stdio, shop_api, wire1213COMMAND = [sys.executable, "list-what-the-server-offers.py", "--serve"]141516async def main() -> None:17 Path("meta.jsonl").unlink(missing_ok=True) # the relay appends to its log18 with loopback.serve(shop_api.create_app()) as base_url:19 server = StdioServerParameters(command=COMMAND[0], args=COMMAND[1:], env=shop_api.server_env(base_url))20 # the relay logs every line the client and server exchange, so the byte counts are of lines as sent21 async with Client(wire.relay(server, log="meta.jsonl"),22 # the name and version the SDK sends as clientInfo in _meta; the server must not rely on them23 client_info=Implementation(name="shop-host", version="0.1.0")) as client:24 # a key under the shop's own prefix, which the protocol leaves to the shop to define25 await client.call_tool("get_order_status", {"order_id": "O-2476"},26 meta={"example.fernhill/requestId": "req-0001"})27 trace = [message for _, message in wire.read_trace("meta.jsonl")]28 call = next(m for m in trace if m.get("method") == "tools/call") # the first tools/call request in the log29 result = next(m for m in trace if m.get("id") == call["id"] and "result" in m) # its response, with the same id30 for key, value in call["params"]["_meta"].items():31 print(f"request {key}:", json.dumps(value))32 for key, value in result["result"]["_meta"].items():33 print(f"result {key}:", json.dumps(value))34 lines = [json.loads(entry)["line"] for entry in Path("meta.jsonl").read_text(encoding="utf-8").splitlines()] # as sent35 print("request _meta bytes:", byte_meter.meta_bytes(lines, call["params"]["_meta"]))36 print("result _meta bytes:", byte_meter.meta_bytes(lines, result["result"]["_meta"]))3738 with raw_stdio.launch(COMMAND, env={}) as raw: # the same request, without clientCapabilities39 # capabilities=None leaves clientCapabilities out of _meta: the request the server must reject40 reply = raw.request("tools/list", meta=raw_stdio.envelope("2026-07-28", capabilities=None))41 print("without capabilities, error code:", reply["error"]["code"])42 print("without capabilities, message:", reply["error"]["message"])434445asyncio.run(main())
python request-meta-on-the-wire.pyrequest example.fernhill/requestId: "req-0001"
request io.modelcontextprotocol/protocolVersion: "2026-07-28"
request io.modelcontextprotocol/clientInfo: {"name": "shop-host", "version": "0.1.0"}
request io.modelcontextprotocol/clientCapabilities: {}
result io.modelcontextprotocol/serverInfo: {"name": "shop-support", "version": "0.2.0"}
request _meta bytes: 228
result _meta bytes: 88
without capabilities, error code: -32602
without capabilities, message: params._meta is missing the required envelope key(s): io.modelcontextprotocol/clientCapabilities
The shop's key travels beside the protocol's own. The tools/call request's _meta held four keys. The shop's example.fernhill/requestId, set to "req-0001", came first, and the SDK added the protocol's three after it: the version, "2026-07-28", then the client's name, version and capabilities, which the output prints, the capabilities empty because this client declares none. The result's _meta carried the server's name and version, also printed.
The request without capabilities failed with code -32602, and the SDK's message names the missing key: "params._meta is missing the required envelope key(s): io.modelcontextprotocol/clientCapabilities". A hand-written client, or a gateway that rewrites bodies and drops _meta, fails this way on its first request.
What this costs the shop is bytes on every message. Measured on the lines as sent, the request's _meta, with the shop's key, took 228 bytes, and the result's 88. They are part of the per-call overhead that Keep an HTTP API where MCP adds nothing measures. What it buys is a server that needs no memory of earlier requests: any copy of shop-support can answer any request, which is what lets Run replicas without sticky sessions put two replicas behind one address.
Working rule: Read the version and the client's capabilities from each request, never from an earlier one, and answer -32021 when a call needs a capability the request didn't declare. Put the shop's own request metadata under its own reverse-DNS prefix, never under io.modelcontextprotocol/ or mcp. Log clientInfo and serverInfo for debugging, and decide nothing on them.
Esta parte aún no está traducida, así que está en inglés.
Handle a version the server doesn't support
Every request in Carry the version and capabilities on every request named its protocol version, so a server can meet, on any request, a version it doesn't implement. No negotiation step settles it in advance. A server that doesn't implement the requested version "MUST respond with an UnsupportedProtocolVersionError listing the versions it does support", error code -32022, with the supported versions and the requested one in its data. The client SHOULD pick a version from that list that both sides support, and retry, or else show the user an error (versioning). Over Streamable HTTP the version also travels in the MCP-Protocol-Version header, which must match the body, and an unsupported version gets status 400 (Streamable HTTP).
The shop meets this when a host built for a later revision connects to shop-support. Showing the error means sending a version the server doesn't know, and the obvious way fails first: mcp.Client accepts as its mode only "auto", "legacy" or one of the SDK's per-request revisions, such as 2026-07-28, and raises before it sends anything (mcp/client/client.py). So the script tries that first, then uses lib.raw_stdio from the previous section to write the request by hand. It asks for 2099-01-01, a made-up revision that stands for any the server lacks, then retries with a version from the server's list.
1"""Ask shop-support for a revision it doesn't implement, read its -32022 error, and retry with the newest revision both2sides list. The prose reads the error code, the versions in its data and the retry's tool list from the printed lines."""3import sys45from mcp import Client, StdioServerParameters6from mcp_types.version import MODERN_PROTOCOL_VERSIONS78from lib import raw_stdio910COMMAND = [sys.executable, "list-what-the-server-offers.py", "--serve"]11UNKNOWN = "2099-01-01" # stands for any revision this server doesn't implement1213try:14 # the SDK's client checks the mode when it is built, so this raises before anything is sent15 Client(StdioServerParameters(command=COMMAND[0], args=COMMAND[1:]), mode=UNKNOWN)16except ValueError as refused:17 print("client refuses:", type(refused).__name__)1819with raw_stdio.launch(COMMAND, env={}) as server:20 # capabilities={} declares no client capabilities: the request is well formed, and only its version is unknown21 error = server.request("tools/list", meta=raw_stdio.envelope(UNKNOWN, capabilities={}))["error"]22 print("error code:", error["code"])23 print("error message:", error["message"])24 print("server supports:", ", ".join(error["data"]["supported"])) # the server lists its versions in the error's data25 print("client asked for:", error["data"]["requested"])2627 # the versions both sides know, in the order the SDK lists them28 mutual = [version for version in MODERN_PROTOCOL_VERSIONS if version in error["data"]["supported"]]29 if not mutual:30 sys.exit("no version in common: show the user an error instead of retrying")31 print("retry with:", mutual[-1]) # the last of that list is the newest version both sides know32 # the same process: at this revision each request names its own version, so the retry needs no new connection33 retry = server.request("tools/list", meta=raw_stdio.envelope(mutual[-1], capabilities={}))34 print("retry tools:", ", ".join(tool["name"] for tool in retry["result"]["tools"]))
python unsupported-version-error.pyclient refuses: ValueError
error code: -32022
error message: Unsupported protocol version
server supports: 2026-07-28
client asked for: 2099-01-01
retry with: 2026-07-28
retry tools: get_order_status
The SDK's client never reached the server: it refused the unknown mode before sending anything, with the error the output beside the example shows. The server's answer is what makes the retry possible. Given the raw request, it refused with the code and message the output prints, and its data listed the versions it supports, 2026-07-28, beside the one the client asked for. From that list the script picked 2026-07-28, the newest version both sides know, and the retry listed get_order_status. The retry went to the same process, because a connection carries no agreed version at the pinned revision, so the next request may name another one.
Two details of the SDK at 2.3.0 matter when you read this error from someone else's server. First, an SDK stdio server decides from the client's first request which era of the protocol to speak. A request whose _meta has a protocol version opens a connection at the pinned revision, even when the version is unknown, which is why this request got -32022 instead of a demand for the 2025 initialize handshake (mcp/server/runner.py). Second, the server's supported list holds only the versions that use per-request _meta, although the same server still accepts 2025 clients through initialize (mcp/shared/inbound.py). The specification's own example of the error lists a 2025 revision as well; the SDK's list doesn't. The SDK's client, in its default auto mode, reads a -32022 whose list shares nothing with its own as a real incompatibility, and any other error on its first request as a 2025 server that needs the old handshake (mcp/client/_probe.py). Serve old and new clients through the window covers that second path.
Working rule: When a server answers -32022, pick the newest version in both your list and its supported list, retry once, and show the user an error naming both lists if they share none. Don't retry in a loop, and don't guess a version the server didn't list. On your own server, keep the supported list exact, because clients choose from it.
Almacenar en caché los resultados de listas
La respuesta de server/discover y la lista de herramientas de Separa el host, el cliente y el servidor solo cambian cuando la tienda se despliega, pero un cliente sin estado podría preguntar antes de cada turno del modelo. Cada resultado de server/discover, tools/list, prompts/list, resources/list, resources/templates/list y resources/read debe incluir dos sugerencias de caché en la revisión fijada (caching):
ttlMs, cuántos milisegundos permanece fresco el resultado, comomax-agede HTTP. Cero significa caducado de inmediato.cacheScope, ya sea"public", que una caché puede compartir entre quienes llaman, o"private", que NO DEBE compartir entre contextos de autorización.
La misma página limita lo que significan las sugerencias. Un TTL es una sugerencia de frescura, no un intervalo de sondeo: el cliente comprueba la frescura cuando necesita los datos, y cualquier sondeo debe usar jitter y backoff. Una notificación list_changed invalida un resultado en caché que aún está fresco. Y cacheScope no es control de acceso: un servidor "NO DEBE depender solo de cacheScope para impedir el acceso no autorizado".
Almacenar en caché una lista de herramientas solo funciona si la lista es estable. La especificación dice que la tools/list de un servidor NO DEBE variar de una conexión a otra, aunque puede variar según la autorización de la solicitud, y que los servidores deben devolver las herramientas en un orden determinista, lo que ayuda a que las cachés de prompts acierten con más frecuencia (tools). El MCPServer del SDK lista las herramientas en el orden en que las registras, lo que cumple esa regla (mcp/server/mcpserver/tools/tool_manager.py).
En el SDK, las sugerencias de un servidor tienen por defecto ttl_ms=0 y "private", así que nada se reutiliza salvo que el servidor lo active. shop-support lo activa para su lista de herramientas con cache_hints={"tools/list": CacheHint(ttl_ms=300_000, scope="public")}, cinco minutos y compartible (mcp/server/caching.py). Del otro lado, mcp.Client almacena en caché por defecto, en memoria, según las sugerencias del servidor, y cada llamada de lista recibe un cache_mode de "use", "refresh" o "bypass". Una llamada que pasa su propio meta siempre llega al servidor, y el cliente limita cualquier TTL a 24 horas (mcp/client/caching.py). Para contar lo que ahorra la caché, lista dos veces las herramientas del servidor del capítulo 1, que no establece ninguna sugerencia, y luego dos veces desde shop-support, y cuenta en el cable, con lib.wire, cuántas solicitudes tools/list llegaron a cada servidor.
1"""Call list_tools() twice on each of two servers, one that sets no cache hint and one with a five-minute public hint,2and count the tools/list requests that reach each; the prose reads the three counts."""3import asyncio4import sys5from pathlib import Path67from mcp import Client, StdioServerParameters89from lib import wire101112async def list_twice(script: str, second_call: str = "use") -> tuple[str, str, int]:13 log = Path(script).with_suffix(".jsonl") # the relay's log, beside the server file14 log.unlink(missing_ok=True) # the relay appends to its log15 server = StdioServerParameters(command=sys.executable, args=[script, "--serve"], env={})16 async with Client(wire.relay(server, log=str(log))) as client:17 first = await client.list_tools() # cache_mode="use" is the default18 await client.list_tools(cache_mode=second_call)19 name = client.server_info.name20 # responses carry no method, so this counts only the requests that reached the server21 sent = sum(1 for _, message in wire.read_trace(str(log)) if message.get("method") == "tools/list")22 return name, f"ttlMs {first.ttl_ms}, cacheScope {first.cache_scope}", sent232425async def main() -> None:26 name, hint, sent = await list_twice("order-status-server.py") # chapter 1's server, which sets no hint27 print(f"{name} hint:", hint)28 print(f"{name} tools/list sent for two calls:", sent)29 name, hint, sent = await list_twice("list-what-the-server-offers.py") # this chapter's server, with its tool-list hint30 print(f"{name} hint:", hint)31 print(f"{name} tools/list sent for two calls:", sent)32 name, hint, sent = await list_twice("list-what-the-server-offers.py", second_call="bypass") # bypass skips the cache33 print(f"{name} tools/list sent when the second call bypasses:", sent)343536asyncio.run(main())
python cache-the-tool-list.pyshop-orders hint: ttlMs 0, cacheScope private
shop-orders tools/list sent for two calls: 2
shop-support hint: ttlMs 300000, cacheScope public
shop-support tools/list sent for two calls: 1
shop-support tools/list sent when the second call bypasses: 2
La sugerencia decide cuántas solicitudes llegan. El shop-orders del capítulo 1 devolvió ttlMs 0, cacheScope private, así que ambas llamadas fueron al servidor, 2 solicitudes en total. La lista de shop-support llegó con ttlMs 300000, cacheScope public, así que la caché del cliente respondió a la segunda llamada, y solo 1 solicitud llegó al servidor. Con cache_mode="bypass" en la segunda llamada, ambas llamadas volvieron a llegar al servidor, y la salida junto al ejemplo las cuenta. Un host que incluye la lista de herramientas en cada turno del modelo ahorra una solicitud por turno. Y como la lista conserva su orden, el prompt del modelo empieza con los mismos bytes, que es lo que necesita la caché de prompts de un proveedor.
La lista de herramientas de la tienda puede ser pública porque todos los que llaman ven las mismas herramientas. Los datos de cada cliente de la tienda no pueden serlo. Cuando Direcciona registros con plantillas de recursos sirve un recurso por pedido, esas lecturas siguen siendo "private", así una caché compartida nunca entregará el pedido de un cliente a la sesión de otro. Si la lista de herramientas llega a depender algún día del token de quien llama, como puede ocurrir cuando se aplique Limita las herramientas según lo que permite el token, también pasará a ser privada.
Regla práctica: Establece un TTL y un alcance "public" en las listas que son iguales para todos los que llaman, como la lista de herramientas de la tienda, y elige un TTL no mayor que el tiempo en que aceptarías una lista desactualizada tras un despliegue: minutos, no horas. Mantén "private", el valor por defecto del SDK, en todo lo que dependa de quién lo pide, y nunca dejes que cacheScope sustituya una comprobación de autorización. En el cliente, mantén la caché por defecto, que elimina una entrada cuando llega una notificación de cambio por un flujo client.listen(tools_list_changed=True) (mcp/client/client.py), el tipo de flujo que abre Avisa a los clientes cuando cambie un recurso. Sin ese flujo ninguna notificación llega al cliente, así que ábrelo, y usa cache_mode="refresh" cuando tengas otro motivo para dudar de una entrada, en lugar de sondear según el TTL.
Esta parte aún no está traducida, así que está en inglés.
Keep an HTTP API where MCP adds nothing
Each section so far showed something MCP adds to the shop's API. Separate the host, the client and the server added run-time discovery, and Put each capability in the right primitive gave each capability a control model. Carry the version and capabilities on every request made every request versioned and self-describing. The host's consent step, in Ask for consent before side effects, is another. Each of those helps when a model or a user's host chooses among capabilities at run time. None of them helps a program whose developer already knows which endpoint it will call.
The specification doesn't say when not to use MCP, so this is the book's judgement, not a protocol rule. We recommend a plain HTTP API for three kinds of work:
- Service-to-service calls with no model choosing, such as the warehouse's nightly read of stock levels. Its code calls fixed endpoints, so nobody reads the discovery answers or the descriptions.
- Fixed workflows, where the same steps run in the same order every time. Write them as code over the API, and if a model needs to start one, expose the whole workflow as one tool.
- High-volume batch work, where every byte and round trip is multiplied.
We recommend MCP where a model or a user's host chooses among capabilities at run time, as the support team's host does. The two don't compete. Meet the shop and its API kept the shop's API as the system of record, and shop-support is a thin adapter over it, so the warehouse keeps its API calls while the support team's host uses MCP.
This run prices the adapter, so the trade-off rests on numbers. The script fetches order O-2476 twice: once from the shop's API, with GET /orders/O-2476, and once through shop-support's get_order_status tool over Streamable HTTP, the transport Move the server from stdio to HTTP teaches. lib.byte_meter, a small module for this measurement, puts a TCP relay in front of each server and counts every byte both ways, headers included, and counts the HTTP requests each server handles. Everything runs in one process on 127.0.0.1, over HTTP/1.1 without TLS. On the MCP side, the count covers a host's setup on opening a client, including the tool listing, but not the tool call. That setup is measured twice: in the default auto mode, which first probes the server with server/discover, and with the version pinned. The tool call itself is made with the version pinned. No times are measured, because times on one machine's loopback say little about a network.
1"""Fetch order O-2476 from the shop's API, then through shop-support's tool over Streamable HTTP, and count the cost.2The prose's comparison comes from the byte totals and the request counts the script prints."""3import asyncio4import os5import runpy67import httpx28from mcp import Client910from lib import byte_meter, loopback, shop_api111213async def session(url, traffic, requests, mode: str, calls: int) -> tuple[list[str], int]:14 """Open a client, list the tools as a host does, make `calls` tool calls, close it: the requests and bytes."""15 traffic.reset()16 requests.reset()17 # auto mode first sends server/discover to probe the server; a pinned revision skips that probe18 async with Client(f"{url}/mcp", mode=mode) as client:19 await client.list_tools()20 for _ in range(calls):21 await client.call_tool("get_order_status", {"order_id": "O-2476"})22 return list(requests.names), traffic.sent + traffic.received # bytes both ways, from the relay232425async def main() -> None:26 print("setup: one process, 127.0.0.1, HTTP/1.1, no TLS, bytes counted at a TCP relay, headers included")27 api_app, api_requests = byte_meter.count_requests(shop_api.create_app())28 with loopback.serve(api_app) as api_url, byte_meter.relay(api_url) as (url, traffic):29 # the one API call, sent through the relay so that its bytes are counted the way the tool's are30 httpx2.get(f"{url}/orders/O-2476", headers={"X-API-Key": shop_api.DEMO_API_KEY}).raise_for_status()31 api_bytes = traffic.sent + traffic.received32 print("api call round trips:", api_requests.count)33 print("api call bytes:", api_bytes)3435 os.environ.update(shop_api.server_env(api_url)) # the tool calls the API directly, not through a relay36 shop_support = runpy.run_path("list-what-the-server-offers.py")["server"] # defined there, not run37 mcp_app, mcp_requests = byte_meter.count_requests(shop_support.streamable_http_app())38 with loopback.serve(mcp_app) as mcp_url, byte_meter.relay(mcp_url) as (url, traffic):39 for mode, label in (("auto", "auto"), ("2026-07-28", "pinned")):40 names, setup_bytes = await session(url, traffic, mcp_requests, mode, calls=0) # setup only, no tool call41 print(f"mcp {label} setup request count:", len(names))42 print(f"mcp {label} setup requests:", ", ".join(names))43 print(f"mcp {label} setup bytes:", setup_bytes)44 names, with_call = await session(url, traffic, mcp_requests, "2026-07-28", calls=1)45 call_bytes = with_call - setup_bytes # a pinned session with one call, less the pinned setup46 print("mcp tool call round trips:", names.count("tools/call"))47 print("mcp tool call bytes:", call_bytes)48 print("tool call bytes per api call byte:", round(call_bytes / api_bytes, 1)) # one decimal place, as the prose quotes495051asyncio.run(main())
python api-call-versus-tool-call.pysetup: one process, 127.0.0.1, HTTP/1.1, no TLS, bytes counted at a TCP relay, headers included
api call round trips: 1
api call bytes: 591
mcp auto setup request count: 2
mcp auto setup requests: server/discover, tools/list
mcp auto setup bytes: 2157
mcp pinned setup request count: 1
mcp pinned setup requests: tools/list
mcp pinned setup bytes: 1147
mcp tool call round trips: 1
mcp tool call bytes: 1357
tool call bytes per api call byte: 2.3
On the wire the tool call costs more bytes, not more round trips. The API call takes 1 round trip and the tool call takes 1, but it sends 2.3 times the bytes, which the output beside the example counts. The difference is the JSON-RPC envelope, the _meta on the request and on the result, the routing headers that Streamable HTTP adds, and the order itself, which the SDK returns as indented JSON inside a text block, with its quotes escaped, as Read the messages on the wire showed.
Setup costs more on top of that. In auto mode, opening the client sent 2 requests before its first call; with the version pinned it skipped the server/discover probe and sent 1. The output beside the example lists the requests and their bytes. Behind the server, each tool call also made its own request to the shop's API, which the counts leave out because the caller never sees it.
Some of those bytes buy something without a model. The headers Mcp-Method, on every request, and Mcp-Name, on tools/call, resources/read and prompts/get, let a gateway route by method and by tool without parsing bodies (Streamable HTTP). For the support team's host, which makes a few calls per ticket, 1357 bytes a call is small beside the model's own tokens. For the warehouse's nightly read of 64 products, every call pays for an envelope its code never reads, and the adapter adds a process to a job that ran without one.
Working rule: Keep a plain HTTP API for callers whose code knows which endpoint to call, such as other services, fixed workflows and batch jobs, and put an MCP server in front of the same API for hosts where a model or a user chooses at run time. Measure the overhead on your own transport before you route high-volume traffic through MCP, and pin the protocol version in clients you control, so they skip the discovery probe. Keep auto mode for clients that may meet servers you don't control, which may speak only the 2025 protocol.
Qué sale mal en producción
Las partes que este capítulo añadió fallan de pocas maneras reconocibles, y cada una deja un rastro que puedes buscar.
Una capacidad acaba en la primitiva equivocada. Una política servida como herramienta se omite cuando el modelo no piensa en consultarla, y un reembolso servido como recurso deja al host sin ningún punto en el que pedir consentimiento. La señal es un comportamiento que varía de un ticket a otro sin motivo aparente en el ticket: respuestas sobre dinero dadas sin la política, o efectos secundarios sin paso de consentimiento en los registros. Pregúntate de cada capacidad quién debe decidir cuándo se ejecuta, como hace Pon cada capacidad en la primitiva correcta.
Una pasarela descarta o reescribe _meta. Los proxies y las pasarelas de API diseñados para APIs JSON simples a veces reescriben los cuerpos de las peticiones. Una petición que pierde su versión o sus capacidades falla con -32602, como mostró Incluye la versión y las capacidades en cada petición. En Streamable HTTP, un cuerpo que ya no coincide con sus cabeceras falla con -32020, porque las cabeceras MCP-Protocol-Version, Mcp-Method y Mcp-Name deben coincidir con el cuerpo (Streamable HTTP). Deja pasar el tráfico de MCP sin cambios, y enruta según las cabeceras en lugar de editar los cuerpos.
clientInfo se usa como identidad. El nombre del cliente en _meta es lo que el cliente haya elegido enviar, y la especificación indica que no debe confiarse en él para la seguridad (protocolo base). Un servidor que concede más a un cliente llamado shop-host se lo concede a cualquiera que envíe ese nombre. La autorización procede de los tokens, por donde empieza Encuentra el servidor de autorización a partir del recurso.
Una entrada de caché pública cruza clientes. Un resultado marcado como "public" puede compartirse entre contextos de autorización, incluso cuando procede de un endpoint autenticado (caché). Un servidor que marca como públicos datos de cada cliente permite que una caché compartida sirva el pedido de un cliente a otro. Mantén el valor por defecto "private" del SDK para todo lo que dependa de quien llama, y trata cada indicación "public" en una revisión de código como una afirmación que hay que comprobar.
Un TTL largo oculta un despliegue. Con una lista de herramientas válida durante horas, un cliente sigue ofreciendo una herramienta que el servidor ya eliminó, y las llamadas a ella fallan. La señal son errores de herramienta desconocida que dejan de aparecer al reiniciar los clientes. Mantén los TTL de las listas de herramientas en minutos, y deja que los clientes se actualicen con una notificación de cambio, que solo llega a un cliente por un flujo subscriptions/listen que él abrió, como configura Avisa a los clientes cuando cambie un recurso.
Un cliente llama a una herramienta que nunca listó. En 2.3.0, mcp.Client comprueba el resultado de una herramienta frente al esquema de salida de esa herramienta, y si todavía no ha listado las herramientas, envía antes tools/list (mcp/client/session.py). Un cliente que llama herramientas sin listarlas paga una petición extra en su primera llamada. Lista las herramientas al abrir el cliente, como hace un host de todos modos.
Códigos de error antiguos de material antiguo. La revisión fijada reserva de -32020 a -32099 para la especificación, trata de -32000 a -32019 como un rango heredado que el código nuevo no debe usar, y pide códigos de aplicación fuera del rango que JSON-RPC reserva (protocolo base). La revisión renumeró sus códigos de error de camino a la publicación (registro de cambios), así que el material escrito para un borrador puede mostrar otros números para los mismos errores. Compara los códigos de error con la especificación, no con una entrada de blog.
La especificación avanza. MCP lo gobierna la Agentic AI Foundation, un fondo dirigido bajo la Linux Foundation, que acogió a MCP como proyecto fundacional en diciembre de 2025 (anuncio). Las revisiones tienen fecha, y una funcionalidad obsoleta permanece al menos doce meses (ciclo de vida de las funcionalidades). El plazo solo es menor por un riesgo de seguridad activo, y entonces es de al menos noventa días, o lo que indique el registro de funcionalidades obsoletas. Consulta el registro cuando planifiques la próxima versión de un servidor, y vigila en los registros los -32022 de clientes creados para una revisión posterior.
Regla práctica: Comprueba cuatro cosas en cualquier servidor que vayas a publicar: la primitiva de cada capacidad coincide con quién decide cuándo se ejecuta, nada entre cliente y servidor edita los cuerpos de MCP, nada se decide según clientInfo, y cada indicación de caché "public" cubre datos iguales para cualquier quien llame. Registra la versión del protocolo y el código de error de cada petición fallida, porque los errores de versión y de envoltorio son la primera señal de que un cliente o una pasarela han cambiado.
Decisiones que tomó este capítulo
- Un cliente por servidor, en el host. La conversación y todo lo que cruza entre servidores se quedan en el código del host; un servidor solo ve las solicitudes que se le envían.
- El servidor de la tienda es
shop-support, con la herramientaget_order_statusdel capítulo 1, la política de devoluciones como recurso enshop://policies/refund, yreview_refundcomo prompt. - Cada capacidad va a la primitiva cuyo controlador debe decidir cuándo se ejecuta: el modelo para las herramientas, el código del host para los recursos, la persona frente al escritorio para los prompts.
- La versión y las capacidades se leen de cada solicitud, nunca de una anterior, y una capacidad que falta recibe
-32021. - Las claves propias de la tienda en
_metausan el prefijoexample.fernhill/. Nada se decide a partir declientInfoni deserverInfo. - Ante
-32022, el cliente reintenta una vez con la versión más reciente que ambas partes listan, y muestra un error si no hay ninguna. - La lista de herramientas es pública, con un TTL de cinco minutos. Los datos de cada cliente siguen siendo privados, y la lista de herramientas pasa a ser privada si llega a depender del token.
- El JSON-RPC escrito a mano, a través de
lib.raw_stdio, solo sirve para mostrar errores que el cliente del SDK nunca provocaría. - Recomendamos una API HTTP sencilla para las llamadas entre servicios, los flujos de trabajo fijos y el trabajo por lotes, y MCP cuando un modelo o el host de un usuario elige en tiempo de ejecución, respaldado por los recuentos de bytes y de viajes de ida y vuelta de
api-call-versus-tool-call.
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.