Serve data as resources and prompts
Unos 29 minutos de lectura, con 5 ejemplos en 8 secciones.
Traducido con IA. Verificado por personas en inglés. Cómo hacemos los libros
Traducido del libro en inglés, edición 2026.11.14. Lee el original
En esta página
Esta parte aún no está traducida, así que está en inglés.
By the end of this chapter you can publish the shop's policies and records as Model Context Protocol resources, address many records with one resource template, complete an argument while a user types it, tell a client when a resource changes, and package a refund review as a prompt the user can pick. The chapter's claims, and the code behind them, hold for mcp 2.3.0, the Python SDK, at revision 2026-07-28 of the specification.
The shop sells kitchen and garden goods, and most of what its support team's host needs to answer a ticket is something to read, not something to do. Separate the host, the client and the server gave the shop's server, shop-support, one capability of each kind: the tool get_order_status, the refund policy as a resource, and a short review_refund prompt. One document and one prompt don't cover it. Every refund answer must follow the refund policy, a ticket is about one order, and a stock question is about one product's count. If each of those is a tool, the model has to decide to fetch it, and it may not.
For this, a Model Context Protocol (MCP) server has two other primitives, which differ from tools in who decides when they're used (Put each capability in the right primitive). A resource is data the server publishes under a URI, and the host decides whether to put it in front of a model. A prompt is a message template the server offers, and the user picks it. This chapter builds both out for the shop.
The server keeps the name shop-support throughout. Each example defines only the part its section teaches, and runs itself as chapter 2's server examples do: with no arguments, the file starts a client that launches the same file with --serve over stdio.
Esta parte aún no está traducida, así que está en inglés.
Expose the policies as resources
shop-support already publishes one of the rules an answer must follow, the refund policy, which Resources are data the application chooses showed how to serve, and the shop has five more. Each one suits a resource: data that a server publishes under a URI, with a name, an optional title and description, a mimeType, and contents that are either text or a base64 blob (resources). A client lists a server's resources with resources/list and reads one with resources/read.
Resources are application-driven: the host decides how they're used. The specification's resources page says a host might show a picker, search the resources, or include some automatically, based on heuristics or the model's own selection. The protocol gives the model no way to read a resource; the host decides, though it may let the model choose. A resource's URI follows RFC 3986, and a server may use a scheme of its own. The specification keeps https:// for resources a client can fetch without the server, directly from the web.
The six are the shop's policies, short rules written for this book on refunds, returns, shipping, stock, data handling and escalation. They are Markdown files in examples/data/shop/policies/, licensed CC BY 4.0 with the book's text and listed in the data card, examples/data/shop/README.md. lib.policies reads each one's title, Updated: date and one-sentence summary, so the server can describe every policy without opening the files on each request.
The server publishes each policy as a static resource at shop://policies/{slug}. The refund policy keeps the URI shop://policies/refund and the name refund-policy that chapter 2 gave it. The SDK's FileResource reads the file again on every resources/read, so an edited policy reaches the next read without a restart (mcp/server/mcpserver/resources/types.py). A resource's annotations are three hints the host may use or ignore (resources):
audiencesays who the content is for. The policies are forassistant, the model.priority, from 0.0 to 1.0, says how important the content is, and 1 means "effectively required". We give the refund policy 1.0 and the others 0.5. That is a judgement: every refund answer must follow the refund policy, while the other five matter only for some tickets.lastModifiedis an ISO 8601 time, here each policy'sUpdated:date.
At the pinned revision, resources/list and resources/read results carry two cache hints. ttlMs says how long a result stays fresh, and cacheScope says whether a cache may share it across callers (caching). The SDK's default is a ttlMs of 0 with the private scope (mcp/server/caching.py). The policies are the same for every caller and change rarely, so this server marks both methods public for an hour. Listing and reading the policies shows both hints.
1"""Serves the shop's six policies as static resources, then lists them and reads the refund policy from a client.2The point rests on the priority lines, where only the refund policy is 1.0, and on the two cache scope lines, which say public."""3import asyncio4import sys56from mcp import Client, StdioServerParameters7from mcp.server.caching import CacheHint8from mcp.server.mcpserver import MCPServer9from mcp.server.mcpserver.resources import FileResource10from mcp.types import Annotations1112from lib.policies import load_policies1314HOUR_MS = 3_600_00015server = MCPServer("shop-support", version="0.4.0", cache_hints={ # policies are the same for every caller16 "resources/list": CacheHint(ttl_ms=HOUR_MS, scope="public"),17 "resources/read": CacheHint(ttl_ms=HOUR_MS, scope="public")})1819for policy in load_policies():20 server.add_resource(FileResource(21 uri=f"shop://policies/{policy.slug}", name=f"{policy.slug}-policy", title=policy.title,22 description=policy.summary, mime_type="text/markdown", path=policy.path,23 # the refund policy is effectively required (1.0); the others matter only for some tickets (0.5)24 annotations=Annotations(audience=["assistant"], priority=1.0 if policy.slug == "refund" else 0.5,25 # the file gives a day, not a time, so its update is taken as midnight UTC26 last_modified=f"{policy.updated}T00:00:00Z")))272829async def main() -> None:30 params = StdioServerParameters(command=sys.executable, args=[__file__, "--serve"], env={})31 async with Client(params) as client:32 print("protocol revision:", client.protocol_version)33 listed = await client.list_resources()34 print("resources:", len(listed.resources))35 for resource in listed.resources:36 print(f" {resource.uri} {resource.title!r} priority {resource.annotations.priority}")37 print("list cache scope:", listed.cache_scope)38 print("list ttl ms:", listed.ttl_ms)39 read = await client.read_resource("shop://policies/refund")40 contents = read.contents[0] # a read returns a list of contents; this file is its only item41 print("mime type:", contents.mime_type)42 print("first line:", contents.text.splitlines()[0]) # the file's first line is its title43 print("read cache scope:", read.cache_scope)44 print("read ttl ms:", read.ttl_ms)454647if __name__ == "__main__":48 server.run() if "--serve" in sys.argv else asyncio.run(main())
python list-policy-resources.pyprotocol revision: 2026-07-28
resources: 6
shop://policies/data-handling 'Data-handling policy' priority 0.5
shop://policies/escalation 'Escalation policy' priority 0.5
shop://policies/refund 'Refund policy' priority 1.0
shop://policies/returns 'Returns policy' priority 0.5
shop://policies/shipping 'Shipping policy' priority 0.5
shop://policies/stock 'Stock policy' priority 0.5
list cache scope: public
list ttl ms: 3600000
mime type: text/markdown
first line: # Refund policy
read cache scope: public
read ttl ms: 3600000
The client sees 6 resources, sorted by slug, and only the refund policy has priority 1.0. The list carries the scope public and a lifetime of 3600000 milliseconds, so a client may reuse it for an hour and share it between users. Cache list results shows what a client does with the hints.
Reading shop://policies/refund returned the file itself, as text/markdown text that begins with the line # Refund policy. The read carries the same scope, public, because the server marks both methods public.
That exchange never put the refund policy in front of a model. The server published it, and the host alone decides when to include it. Put resources in the model's context builds the host loop that does so for every refund ticket.
Working rule: Publish the documents a host should be able to put in front of a model as static resources, under a scheme that names your system, with a MIME type and a description the host can show. Use https:// only for resources the client can fetch without your server. Mark a result public only when every caller gets the same one, and give high priority only to the one or two documents every answer depends on, not to all of them.
Direccionar registros con plantillas de recursos
Las six políticas de la sección anterior sirven para una lista, pero los pedidos de la tienda no. Los datos contienen 501 pedidos cuyos identificadores empiezan solo por O-2, y un recurso para cada uno sería inútil para un host y costoso de servir. Una plantilla de recurso nombra muchos recursos con una única plantilla de URI, escrita en la sintaxis de la RFC 6570 (RFC 6570). Un cliente lista las plantillas con resources/templates/list, rellena las variables y lee el resultado con resources/read (recursos).
En el SDK de Python, la URI que se pasa a @server.resource() determina el tipo. Las llaves alrededor de una variable registran una plantilla, y los parámetros de la función deben coincidir con las variables. Una URI sin llaves registra un recurso estático (mcp/server/mcpserver/server.py, resource). El valor devuelto fija el contenido: un str da texto, bytes dan un blob, y cualquier otro valor se convierte a JSON.
Una plantilla también cambia lo que significa un fallo de búsqueda. Una lectura de un recurso que no existe falla, en la revisión fijada, con el error JSON-RPC -32602, Invalid Params, y la URI va en el data del error. El servidor "NO DEBE devolver un array contents vacío" en su lugar (recursos). La revisión 2025-11-25 usaba -32002 para el mismo caso, y los clientes deben seguir aceptando ese código de servidores antiguos (registro de cambios). En MCPServer, una función obtiene -32602 al lanzar ResourceNotFoundError. Cualquier otro ResourceError se convierte en -32603, y un recurso, a diferencia de una herramienta, no tiene un resultado isError con el que fallar (gestión de errores).
La plantilla de pedidos de la tienda es shop://orders/{order_id}, y su función envuelve GET /orders/{order_id} en la API de la tienda, el endpoint que también envuelve get_order_status. Lanza ResourceNotFoundError cuando la API responde 404. Un pedido pertenece a un solo cliente, así que la lectura conserva la indicación de caché predeterminada del SDK, private con una vida de 0. La página de caché nombra private como ámbito para los resultados de resources/read "que dependen del usuario autenticado" (caché). Antes de que la API vea nada, la función comprueba que la variable tenga aspecto de identificador de pedido, O- y cuatro dígitos, y lanza ResourceNotFoundError si no es así, de modo que un identificador mal formado nunca llega a la API.
Cuatro lecturas, un éxito y tres tipos de fallo: un pedido real, uno que no existe, un identificador con formato incorrecto y una URI cuya variable intenta salirse de la ruta del pedido.
1"""Reads orders through the template shop://orders/{order_id} and prints what each kind of miss returns.2The point rests on the codes, which are all the same, and on the traversal's message, which the SDK wrote rather than the handler."""3import asyncio4import json5import re6import sys78from mcp import Client, MCPError, StdioServerParameters9from mcp.server.mcpserver import MCPServer10from mcp.server.mcpserver.exceptions import ResourceNotFoundError1112from lib import loopback, shop_api, shop_reads1314server = MCPServer("shop-support", version="0.4.0") # default cache hint: ttl 0, scope private151617@server.resource("shop://orders/{order_id}", title="One of the shop's orders", mime_type="application/json")18async def order(order_id: str) -> dict:19 """One order: its status, dates, lines and total, as the shop's API returns it."""20 if not re.fullmatch(r"O-\d{4}", order_id): # check the format before the API sees it21 raise ResourceNotFoundError(f"Order IDs look like O-1873, not {order_id!r}.")22 if (found := await shop_reads.get_json(f"/orders/{order_id}")) is None: # the API answered 40423 raise ResourceNotFoundError(f"The shop has no order {order_id}.")24 return found252627async def main() -> None:28 with loopback.serve(shop_api.create_app()) as base_url:29 params = StdioServerParameters(command=sys.executable, args=[__file__, "--serve"],30 env=shop_api.server_env(base_url))31 async with Client(params) as client:32 template = (await client.list_resource_templates()).resource_templates[0] # the server defines one template33 print("template:", template.uri_template)34 read = await client.read_resource("shop://orders/O-2476")35 print("O-2476 status:", json.loads(read.contents[0].text)["status"]) # a read returns a list; the order is its only item36 print("read cache scope:", read.cache_scope)37 for case, uri in (("unknown order", "shop://orders/O-7144"),38 ("malformed", "shop://orders/2476"),39 # %2F is an encoded slash, so the URI has no path separator until the SDK decodes the variable40 ("traversal", "shop://orders/..%2F..%2Frefunds")):41 try:42 await client.read_resource(uri)43 except MCPError as err:44 print(f"{case} code:", err.error.code)45 print(f"{case} says:", err.error.message)46 print(f"{case} data uri:", err.error.data["uri"]) # the URI the server could not read, which the error carries47 assert err.error.code == -32602, case # every miss gets the same code, the one the prose names484950if __name__ == "__main__":51 server.run() if "--serve" in sys.argv else asyncio.run(main())
python order-resource-template.pytemplate: shop://orders/{order_id}
O-2476 status: shipped
read cache scope: private
unknown order code: -32602
unknown order says: The shop has no order O-7144.
unknown order data uri: shop://orders/O-7144
malformed code: -32602
malformed says: Order IDs look like O-1873, not '2476'.
malformed data uri: shop://orders/2476
traversal code: -32602
traversal says: Unknown resource: shop://orders/..%2F..%2Frefunds
traversal data uri: shop://orders/..%2F..%2Frefunds
La plantilla aparece listada como shop://orders/{order_id}, y el pedido O-2476 se lee como shipped, con el ámbito de caché private.
Los tres fallos terminan con el mismo código, -32602, pero sus mensajes proceden de lugares distintos. El pedido inexistente, O-7144, recibe el mensaje propio del manejador, y su URI vuelve en los datos del error, shop://orders/O-7144. El identificador 2476 recibe el mensaje de la comprobación de formato, Order IDs look like O-1873, not '2476'..
La lectura con recorrido de ruta también falla, pero su mensaje es el del SDK, Unknown resource: shop://orders/..%2F..%2Frefunds, no el del manejador. El SDK decodificó la variable como ../../refunds, encontró .. segmentos de ruta en ella y rechazó la URI antes de ejecutar la función. Sin ese rechazo, el manejador habría enviado ../../refunds en la ruta de su petición a la API de la tienda.
Ese rechazo es ResourceSecurity, que por defecto rechaza segmentos .., rutas absolutas y bytes NUL en las variables de plantilla, sea cual sea la codificación usada en la URI (mcp/server/mcpserver/resources/templates.py). La especificación exige que los servidores validen cada URI de recurso (recursos), y la comprobación del SDK lo refuerza sin sustituirlo. No detiene 2476, que pasa ResourceSecurity, así que solo la comprobación de formato del manejador lo detecta.
Esta plantilla lee cualquier pedido para quien posea la clave de API del servidor, lo que encaja con el host del equipo de soporte. La siguiente sección limita las lecturas a un solo cliente.
Regla práctica: Usa una plantilla de recurso para registros que comparten una forma y un identificador. Devuelve el JSON propio de la API, y lanza ResourceNotFoundError ante un fallo, lo que da al cliente -32602 con la URI. Mantén el ámbito private para cualquier dato que pertenezca a un usuario. Deja activada la comprobación ResourceSecurity del SDK, y valida también tú el formato de la variable. Exime una variable de la comprobación solo cuando deba transportar una ruta, y en ese caso comprueba la ruta tú mismo.
Completar argumentos para el usuario
Un host que muestra al usuario la plantilla de pedidos de la sección anterior necesita que complete order_id, y pocas personas recuerdan los identificadores de pedido. El completado de argumentos permite que el host pida al servidor sugerencias mientras el usuario escribe. El host envía completion/complete con una referencia, bien ref/resource con el URI de una plantilla, bien ref/prompt con el nombre de un prompt, además del nombre del argumento y su valor parcial. Puede añadir context.arguments, los valores que el usuario ya haya elegido para otros argumentos. El resultado contiene values, como máximo 100, con un total opcional y hasMore. Un servidor que ofrece completado declara la capacidad completions (completion).
Un único manejador @server.completion() del SDK de Python atiende todas las plantillas y prompts del servidor. Recibe la referencia, el argumento y el contexto, y devuelve un Completion o None. Registrarlo declara la capacidad. El SDK no filtra lo que devuelve, así que todo lo que haya en values es lo que muestra la interfaz (completions). Tampoco aplica el límite de 100 elementos. El tipo Completion indica que no debe superar los 100 elementos, pero nada lo comprueba (mcp_types/_types.py), por lo que el manejador debe limitar la lista por sí mismo.
El completado es también una búsqueda, y una búsqueda puede filtrar datos. La especificación exige que los servidores controlen el acceso a las sugerencias sensibles, para que el completado no revele información que no debería revelar (completion). Un manejador que completara identificadores de pedido de toda la tienda diría a cualquiera que escriba O-2 qué pedidos de la tienda existen.
Por eso el manejador completa solo los pedidos del cliente en nombre del cual actúa el servidor. Por stdio, el host indica ese cliente en el entorno del servidor, al pasar la clave de API de la tienda. Aquí SHOP_CUSTOMER_ID es C-0127, el cliente que hizo el pedido O-2476. Por HTTP, Autorizar clientes con OAuth sustituye la variable por lo que indique un token de acceso. El token de un host de soporte nombra a un miembro del personal, así que el cliente se obtiene del ticket que consulta el servidor (el sujeto del token es el cliente solo cuando los propios clientes inician sesión; véase Evitar que el servidor actúe como un delegado confundido).
El manejador pide a la API de la tienda los pedidos de ese cliente y conserva los que empiezan por lo que escribió el usuario. La API devuelve como máximo 100 pedidos de un cliente, del más reciente al más antiguo (examples/lib/shop_api.py), así que la respuesta nunca supera el límite del protocolo. El manejador mantiene también ese orden: en un ticket de soporte los pedidos más recientes son los más probables, y la especificación pide sugerencias "ordenadas por relevancia" (completion).
La respuesta de la API incluye además el número total de pedidos del cliente. Cuando ese total es mayor que el número de pedidos devueltos, pedidos más antiguos podrían coincidir también, así que el manejador omite total y establece has_more. En caso contrario informa del número de coincidencias como total. La plantilla de pedidos aplica el mismo ámbito a las lecturas: el pedido de otro cliente recibe la misma respuesta de no encontrado que un pedido que no existe. Un módulo compartido, lib.shop_reads, contiene la función asíncrona auxiliar que ambos manejadores usan para llamar a la API de la tienda. La ejecución prueba dos prefijos y lee dos pedidos que el llamador no puede ver.
1"""Completes order IDs for shop://orders/{order_id} from the orders of the one customer the server acts for, and answers another customer's order as if it didn't exist.2The point rests on the offers, which hold only the caller's orders, and on the two answers at the end, which differ only in the ID."""3import asyncio4import os5import sys67from mcp import Client, MCPError8from mcp.server.mcpserver import MCPServer9from mcp.server.mcpserver.exceptions import ResourceNotFoundError10from mcp.types import Completion, ResourceTemplateReference1112from lib import loopback, shop_api, shop_reads13server = MCPServer("shop-support", version="0.4.0")141516@server.resource("shop://orders/{order_id}", title="One of your orders", mime_type="application/json")17async def order(order_id: str) -> dict:18 found = await shop_reads.get_order(order_id) # checks the ID's format before the API sees it19 # the customer the server acts for, from the server's environment20 if found is None or found["customer_id"] != os.environ["SHOP_CUSTOMER_ID"]:21 raise ResourceNotFoundError(f"You have no order {order_id}.") # the same answer either way22 return found232425@server.completion()26async def complete(ref, argument, context) -> Completion | None:27 # this handler completes only the order template's order_id argument28 if not isinstance(ref, ResourceTemplateReference) or argument.name != "order_id":29 return None30 # the API's newest-first page, at most 100 orders, which is also the protocol's cap of 100 values31 page = await shop_reads.get_json("/orders", customer_id=os.environ["SHOP_CUSTOMER_ID"], limit=100)32 # upper-cases what the user typed, so o-24 matches O-247633 matches = [o["order_id"] for o in page["orders"] if o["order_id"].startswith(argument.value.upper())]34 cut_short = page["total"] > len(page["orders"]) # older orders the API didn't return may match too35 # total is reported only when every match was counted36 return Completion(values=matches, total=None if cut_short else len(matches), has_more=cut_short)373839async def main() -> None:40 print("shop orders starting O-2:", shop_reads.orders_starting("O-2"))41 print("most orders for one customer:", shop_reads.most_orders_per_customer())42 with loopback.serve(shop_api.create_app()) as base_url:43 # C-0127 is the customer the server acts for, passed in the server's environment44 async with Client(shop_reads.server_params(__file__, base_url, SHOP_CUSTOMER_ID="C-0127")) as client:45 for typed in ("O-2", "o-24"):46 ref = ResourceTemplateReference(uri="shop://orders/{order_id}")47 result = (await client.complete(ref, {"name": "order_id", "value": typed})).completion48 print(f"{typed} offers:", ", ".join(result.values), f"({result.total} in all)")49 for order_id in ("O-1767", "O-7144"): # another customer's order, and nobody's50 try:51 await client.read_resource(f"shop://orders/{order_id}")52 except MCPError as err:53 print(f"{order_id} answer:", err.error.code, err.error.message)545556if __name__ == "__main__":57 server.run() if "--serve" in sys.argv else asyncio.run(main())
python complete-order-ids.pyshop orders starting O-2: 501
most orders for one customer: 100
O-2 offers: O-2476, O-2230 (2 in all)
o-24 offers: O-2476 (1 in all)
O-1767 answer: -32602 You have no order O-1767.
O-7144 answer: -32602 You have no order O-7144.
El completado ofrece a cada llamador solo sus propios pedidos. Sobre toda la tienda, O-2 coincidiría con 501 pedidos, más de los que el límite permite en una sola respuesta, pero el cliente C-0127 que escribe O-2 recibe O-2476, O-2230 (2 in all) y nada más. Si escribe o-24 en minúsculas, obtiene O-2476 (1 in all), porque el manejador convierte primero a mayúsculas lo que escribió el usuario.
Leer el pedido de otro cliente, O-1767, devuelve -32602 You have no order O-1767., y leer O-7144, que no existe, devuelve -32602 You have no order O-7144.. Las dos respuestas solo se diferencian en el identificador, así que el llamador no puede saber si el pedido existe.
El límite solo importa a un cliente con más de 100 pedidos. El máximo que tiene un solo cliente en los datos de la tienda es 100, así que para cada cliente la API devuelve todos sus pedidos, y el manejador informa de un total. Un cliente con un pedido número 101 recibiría coincidencias solo de los 100 más recientes, sin total y con has_more en verdadero. La ejecución no puede mostrar ese caso, porque ningún cliente tiene tantos pedidos.
context.arguments se justifica con un prompt que recibe más de un argumento, como uno que restringe los identificadores de pedido a un cliente que el usuario eligió antes. Trátalo como entrada del usuario, nunca como autorización, porque quien llama al servidor decide lo que este dice. La especificación pide además que los servidores limiten la frecuencia de las peticiones de completado y que los clientes las agrupen (debounce), ya que un host puede enviar una por cada pulsación de tecla (completion).
Regla práctica: Completa argumentos solo con lo que el llamador puede leer, determinado por a quién representa el servidor, no por nada que contenga la petición. Filtra tú mismo por el prefijo escrito y mantén la lista dentro de 100 valores, porque el SDK no lo hará. Establece has_more siempre que la fuente que filtraste estuviera ya truncada, e informa de un total solo cuando hayas contado todas las coincidencias. Da a un registro inaccesible la misma respuesta de no encontrado que a uno inexistente, tanto en las lecturas como en los completados.
Avisa a los clientes cuando cambie un recurso
Un host que ha puesto un recurso delante de un modelo, como un pedido de la plantilla de pedidos, debe enterarse de los cambios; de lo contrario, sigue mostrando una copia desactualizada. En la revisión fijada, un cliente pide notificaciones de cambios con una sola solicitud, subscriptions/listen. Su filtro puede nombrar los URI de recursos que quiere vigilar (resourceSubscriptions) y pedir cambios en las listas (resourcesListChanged, toolsListChanged, promptsListChanged), y la respuesta es un flujo de notificaciones de larga duración (suscripciones).
subscriptions/listen reemplaza tres cosas de las revisiones de 2025: resources/subscribe, resources/unsubscribe y el flujo HTTP GET (registro de cambios). El Client.subscribe_resource del SDK está obsoleto, y solo se comunica con servidores de la era 2025 (mcp/client/client.py). Inventaría de qué depende el servidor antiguo explica cómo abandonarlo.
El flujo tiene una forma fija (suscripciones):
- El servidor envía primero
notifications/subscriptions/acknowledged, indicando el subconjunto del filtro que va a atender. - Después etiqueta cada notificación con
io.modelcontextprotocol/subscriptionId, el ID JSON-RPC de la solicitud listen, y "NO DEBE enviar tipos de notificación que el cliente no haya solicitado explícitamente". - Un mensaje
notifications/resources/updatedlleva el URI y nada más. Indica que el recurso cambió, no lo que contiene, así que el cliente debe volver a leerlo. - En stdio, el servidor no conserva el estado de las suscripciones tras una reconexión. Después de un flujo interrumpido, el cliente envía de nuevo
subscriptions/listeny vuelve a obtener lo que necesita.
En el SDK de Python, el código del servidor publica un cambio con await ctx.notify_resource_updated(uri). Eso entrega la actualización a un bus de suscripciones, del que lee cada flujo abierto (mcp/server/mcpserver/context.py). En el cliente, async with client.listen(resource_subscriptions=[...]) as changes envía la solicitud y espera el acuse de recibo. changes.honored contiene entonces lo que el servidor aceptó, y al iterar sobre changes se obtienen los eventos. Un cierre ordenado por parte del servidor termina el bucle, y una caída abrupta lanza SubscriptionLost (mcp/client/client.py, listen). No se reproduce nada y el SDK indica que un flujo interrumpido no es reanudable (mcp/server/subscriptions.py). El ejemplo de existencias muestra lo que eso cuesta.
La política de existencias de la tienda dice que un recuento negativo significa que hay que hacer un recuento físico, y KG-1018 tiene un recuento negativo en el almacén south. Para mostrar un cambio dentro de un mismo proceso, el ejemplo guarda los recuentos en la memoria del servidor, en lugar del sistema de existencias de la tienda. Publica el recuento de cada producto como shop://stock/{sku}, y añade una herramienta, set_on_hand, que el host de un almacén llama después de un recuento. La herramienta reemplaza un recuento y publica una actualización para el URI de ese producto. El cliente vigila KG-1018 y KG-9999, que no existe. Registra un recuento de otro producto, luego uno de KG-1018, y más tarde cierra el flujo y lo vuelve a abrir.
1"""Watches two products with subscriptions/listen, records recounts while a stream is open and while it is closed, and re-reads after each.2The point rests on the first event, which arrives, and on the re-listening line, which shows that nothing is replayed."""3import asyncio4import sys56import anyio7from mcp import Client, StdioServerParameters8from mcp.server.mcpserver import Context, MCPServer9from mcp.server.mcpserver.exceptions import ResourceNotFoundError1011from lib.shop_data import WAREHOUSES, load_shop12from lib.shop_reads import stock_summary1314server = MCPServer("shop-support", version="0.4.0")15counts = {(s.sku, s.warehouse): s.on_hand for s in load_shop().stock} # stands in for the shop's stock system161718@server.resource("shop://stock/{sku}", title="On-hand stock for one product", mime_type="application/json")19def stock(sku: str) -> dict:20 if (sku, WAREHOUSES[0]) not in counts: # a product exists if the first warehouse has a count for it21 raise ResourceNotFoundError(f"The shop sells no product {sku}.")22 return {warehouse: counts[sku, warehouse] for warehouse in WAREHOUSES}232425@server.tool()26async def set_on_hand(sku: str, warehouse: str, counted: int, ctx: Context) -> str:27 """Record a warehouse's recount of one product, replacing its on-hand count."""28 counts[sku, warehouse] = counted29 await ctx.notify_resource_updated(f"shop://stock/{sku}") # the exact URI clients watch; another spelling never matches30 return f"{sku} in {warehouse}: {counted}"313233async def main() -> None:34 watched = ["shop://stock/KG-1018", "shop://stock/KG-9999"] # KG-9999 doesn't exist35 async with Client(StdioServerParameters(command=sys.executable, args=[__file__, "--serve"], env={})) as client:36 async with client.listen(resource_subscriptions=watched) as changes:37 print("honoured:", " and ".join(changes.honored.resource_subscriptions))38 print("before:", await stock_summary(client, watched[0])) # watched[0] is KG-101839 # KG-1026 isn't watched, so this recount sends nothing on the stream40 await client.call_tool("set_on_hand", {"sku": "KG-1026", "warehouse": "north", "counted": 0})41 # KG-1018 is watched, so its update reaches the open stream42 await client.call_tool("set_on_hand", {"sku": "KG-1018", "warehouse": "south", "counted": 4})43 print("first event:", (await anext(changes)).uri)44 print("after:", await stock_summary(client, watched[0])) # watched[0] is KG-101845 # recorded while no stream is open, so no stream can hear it46 await client.call_tool("set_on_hand", {"sku": "KG-1018", "warehouse": "south", "counted": 3})47 async with client.listen(resource_subscriptions=watched) as changes:48 with anyio.move_on_after(1.0) as waited: # wait a second for anything replayed49 await anext(changes)50 print("events after re-listening:", 0 if waited.cancelled_caught else "at least 1")51 print("re-read:", await stock_summary(client, watched[0])) # watched[0] is KG-1018525354if __name__ == "__main__":55 server.run() if "--serve" in sys.argv else asyncio.run(main())
python stock-resource-changes.pyhonoured: shop://stock/KG-1018 and shop://stock/KG-9999
before: north 2, south -6
first event: shop://stock/KG-1018
after: north 2, south 4
events after re-listening: 0
re-read: north 2, south 3
El SDK atiende cada URI que un cliente pide, incluso uno que no existe. Aquí el acuse de recibo atiende ambos, shop://stock/KG-1018 and shop://stock/KG-9999, incluido el producto que la tienda no vende, y el SDK no comprueba si quien llama puede leer ninguno de los dos (mcp/server/subscriptions.py). Qué sale mal en producción vuelve sobre ello.
Un cambio hecho mientras un flujo está abierto llega al cliente como un evento, y el cliente vuelve a leer. El recuento de KG-1026 no envió nada por este flujo, porque nadie pidió vigilarlo, y el primer evento nombra shop://stock/KG-1018. KG-1018 se lee como north 2, south -6 antes del recuento y como north 2, south 4 después.
La notificación de un cambio hecho mientras nadie escucha se pierde para siempre. El cliente cerró el flujo, y un segundo recuento dejó el recuento de south en 3. En el flujo reabierto, una espera de un segundo encontró 0 eventos, y solo una lectura nueva, north 2, south 3, muestra el cambio.
El bus en memoria solo llega a los flujos de su propio proceso. Con dos réplicas del servidor, un cambio en una nunca llega a un flujo de la otra, así que las réplicas necesitan un bus compartido (suscripciones). Ejecutar réplicas sin sesiones pegajosas ejecuta el servidor de la tienda de esa forma.
Regla práctica: Vigila solo los recursos que el host ha puesto a disposición de un modelo o de un usuario, y trata cada evento como una señal para volver a leer, nunca como el nuevo valor. Vuelve a leer todo aquello de lo que dependes cada vez que abras un flujo, la primera vez y después de cada caída, porque nada se reproduce. Publica una actualización para el URI exacto que leen los clientes, desde la ruta de código que hace el cambio.
Esta parte aún no está traducida, así que está en inglés.
Package a workflow as a prompt
The resources in the previous sections give a host the shop's data. Some of the support team's work, though, is a fixed procedure that a person starts, such as reviewing a refund before anyone issues it. A prompt packages such a procedure as a named message template that the server offers and the user picks, for example as a slash command. The user decides when it's used, and the server writes it, as Prompts are templates the user chooses quoted.
A prompt has a name, an optional title and description, and arguments, each with a name, a description and whether it's required. A client lists prompts with prompts/list and fills one in with prompts/get, which returns messages. Each message has the role user or assistant and one content block: text, an image, audio, a resource link, or an embedded resource that carries a resource's contents inside the message. There is no system role, so a prompt is not a system prompt, and the host keeps its own. The same page says implementations "MUST carefully validate all prompt inputs and outputs to prevent injection attacks or unauthorized access to resources."
With the Python SDK, @server.prompt() takes the prompt's name from the function, its arguments from the parameters and its description from the docstring. The function returns the messages, and a bare string or content block becomes one user message (mcp/server/mcpserver/prompts/base.py). An MCPError the function raises reaches the client unchanged. But for an unknown prompt or a missing required argument, the SDK raises a plain ValueError (mcp/server/mcpserver/server.py, get_prompt), though the specification assigns -32602 to both (schema).
The support team reviews each refund request against the refund policy, which says that a refund above €150.00 needs a support lead to confirm it. Chapter 2's review_refund took only an order_id, and its one message told the model which tool and resource to fetch. Here the prompt gains a second argument, amount, and carries what the review needs itself. Before it calls anything, it checks that both arguments look like the shop's formats. Then it looks the order up through the shop's API and returns two user messages. The first embeds the refund policy under its URI, shop://policies/refund, so the host needn't read it separately. The second quotes the order and asks the review's three questions.
Filling the prompt in for order O-1145, whose customer asks for €343.49, shows the messages a model would receive. Three bad calls follow: a path where an order ID belongs, a missing argument and a misspelled prompt name.
1"""Packages a refund review as a prompt, with the refund policy embedded, the order quoted and the arguments checked first.2The point rests on the two messages, and on the three failures: a bad path gets Invalid Params, while a missing amount and a misspelled name both get an internal error."""3import asyncio4import json5import re6import sys78from mcp import Client, MCPError, StdioServerParameters9from mcp.server.mcpserver import MCPServer10from mcp.types import INVALID_PARAMS, EmbeddedResource, TextResourceContents1112from lib import loopback, shop_api, shop_reads13from lib.policies import policy1415server = MCPServer("shop-support", version="0.4.0")161718@server.prompt(title="Review a refund request")19async def review_refund(order_id: str, amount: str) -> list[EmbeddedResource | str]:20 """Check a customer's refund request against the refund policy before a person issues it."""21 # up to five whole digits and exactly two decimals, so 24.99 and 343.49 pass22 if not re.fullmatch(r"\d{1,5}\.\d{2}", amount):23 raise MCPError(INVALID_PARAMS, f"Amounts look like 24.99, not {amount!r}.")24 # the API is asked only for an ID in the right format, and None from it means no such order25 if not re.fullmatch(r"O-\d{4}", order_id) or (order := await shop_reads.get_json(f"/orders/{order_id}")) is None:26 raise MCPError(INVALID_PARAMS, f"No order {order_id!r}. Order IDs look like O-1873.")27 return [EmbeddedResource(type="resource", resource=TextResourceContents( # each item: one user message28 uri="shop://policies/refund", mime_type="text/markdown", text=policy("refund").text)),29 (f"Order {order_id}: {json.dumps(order)}\n\nThe customer asks for a refund of {amount}. "30 "From the policy and the order only: does it qualify, how much may the shop refund, "31 "and must a support lead confirm it?")]323334async def main() -> None:35 good = {"order_id": "O-1145", "amount": "343.49"} # the order, and the amount its customer asks for36 tries = {"path as order_id": ("review_refund", {**good, "order_id": "../refunds"}), # a path where an ID belongs37 "missing amount": ("review_refund", {"order_id": "O-1145"}),38 "unknown prompt": ("refund_review", good)} # misspelled: the prompt is review_refund39 with loopback.serve(shop_api.create_app()) as base_url:40 env = shop_api.server_env(base_url)41 async with Client(StdioServerParameters(command=sys.executable, args=[__file__, "--serve"], env=env)) as client:42 for n, message in enumerate((await client.get_prompt("review_refund", good)).messages, 1):43 print(f"message {n}:", message.role, message.content.type)44 for case, (name, arguments) in tries.items():45 try:46 await client.get_prompt(name, arguments)47 except MCPError as err:48 print(f"{case}:", err.error.code, err.error.message)495051if __name__ == "__main__":52 server.run() if "--serve" in sys.argv else asyncio.run(main())
python refund-review-prompt.pymessage 1: user resource
message 2: user text
path as order_id: -32602 No order '../refunds'. Order IDs look like O-1873.
missing amount: -32603 Internal server error
unknown prompt: -32603 Internal server error
The filled-in prompt is two messages. The first, user resource, embeds the refund policy itself, and the second, user text, carries the order and the questions. Nothing here calls a model. These messages are what a host sends a model when a person picks the prompt, and Run the host loop makes that turn.
The failures show where the SDK and the specification part. The path, ../refunds, never reached the shop's API, because the format check raised MCPError with INVALID_PARAMS, and the client got -32602 No order '../refunds'. Order IDs look like O-1873.. The two failures the SDK handles itself came back differently. A missing amount gave -32603 Internal server error, and the misspelled name gave -32603 Internal server error. Both carry the internal-error code rather than the -32602 the specification assigns, and the SDK's own message is hidden behind a generic one. So a host can't tell either mistake from a crash in the server.
Prompt arguments also become text that a model reads. A customer's words pasted into a free-text argument would reach the model inside a user message, which is one reason this prompt takes only an order ID and a decimal amount. Treat ticket text as untrusted data covers that path in general.
Working rule: Offer a prompt for a procedure a person starts by name, and keep its arguments to values with a format you can check. Embed the resources the procedure depends on, so the host needn't fetch them. Validate every argument before you use it, and raise MCPError with INVALID_PARAMS for a bad one, because the SDK's own checks answer with an internal error.
Elige entre un recurso y una herramienta
Coloca cada capacidad en la primitiva adecuada resolvió la mayor parte de la elección al preguntar quién decide cuándo se usan los datos. Dejó abierto un caso: los datos que son ambas cosas. Las secciones anteriores publicaron los mismos tipos de datos de la tienda que devuelven las herramientas de Da forma a las herramientas según las tareas, no según los endpoints: un pedido, desde get_order_status, y el stock de un producto, desde check_stock. Lo que sigue es criterio, no medición.
La plantilla de pedido permite que un host adjunte el pedido al que se refiere un ticket antes de que el modelo lea el ticket. get_order_status permite que el modelo, en cambio, busque un pedido que encuentre en el texto del ticket. Haz que ambas lecturas pasen por la misma llamada a la API, para que no puedan contradecirse.
Cuando una herramienta encuentra registros que el host podría querer conservar, puede devolver enlaces de recurso hacia ellos en lugar de su contenido completo, y el host lee los que necesite. La especificación no garantiza que esos enlaces aparezcan en un resultado de resources/list (herramientas), así que un servidor puede enlazar a registros a los que solo una plantilla da acceso.
Regla práctica: Ofrece un registro como recurso y como herramienta cuando los hosts lo adjuntan y los modelos lo buscan, y sirve ambos desde una misma ruta de código para que no puedan contradecirse. Cuando una herramienta encuentra registros que el host podría conservar, devuelve enlaces de recurso hacia ellos en lugar de su contenido.
Qué falla en producción
Los recursos y los prompts de la tienda funcionan en una máquina con un solo cliente. En producción, con muchos clientes, cachés, réplicas y hosts que la tienda no escribió, fallan de unas pocas maneras, y cada una tiene un síntoma que puedes detectar a tiempo.
Una lectura por usuario recibe un ámbito de caché público. Una caché "NO DEBE" compartirse entre contextos de autorización, y public le indica que el resultado puede almacenarse (caching). MCPServer no puede fijar la indicación en cada función, así que cache_hints fija una indicación por método, y un servidor que sirve políticas públicas y pedidos privados da la misma indicación en cada resources/read (mcp/server/mcpserver/server.py, _handle_read_resource). Mantén resources/read como private en un servidor que sirve cualquier dato por usuario, o da a las políticas un servidor propio. La señal es un usuario que ve un pedido que no es suyo, algo que ninguna prueba con un solo usuario detecta. Y ttlMs no es un intervalo de sondeo: los clientes "NO DEBERÍAN" sondear según ese valor.
Las listas cambian entre conexiones. resources/list y prompts/list no deben variar por conexión, como indicó Cache list results sobre la lista de herramientas. Una lista puede variar según la autorización de la solicitud, y puede cambiar con el tiempo si el servidor envía una notificación de cambio en la lista (recursos, prompts). Un servidor que añade un recurso después de una llamada a una herramienta rompe la caché de todos los clientes. Se nota como una lista que cambia después de una llamada a una herramienta, o que cambia sin notificación de cambio en la lista.
Un cliente observa lo que no puede leer. El SDK acepta cualquier URI que un cliente pida observar, como mostró el ejemplo de stock con un producto que la tienda no vende. Un cliente que observe el pedido de otro cliente sabría que ese pedido existe y cuándo cambió. Pon un middleware en subscriptions/listen que rechace los URI que el llamador no puede leer (suscripciones). Vigila que ningún acuse de recibo repita URI que el llamador nunca podría leer.
Una actualización nunca coincide. MCPServer compara los URI como cadenas exactas (suscripciones), así que un cliente que observa shop://stock/kg-1018 nunca se entera de shop://stock/KG-1018. La especificación también permite que una actualización nombre un subrecurso del URI observado (esquema), y MCPServer nunca coincide con ninguno. La pista es un cliente que solo se actualiza al reconectarse. Publica el URI exacto que producen tus plantillas, y normaliza los IDs antes de construir un URI.
Un flujo caído pasa desapercibido. No se reproduce nada, así que un host que pierde su flujo y nunca vuelve a escuchar muestra datos obsoletos indefinidamente. Uno que vuelve a escuchar sin volver a leer pierde todos los cambios hechos mientras estuvo desconectado, como mostró el ejemplo de stock (mcp/server/subscriptions.py). Captura SubscriptionLost, vuelve a escuchar y luego vuelve a leer.
La autocompletación se convierte en un punto de enumeración. Un manejador que completa a partir de cada registro, o que confía en context.arguments para el acceso, permite que cualquiera liste lo que existe, una tecla a la vez. Un host que envía una solicitud por cada tecla también multiplica la carga (completado). Limita las sugerencias al llamador, pon un tope a su número, limita la tasa por llamador, y vigila las tasas de solicitudes de completado como vigilarías los intentos de inicio de sesión.
Los errores de prompts parecen fallos. El SDK responde a un prompt desconocido o a un argumento faltante con -32603, como mostró el ejemplo del prompt, así que los registros de un host mezclan los errores de los usuarios con las fallas del servidor. Lanza MCPError con INVALID_PARAMS por cada argumento que rechaces, y configura alertas para los errores internos que queden.
Regla práctica: Prueba los recursos y los prompts con dos clientes antes de que lleguen a producción. Ninguno debe poder ver, completar u observar los registros del otro, y ninguno debería ver un cambio de lista sin una notificación de cambio en la lista. Comprueba que cada resources/read de datos de un usuario lleve el ámbito private, y que un host se recupere de un flujo caído volviendo a escuchar y volviendo a leer.
Decisiones que tomó este capítulo
- Las políticas de la tienda son seis recursos estáticos en
shop://policies/{slug}, servidos desde archivos Markdown escritos para el libro, con la política de reembolsos con prioridad 1.0 por decisión de criterio. - La lista y las lecturas de las políticas son
publicdurante una hora, porque son las mismas para cada solicitante. Los pedidos mantienen el valor predeterminadoprivate. - Los pedidos son una plantilla de recurso,
shop://orders/{order_id}, sobre el mismo endpoint de la API queget_order_status, y una búsqueda sin resultado lanzaResourceNotFoundErrorcon -32602. - El
ResourceSecuritydel SDK permanece activado, y los manejadores siguen comprobando el formato de lo que reciben. - El autocompletado ofrece solo los pedidos propios de quien llama, del más reciente al más antiguo y limitados por el límite de 100 de la API, con
has_morecuando la API retuvo más. Un pedido de otro cliente se lee como no encontrado. - En nombre de quién actúa el servidor se toma del entorno a través de stdio. Por HTTP, el sujeto del token indica quién llama: en el host de soporte, un miembro del personal, con el cliente tomado del registro del ticket (Autorizar clientes con OAuth, Evitar que el servidor actúe como un diputado confundido).
- El ejemplo de inventario mantiene los recuentos en la memoria del servidor, en lugar del sistema de inventario de la tienda, y la herramienta
set_on_handpublica la actualización desde la ruta de código que cambia el recuento. - Las notificaciones de cambios usan
subscriptions/listen, nuncaresources/subscribe, y el cliente vuelve a leer en cada evento y en cada nuevo flujo. - Ninguna llamada a un modelo en este capítulo. Los mensajes del prompt son la entrada de un turno de modelo que el bucle del host del libro realizará más adelante.
- El prompt
review_refundincorpora la política de reembolsos, comprueba primero los formatos de sus argumentos y lanzaMCPErrorconINVALID_PARAMSpor su cuenta. - Los datos que adjunta el host son un recurso, y los datos que el modelo consulta son una herramienta. Un registro puede ser ambas cosas, servido desde una misma ruta de código.
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.