Serve data as resources and prompts
Cerca de 34 minutos min de leitura, com 5 exemplos em 8 seções.
Traduzido com IA. Verificado por pessoas em inglês. Como fazemos os livros
Traduzido do livro em inglês, edição 2026.11.14. Leia o original
Esta parte ainda não foi traduzida, por isso está em 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 ainda não foi traduzida, por isso está em 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.
Endereçar registros com modelos de recurso
As seis políticas da seção anterior servem para uma lista, mas os pedidos da loja não. Os dados contêm 501 pedidos cujos IDs começam apenas com O-2, e um recurso para cada um seria inútil para um host e caro de servir. Um modelo de recurso nomeia muitos recursos com um único modelo de URI, escrito na sintaxe da RFC 6570 (RFC 6570). Um cliente lista os modelos com resources/templates/list, preenche as variáveis e lê o resultado com resources/read (recursos).
No SDK Python, o URI passado a @server.resource() define o tipo. Chaves em volta de uma variável registram um modelo, e os parâmetros da função devem corresponder às variáveis. Um URI sem chaves registra um recurso estático (mcp/server/mcpserver/server.py, resource). O valor retornado define o conteúdo: um str gera texto, bytes geram um blob, e qualquer outro valor é convertido para JSON.
Um modelo também muda o que significa um erro de leitura (recurso inexistente). A leitura de um recurso que não existe falha, na revisão fixada, com o erro JSON-RPC -32602, Invalid Params, e o URI vai no data do erro. O servidor "NÃO DEVE retornar um array contents vazio" em vez disso (recursos). A revisão 2025-11-25 usava -32002 para o mesmo caso, e os clientes ainda devem aceitar esse código de servidores mais antigos (registro de mudanças). Em MCPServer, uma função obtém -32602 ao levantar ResourceNotFoundError. Qualquer outro ResourceError vira -32603, e um recurso, diferentemente de uma ferramenta, não tem um resultado isError para sinalizar falha (tratamento de erros).
O modelo de pedidos da loja é shop://orders/{order_id}, e sua função encapsula GET /orders/{order_id} na API da loja, o mesmo endpoint que get_order_status também encapsula. Ela levanta ResourceNotFoundError quando a API responde 404. Um pedido pertence a um único cliente, então a leitura mantém a dica de cache padrão do SDK, private com duração de 0. A página de cache indica private como o escopo para os resultados de resources/read "que dependem do usuário autenticado" (cache). Antes que a API veja qualquer coisa, a função verifica se a variável tem a forma de um ID de pedido, O- seguido de quatro dígitos, e levanta ResourceNotFoundError se não tiver, de modo que um ID malformado nunca chega à API.
Quatro leituras, um sucesso e três tipos de falta: um pedido real, um pedido que não existe, um ID no formato errado e um URI cuja variável tenta sair do caminho do 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
O modelo aparece listado como shop://orders/{order_id}, e o pedido O-2476 é lido como shipped, com o escopo de cache private.
As três faltas falham com o mesmo código, -32602, mas suas mensagens vêm de lugares diferentes. O pedido desconhecido, O-7144, recebe a mensagem do próprio handler, e seu URI volta nos dados do erro, shop://orders/O-7144. O ID 2476 recebe a mensagem da verificação de formato, Order IDs look like O-1873, not '2476'..
A leitura de traversal também falha, mas sua mensagem é a do SDK, Unknown resource: shop://orders/..%2F..%2Frefunds, não a do handler. O SDK decodificou a variável para ../../refunds, encontrou .. segmentos de caminho nela e recusou o URI antes que a função rodasse. Sem essa recusa, o handler teria enviado ../../refunds no caminho da requisição para a API da loja.
Essa recusa é ResourceSecurity, que por padrão rejeita segmentos .., caminhos absolutos e bytes NUL nas variáveis de modelo, qualquer que seja a codificação usada no URI (mcp/server/mcpserver/resources/templates.py). A especificação exige que os servidores validem todo URI de recurso (recursos), e a verificação do SDK reforça isso sem substituí-la. Ela não impede 2476, que passa por ResourceSecurity, então só a verificação de formato do handler pega esse caso.
Este modelo lê qualquer pedido para quem tiver a chave de API do servidor, o que serve ao host da equipe de suporte. A próxima seção restringe as leituras a um único cliente.
Regra prática: Use um modelo de recurso para registros que compartilham uma forma e um ID. Retorne o JSON da própria API e levante ResourceNotFoundError para uma falta, o que dá ao cliente -32602 com o URI. Mantenha o escopo private para qualquer coisa que pertença a um usuário. Deixe o ResourceSecurity do SDK ativado e valide você mesmo o formato da variável. Isente uma variável da verificação somente quando ela precisar carregar um caminho, e então verifique o caminho você mesmo.
Completar argumentos para o usuário
Um host que mostra o modelo de pedido da seção anterior a uma pessoa precisa que ela preencha order_id, e poucas pessoas se lembram de IDs de pedido. A completação de argumentos permite que o host peça ao servidor sugestões enquanto o usuário digita. O host envia completion/complete com uma referência, seja ref/resource com o URI de um template, seja ref/prompt com o nome de um prompt, além do nome do argumento e do seu valor parcial. Ele pode incluir context.arguments, os valores que o usuário já escolheu para outros argumentos. O resultado traz values, no máximo 100 deles, com um total opcional e um hasMore. Um servidor que oferece completação declara a capacidade completions (completação).
Um manipulador @server.completion(), no SDK Python, atende a todos os templates e prompts do servidor. Ele recebe a referência, o argumento e o contexto, e devolve um Completion ou None. Registrá-lo declara a capacidade. O SDK não filtra o que ele devolve, então tudo o que estiver em values é o que a interface mostra (completações). Ele também não aplica o limite de 100 itens. O tipo Completion diz que não deve exceder 100 itens, mas nada verifica isso (mcp_types/_types.py), então o manipulador precisa limitar a lista por conta própria.
A completação também é uma consulta, e uma consulta pode vazar informação. A especificação exige que os servidores controlem o acesso a sugestões sensíveis, o que impede que a completação revele informações que não deveria revelar (completação). Um manipulador que completasse IDs de pedidos de toda a loja diria a qualquer pessoa que digitasse O-2 quais pedidos da loja existem.
Por isso, o manipulador completa apenas os pedidos do cliente em nome de quem o servidor atua. Via stdio, o host informa esse cliente no ambiente do servidor, ao passar a chave de API da loja. Aqui SHOP_CUSTOMER_ID é C-0127, o cliente que fez o pedido O-2476. Via HTTP, Autorizar clientes com OAuth substitui a variável pelo que diz um token de acesso. O token de um host de suporte identifica um integrante da equipe, então o cliente vem do ticket que o servidor consulta (o subject do token só é o cliente onde os próprios clientes fazem login; veja Evite que o servidor atue como um deputado confuso).
O manipulador pede à API da loja os pedidos desse cliente e mantém os que começam com o que o usuário digitou. A API devolve no máximo 100 pedidos de um cliente, do mais recente para o mais antigo (examples/lib/shop_api.py), de modo que a resposta nunca ultrapassa o limite do protocolo. O manipulador também mantém essa ordem: num ticket de suporte, os pedidos mais recentes são os mais prováveis, e a especificação pede sugestões "ordenadas por relevância" (completação).
A resposta da API também traz o número total de pedidos do cliente. Quando esse total é maior do que o que a API devolveu, pedidos mais antigos podem corresponder também, então o manipulador deixa total de fora e define has_more. Caso contrário, informa o número de correspondências como total. O modelo de pedido aplica o mesmo escopo às leituras: o pedido de outro cliente recebe a mesma resposta de não encontrado que um pedido inexistente. Um módulo compartilhado, lib.shop_reads, contém o auxiliar assíncrono que os dois manipuladores usam para chamar a API da loja. A execução digita dois prefixos e lê dois pedidos que o chamador não pode 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.
A completação oferece a cada chamador apenas os seus próprios pedidos. Em toda a loja, O-2 corresponderia a 501 pedidos, mais do que o limite permite em uma única resposta, mas o cliente C-0127 que digita O-2 recebe O-2476, O-2230 (2 in all) e nada além disso. Digitar o-24 em minúsculas retorna O-2476 (1 in all), porque o manipulador converte primeiro para maiúsculas o que o usuário digitou.
Ler o pedido de outro cliente, O-1767, retorna -32602 You have no order O-1767., e ler O-7144, que não existe, retorna -32602 You have no order O-7144.. As duas respostas diferem apenas no ID, então quem chama não consegue saber se o pedido existe.
O limite só importa para um cliente com mais de 100 pedidos. O maior número de pedidos que qualquer cliente tem nos dados da loja é 100, então, para todos os clientes, a API devolve todos os pedidos e o manipulador informa um total. Um cliente com um 101º pedido receberia sugestões apenas dos 100 mais recentes, sem total e com has_more verdadeiro. A execução não consegue mostrar esse caso, já que nenhum cliente tem tantos pedidos.
context.arguments se justifica com um prompt que recebe mais de um argumento, como um que restringe IDs de pedido a um cliente escolhido antes pelo usuário. Trate-o como entrada do usuário, nunca como autorização, pois quem chama o servidor escolhe o conteúdo dele. A especificação também pede que os servidores limitem a taxa de requisições de completação e que os clientes apliquem debounce, já que um host pode enviar uma requisição a cada tecla digitada (completação).
Regra prática: Complete os argumentos apenas com o que quem chama pode ler, decidido por quem o servidor atua em nome de, e não por nada que esteja na requisição. Filtre você mesmo pelo prefixo digitado e mantenha a lista em no máximo 100 valores, porque o SDK não faz isso. Defina has_more sempre que a fonte filtrada tiver sido ela mesma truncada, e informe um total somente quando tiver contado todas as correspondências. Dê a um registro inacessível a mesma resposta de não encontrado de um registro inexistente, tanto em leituras quanto em completações.
Avise os clientes quando um recurso mudar
Um host que colocou um recurso à frente de um modelo, como um pedido do modelo de pedido, precisa saber das mudanças, ou continuará exibindo uma cópia desatualizada. Na revisão fixada, um cliente pede notificações de mudança com uma única requisição, subscriptions/listen. O filtro dela pode nomear URIs de recursos a observar (resourceSubscriptions) e pedir mudanças nas listas (resourcesListChanged, toolsListChanged, promptsListChanged), e a resposta é um fluxo de notificações de longa duração (assinaturas).
subscriptions/listen substitui três mecanismos das revisões de 2025: resources/subscribe, resources/unsubscribe e o fluxo HTTP GET (changelog). O Client.subscribe_resource do SDK está obsoleto, e ele se comunica apenas com servidores da era 2025 (mcp/client/client.py). Faça um inventário das dependências do servidor antigo cobre a migração para longe dele.
O fluxo tem um formato fixo (assinaturas):
- O servidor envia primeiro
notifications/subscriptions/acknowledged, nomeando o subconjunto do filtro que vai honrar. - Em seguida, marca cada notificação com
io.modelcontextprotocol/subscriptionId, o ID JSON-RPC da requisição de escuta, e "NÃO DEVE enviar tipos de notificação que o cliente não tenha solicitado explicitamente." - Uma mensagem
notifications/resources/updatedtraz apenas a URI. Ela informa que o recurso mudou, e não o que ele contém, por isso o cliente o lê novamente. - Em stdio, o servidor não mantém estado de assinatura entre reconexões. Depois de um fluxo interrompido, o cliente envia
subscriptions/listende novo e busca novamente o que depende.
No SDK Python, o código do servidor publica uma mudança com await ctx.notify_resource_updated(uri). Isso entrega a atualização a um barramento de assinaturas, do qual todo fluxo aberto lê (mcp/server/mcpserver/context.py). No cliente, async with client.listen(resource_subscriptions=[...]) as changes envia a requisição e aguarda a confirmação. changes.honored então contém o que o servidor aceitou, e iterar sobre changes produz eventos. Um encerramento gracioso pelo servidor finaliza o laço, e uma queda abrupta lança SubscriptionLost (mcp/client/client.py, listen). Nada é reenviado, e o SDK informa que um fluxo interrompido não pode ser retomado (mcp/server/subscriptions.py). O exemplo de estoque mostra o custo disso.
A política de estoque da loja diz que uma contagem negativa indica que é preciso recontar, e KG-1018 tem contagem negativa no depósito south. Para mostrar uma mudança dentro de um único processo, o exemplo mantém as contagens na memória do servidor, no lugar do sistema de estoque da loja. Ele publica as contagens de cada produto como shop://stock/{sku} e acrescenta uma ferramenta, set_on_hand, que o host de um depósito chamaria após uma recontagem. A ferramenta substitui uma contagem e publica uma atualização para a URI desse produto. O cliente observa KG-1018 e KG-9999, que não existe. Ele registra a recontagem de outro produto, depois a de KG-1018, e, mais tarde, fecha o fluxo e o abre de novo.
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
O SDK honra toda URI que um cliente pede, mesmo uma que não existe. Aqui a confirmação honra as duas, shop://stock/KG-1018 and shop://stock/KG-9999, inclusive o produto que a loja não vende, e o SDK não verifica se quem chama pode ler qualquer uma delas (mcp/server/subscriptions.py). O que dá errado em produção volta a esse ponto.
Uma mudança feita enquanto um fluxo está aberto chega ao cliente como evento, e o cliente lê novamente. A recontagem de KG-1026 não enviou nada neste fluxo, porque ninguém pediu para observar esse produto, e o primeiro evento nomeia shop://stock/KG-1018. KG-1018 lê north 2, south -6 antes da recontagem e north 2, south 4 depois dela.
A notificação de uma mudança feita enquanto ninguém escuta se perde para sempre. O cliente fechou o fluxo, e uma segunda recontagem definiu a contagem de south como 3. No fluxo reaberto, uma espera de um segundo trouxe 0 eventos, e somente uma leitura nova, north 2, south 3, mostra a mudança.
O barramento em memória alcança apenas os fluxos do próprio processo. Com duas réplicas do servidor, uma mudança em uma nunca chega a um fluxo na outra, por isso as réplicas precisam de um barramento compartilhado (assinaturas). Execute réplicas sem sticky sessions executa o servidor da loja dessa forma.
Regra prática: Observe apenas os recursos que o host colocou à frente de um modelo ou de um usuário, e trate cada evento como um sinal para ler novamente, nunca como o novo valor. Releia tudo de que você depende sempre que abrir um fluxo, na primeira vez e após cada queda, porque nada é reenviado. Publique uma atualização para a URI exata que os clientes leem, a partir do código que faz a mudança.
Esta parte ainda não foi traduzida, por isso está em 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.
Escolha entre um recurso e uma ferramenta
Coloque cada capacidade no primitivo certo resolveu a maior parte da escolha ao perguntar quem decide quando os dados são usados. Restou um caso em aberto: dados que são ambos. As seções anteriores publicaram os mesmos tipos de dados da loja que as ferramentas de Modele ferramentas em torno de tarefas, não de endpoints retornam: um pedido, de get_order_status, e o estoque de um produto, de check_stock. O que segue é uma questão de julgamento, não de medição.
O template de pedido permite que um host anexe o pedido ao qual um chamado se refere antes que o modelo leia o chamado. get_order_status permite que o modelo, em vez disso, consulte um pedido que encontra no texto do chamado. Mantenha as duas leituras pela mesma chamada de API, para que não possam divergir.
Quando uma ferramenta encontra registros que o host pode querer manter, ela pode retornar links de recurso para eles em vez de seu conteúdo completo, e o host lê os que precisa. A especificação não garante que esses links apareçam em um resultado de resources/list (ferramentas), então um servidor pode apontar para registros que só um template endereça.
Regra prática: Ofereça um registro como recurso e como ferramenta quando hosts o anexam e modelos o consultam, e sirva os dois a partir de um mesmo caminho de código, para que não possam divergir. Quando uma ferramenta encontrar registros que o host pode manter, retorne links de recurso para eles em vez de seus conteúdos.
O que dá errado em produção
A loja tem recursos e prompts que funcionam em uma máquina, com um único chamador. Em produção, com muitos chamadores, caches, réplicas e hosts que a loja não escreveu, eles falham de algumas maneiras, e cada uma delas tem um sintoma que você pode detectar cedo.
Uma leitura por usuário recebe um escopo de cache público. Um cache "NÃO DEVE" ser compartilhado entre contextos de autorização, e public informa que o resultado pode ser compartilhado (cache). MCPServer não consegue definir a dica em cada função, então cache_hints define uma dica por método, e um servidor que serve políticas públicas e pedidos privados aplica a mesma dica em todo resources/read (mcp/server/mcpserver/server.py, _handle_read_resource). Mantenha resources/read como private em um servidor que sirva qualquer coisa por usuário, ou dê às políticas um servidor próprio. O sinal é um usuário que vê um pedido que não é dele, algo que nenhum teste com um único usuário detecta. E ttlMs não é um intervalo de polling: os clientes "NÃO DEVERIAM" fazer polling com base nele.
As listas diferem entre conexões. resources/list e prompts/list não podem variar por conexão, como Cache de resultados de listagem disse sobre a lista de ferramentas. Uma lista pode variar conforme a autorização da requisição, e pode mudar com o tempo se o servidor enviar uma notificação de mudança de lista (recursos, prompts). Um servidor que adiciona um recurso depois de uma chamada de ferramenta quebra o cache de todos os clientes. Isso aparece como uma lista que muda após uma chamada de ferramenta, ou que muda sem nenhuma notificação de mudança de lista.
Um cliente observa o que não consegue ler. O SDK atende a todo URI que um cliente pede para observar, como mostrou o exemplo de estoque com um produto que a loja não vende. Um cliente que observa o pedido de outro cliente ficaria sabendo que o pedido existe e quando ele mudou. Coloque um middleware em subscriptions/listen que rejeite URIs que o chamador não pode ler (assinaturas). Fique atento a uma confirmação que repete URIs que o chamador nunca poderia ler.
Uma atualização nunca corresponde. MCPServer compara URIs como strings exatas (assinaturas), então um cliente que observa shop://stock/kg-1018 nunca fica sabendo de shop://stock/KG-1018. A especificação também permite que uma atualização nomeie um subrecurso do URI observado (schema), e MCPServer nunca corresponde a um deles. O sinal é um cliente que só se atualiza quando reconecta. Publique exatamente o URI que seus templates produzem e normalize os IDs antes de montar um URI.
Um fluxo interrompido passa despercebido. Nada é reenviado, então um host que perde seu fluxo e nunca volta a escutar mostra dados desatualizados indefinidamente. Um host que volta a escutar sem reler perde todas as mudanças feitas enquanto esteve fora, como mostrou o exemplo de estoque (mcp/server/subscriptions.py). Capture SubscriptionLost, volte a escutar e, então, releia.
A completação vira um endpoint de enumeração. Um handler que completa a partir de todos os registros, ou que confia em context.arguments para controle de acesso, permite que qualquer pessoa liste o que existe, uma tecla por vez. Um host que envia uma requisição por tecla também multiplica a carga (completação). Limite as sugestões ao chamador, imponha um limite máximo, aplique limite de taxa por chamador e monitore as taxas de requisições de completação como você faria com tentativas de login.
Erros de prompt parecem falhas. O SDK responde a um prompt desconhecido ou a um argumento ausente com -32603, como mostrou o exemplo de prompt, e por isso os logs de um host misturam erros dos usuários com falhas do servidor. Lance MCPError com INVALID_PARAMS para cada argumento que você rejeitar, e emita alertas para os erros internos que continuarem ocorrendo.
Regra prática: Teste recursos e prompts com dois chamadores antes que cheguem à produção. Nenhum dos dois pode ver, completar ou observar os registros do outro, e nenhum deles deveria ver uma lista mudar sem uma notificação de mudança de lista. Verifique se cada resources/read de dados de um usuário carrega o escopo private, e se um host se recupera de um fluxo interrompido voltando a escutar e relendo.
Decisões tomadas neste capítulo
- As políticas da loja são seis recursos estáticos em
shop://policies/{slug}, servidos a partir de arquivos Markdown escritos para o livro, com a política de reembolso na prioridade 1.0 por julgamento. - A listagem e as leituras das políticas são
publicpor uma hora, porque são as mesmas para todos os chamadores. Os pedidos mantêm o padrãoprivate. - Os pedidos são um modelo de recurso,
shop://orders/{order_id}, sobre o mesmo endpoint da API queget_order_status, e uma busca sem resultado lançaResourceNotFoundErrorcom código -32602. - O
ResourceSecuritydo SDK continua ativado, e os handlers ainda verificam o formato do que recebem. - A completion oferece apenas os pedidos do próprio cliente, do mais recente para o mais antigo, limitada pelo limite de 100 da API, com
has_morequando a API reteve mais. Um pedido de outro cliente aparece como não encontrado. - A identidade em nome de quem o servidor age vem do ambiente via stdio. Via HTTP, o subject do token indica quem está chamando: no host de suporte, um funcionário da equipe, com o cliente obtido do registro do chamado (Autorize clientes com OAuth, Impeça que o servidor atue como um "confused deputy").
- O exemplo de estoque mantém as contagens na memória do servidor, no lugar do sistema de estoque da loja, e a ferramenta
set_on_handpublica a atualização a partir do caminho de código que altera a contagem. - As notificações de mudança usam
subscriptions/listen, nuncaresources/subscribe, e o cliente relê a cada evento e a cada novo stream. - Nenhuma chamada a modelo neste capítulo. As mensagens do prompt são a entrada de um turno de modelo que o loop do host do livro executa depois.
- O prompt
review_refundincorpora a política de reembolso, verifica antes o formato dos seus argumentos e lançaMCPErrorcomINVALID_PARAMSpor conta própria. - Dados que o host anexa são um recurso, e dados que o modelo consulta são uma ferramenta. Um registro pode ser as duas coisas, servido a partir do mesmo caminho de código.
Este capítulo, nesta edição
Edição 2026.11.14Exemplos aprovados em 19 de nov de 20265 de 5 exemplos exemplos deste capítulo passam
Traduzido do livro em inglês, edição 2026.11.14.