O que o MCP acrescenta a uma API
Cerca de 35 minutos min de leitura, com 6 exemplos em 11 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
Nesta página
- Separe o host, o cliente e o servidor
- Put each capability in the right primitive
- Ferramentas são ações que o modelo escolhe
- Recursos são dados que a aplicação escolhe
- Prompts são modelos que o usuário escolhe
- Envie a versão e as capacidades em cada requisição
- Handle a version the server doesn't support
- Armazenar em cache os resultados de listagem
- Keep an HTTP API where MCP adds nothing
- O que dá errado em produção
- Decisões tomadas neste capítulo
Ao final deste capítulo, você saberá dizer o que o host, o cliente e o servidor fazem, colocar cada uma das capacidades da loja na primitiva correta do Model Context Protocol, ler a versão e as capacidades que toda requisição carrega, e decidir quando a loja deve manter uma API HTTP comum. Suas afirmações e exemplos estão ligados à revisão 2026-07-28 da especificação e a mcp, o SDK para Python, na versão 2.3.0.
O que este capítulo precisa da loja, a loja online fictícia de utensílios de cozinha e jardim da Fernhill Supply, é de uma API HTTP cuja consulta de pedidos o host da equipe de suporte já usa. MCP de ponta a ponta colocou essa consulta atrás de um servidor Model Context Protocol (MCP), para que um modelo no host da equipe de suporte pudesse chamá-la. Esse servidor tinha uma única ferramenta. A equipe de suporte quer mais: a política de reembolso, que o host deve ter à mão sempre que um chamado mencionar dinheiro, e uma maneira padrão de revisar um pedido de reembolso. Enquanto isso, a equipe de armazém, que lê os níveis de estoque da mesma API todas as noites, pergunta se ela também deveria migrar para o MCP.
As duas perguntas dependem do que o MCP acrescenta a uma API que já funciona. Um cliente HTTP é escrito com base em endpoints sobre os quais seu desenvolvedor leu. Um cliente MCP descobre em tempo de execução o que um servidor oferece, em uma forma que um modelo consegue ler, e o protocolo define quem decide quando cada capacidade é usada. Este capítulo examina essas adições uma a uma, mede o que elas custam na rede e termina com os casos em que a loja não deve pagar por elas.
Separe o host, o cliente e o servidor
O servidor do Encapsule um endpoint como ferramenta rodou atrás de um cliente que o código daquele capítulo dirigia. Antes que a loja acrescente mais coisas a ele, seja exato sobre qual parte faz o quê, porque as garantias do MCP se aplicam aos papéis, não aos processos.
A especificação nomeia três papéis (arquitetura). O host é a aplicação em que o usuário trabalha. Ele cria clientes, mantém a conversa com o modelo e aplica políticas de segurança e consentimento. Um cliente é a conexão do host com um servidor: "Each client is created by the host and communicates with exactly one server". Um servidor expõe capacidades, como ferramentas, e não sabe nada além disso sobre o host. A mesma página define um princípio de projeto que decorre dessa divisão: um servidor não deve ver a conversa inteira, nem olhar para outros servidores. O host decide o que cada servidor vê, e tudo que atravessa servidores acontece no host.
O host da equipe de suporte da loja desempenha o papel de host e executa o loop de host do livro. Cada servidor que ele usa ganha seu próprio cliente: neste capítulo, um, shop-support, e em Detecte descrições de ferramentas envenenadas um segundo servidor, de um parceiro, que jamais deve saber o que o servidor da loja devolveu. shop-support é o servidor deste capítulo. Ele mantém a ferramenta get_order_status do capítulo 1 e acrescenta um recurso, a política de reembolso, e um prompt, review_refund, de modo que cada tipo de capacidade apareça uma vez. Como todo exemplo de servidor aqui, o arquivo define o servidor e, executado sem argumentos, inicia um cliente que o lança com --serve.
A primeira coisa que um cliente faz é perguntar ao servidor o que ele oferece. Uma capacidade é algo que um cliente ou servidor declara suportar, como um servidor que oferece ferramentas ou um cliente que pode responder a uma request de entrada. Na revisão fixada, isso exige uma única requisição, server/discover, cuja resposta traz as versões suportadas pelo servidor, suas capacidades e seu nome, de modo que um cliente possa exibir tudo o que um servidor suporta a partir dessa única resposta (descoberta). Em seguida, o cliente lista cada tipo de capacidade com tools/list, resources/list e prompts/list. No seu modo automático padrão, mcp.Client envia server/discover ao abrir, e guarda a resposta como client.session.discover_result (mcp/client/session.py).
1"""shop-support, the chapter 2 server, offers one tool, one resource and one prompt. Run bare, the file starts it as a2client, which prints what it discovers: the tools, resources and prompts lines are the ones the prose reads."""3import asyncio4import os5import sys67import httpx28from mcp import Client, StdioServerParameters9from mcp.server.caching import CacheHint10from mcp.server.mcpserver import MCPServer11from mcp.server.mcpserver.exceptions import ToolError1213from lib.policies import policy1415# ttl_ms is in milliseconds, so 300_000 is five minutes; "public" lets a shared cache reuse the tool list.16server = MCPServer("shop-support", version="0.2.0",17 cache_hints={"tools/list": CacheHint(ttl_ms=300_000, scope="public")})181920@server.tool()21def get_order_status(order_id: str) -> dict:22 """Look up one of the shop's orders by its ID, such as O-1873: its status, dates, lines and total."""23 response = httpx2.get(f"{os.environ['SHOP_API_URL']}/orders/{order_id}",24 headers={"X-API-Key": os.environ["SHOP_API_KEY"]}, timeout=5.0) # timeout in seconds25 if response.status_code == 404:26 raise ToolError(f"The shop has no order {order_id}. Order IDs look like O-1873.")27 response.raise_for_status()28 return response.json()293031@server.resource("shop://policies/refund", name="refund-policy", mime_type="text/markdown")32def refund_policy() -> str:33 return policy("refund").path.read_text(encoding="utf-8") # examples/data/shop/policies/refund.md343536@server.prompt()37def review_refund(order_id: str) -> str:38 """Review a customer's refund request for one order against the shop's refund policy."""39 return (f"Review the refund request for order {order_id}. Look up the order with get_order_status, read the "40 "refund policy at shop://policies/refund, and say whether the refund needs a person to confirm it.")414243async def main() -> None:44 # No variables are passed: listing never calls the tool, so the server needs none of the shop's API settings.45 async with Client(StdioServerParameters(command=sys.executable, args=[__file__, "--serve"], env={})) as client:46 print("server:", client.server_info.name, client.server_info.version)47 print("protocol revision:", client.protocol_version)48 # auto mode keeps the server/discover answer on the session, so the versions come from there49 print("supported versions:", ", ".join(client.session.discover_result.supported_versions))50 # exclude_none drops the capabilities the server didn't declare, leaving only the ones it offers51 print("capabilities:", ", ".join(sorted(client.server_capabilities.model_dump(exclude_none=True))))52 print("tools:", ", ".join(t.name for t in (await client.list_tools()).tools))53 print("resources:", ", ".join(str(r.uri) for r in (await client.list_resources()).resources))54 print("prompts:", ", ".join(p.name for p in (await client.list_prompts()).prompts))555657if __name__ == "__main__":58 # With --serve this file is the server the client launches; run bare, it is the client.59 server.run() if "--serve" in sys.argv else asyncio.run(main())
python list-what-the-server-offers.pyserver: shop-support 0.2.0
protocol revision: 2026-07-28
supported versions: 2026-07-28
capabilities: prompts, resources, tools
tools: get_order_status
resources: shop://policies/refund
prompts: review_refund
O código do cliente nunca nomeia nenhum dos três. Ele os aprendeu do servidor, junto com o nome do próprio servidor, shop-support 0.2.0, a revisão que ele suporta, 2026-07-28, e as capacidades que declara, prompts, resources, tools, impressos ao lado do exemplo. Essa é a primeira coisa que o MCP acrescenta à API da loja: um cliente que não sabe nada sobre a loja pode descobrir o que ela oferece, com uma descrição de cada item e, para ferramentas e prompts, os argumentos que recebem, e um host pode apresentar essas informações a um modelo. O servidor também define uma dica de cache na sua lista de ferramentas, que Armazene em cache resultados de listagem explica.
Regra prática: Dê a cada servidor seu próprio cliente no host, e mantenha a conversa e tudo que atravessa servidores no código do host, nunca em um servidor. Comece cada cliente lendo o que o servidor oferece em vez de presumir, para que um servidor que mude suas ferramentas não quebre o host. Ao escrever um servidor, presuma que ele vê apenas as requests enviadas a ele, porque é tudo que a especificação permite que ele veja.
Esta parte ainda não foi traduzida, por isso está em inglês.
Put each capability in the right primitive
The shop-support server from the previous section offers one tool, one resource and one prompt. A server's three primitives are its tools, resources and prompts, and they differ less in what they return than in who decides when they're used. The specification's server overview puts it in a table: prompts are user-controlled, resources are application-controlled, and tools are model-controlled (server features). So the question to ask of each capability is not whether it reads or writes, but who should decide when it runs: the model, the host's own code, or the person at the desk.
The tools page mandates no particular interface for a tool. The resources and prompts pages do the same for their primitives. A host can show them however it likes, but one that respects the control model gives each to the party the table names. The next script uses each of shop-support's three once, the way a host would.
1"""Use each of shop-support's three primitives once, as a host would: the tool for the model, the resource for the2host's code, the prompt for the person at the desk. The prose quotes the order's status, the policy's first line and3the prompt's one required argument."""4import asyncio5import json6import sys78from mcp import Client, StdioServerParameters910from lib import loopback, shop_api111213async def main() -> None:14 with loopback.serve(shop_api.create_app()) as base_url:15 # the server from list-what-the-server-offers, run as its own process with --serve; its env points at the shop's API16 params = StdioServerParameters(command=sys.executable, args=["list-what-the-server-offers.py", "--serve"],17 env=shop_api.server_env(base_url))18 async with Client(params) as client:19 # A tool: the host lists it for the model, and calls it when the model asks.20 result = await client.call_tool("get_order_status", {"order_id": "O-2476"})21 assert result.is_error is False # the lookup must succeed for the prose's claim22 # a tool's result is a list of content blocks; the order arrives as JSON text in the first one23 print("tool says order status:", json.loads(result.content[0].text)["status"])2425 # A resource: the host reads it when its own code decides the model needs it.26 policy = (await client.read_resource("shop://policies/refund")).contents[0] # this server returns one item27 print("resource type:", policy.mime_type)28 print("resource first line:", policy.text.splitlines()[0])2930 # A prompt: the host shows it to the user, who picks it and fills in its arguments.31 listed = (await client.list_prompts()).prompts[0] # the first prompt, the only one shop-support offers32 print("prompt arguments:", "; ".join(f"{a.name}, {'required' if a.required else 'optional'}"33 for a in listed.arguments))34 prompt = await client.get_prompt("review_refund", {"order_id": "O-2476"})35 print("prompt messages:", len(prompt.messages))36 print("prompt role:", prompt.messages[0].role)37 print("prompt starts:", prompt.messages[0].content.text[:44] + "…") # 44 characters: enough to name the order383940asyncio.run(main())
python three-primitives-side-by-side.pytool says order status: shipped
resource type: text/markdown
resource first line: # Refund policy
prompt arguments: order_id, required
prompt messages: 1
prompt role: user
prompt starts: Review the refund request for order O-2476. …
Ferramentas são ações que o modelo escolhe
Uma ferramenta é uma ação nomeada, com uma descrição e um esquema de entrada, e o modelo decide se a chama e com quais valores (ferramentas). O host lista as ferramentas para o modelo e executa as chamadas que ele pede. A consulta do pedido O-2476 foi concluída sem erro, e o status do pedido retornou como shipped.
Uma consulta pertence aqui porque o chamado decide se ela é necessária. Um cliente cita o número do pedido e pergunta onde está a encomenda; outro pergunta se uma frigideira vem em 28 cm. Só algo que lê o chamado pode escolher, e neste host quem faz isso é o modelo. Deixe um modelo escolher a ferramenta mostrou o modelo fazendo essa escolha em uma gravação.
Regra prática: Transforme uma capacidade em ferramenta quando o modelo deve decidir, a partir da conversa, se a utiliza. Isso inclui consultas que dependem do que o cliente escreveu, e toda ação que altere algo, como um reembolso, para a qual o host então pede consentimento antes da chamada.
Recursos são dados que a aplicação escolhe
Um recurso é um dado que um servidor expõe sob um URI, e cabe à aplicação decidir quando lê-lo e o que fazer com ele (recursos). O host pode anexar um recurso ao contexto do modelo, mostrá-lo ao usuário ou indexá-lo. shop-support serve a política de reembolso da loja, um dos documentos curtos de política escritos para o livro, sob shop://policies/refund. A leitura devolveu texto do tipo text/markdown, cuja primeira linha é # Refund policy.
A política de reembolso é um recurso porque a loja sabe de antemão quando ela é importante: em todo chamado sobre dinheiro. O código do host pode anexá-la ao contexto do modelo nesses chamados sem precisar pedir ao modelo. Como ferramenta, ela dependeria de o modelo lembrar de buscá-la, e custaria um turno a cada vez. Um recurso não é o mesmo que uma ferramenta somente leitura: ambos devolvem dados, mas quem lê um recurso é o código do host, e o resultado pode ser armazenado em cache segundo as regras em Armazenar em cache os resultados de listagem. Expor as políticas como recursos atende do mesmo modo às demais políticas da loja.
Regra prática: Torne um dado um recurso quando o próprio código do host consegue saber quando ele é necessário, como uma política que se aplica a um tipo conhecido de chamado, ou um registro que o usuário abriu. Mantenha-o como ferramenta quando só o modelo, lendo a conversa, consegue saber se ele é necessário.
Prompts são modelos que o usuário escolhe
Um prompt é um modelo de mensagens, com argumentos, que o servidor define e o usuário escolhe (prompts). A especificação é precisa quanto à palavra: "controlado pelo usuário" refere-se a "quem decide quando o prompt é usado, não a quem escreve o seu conteúdo". O servidor escreve o conteúdo, e um host normalmente oferece prompts em um menu ou como comandos. review_refund recebe um argumento, order_id, required. Preenchido para o pedido O-2476, ele devolveu 1 mensagem do papel user, começando por "Review the refund request for order O-2476. …".
review_refund é um prompt porque uma pessoa da equipe de suporte decide iniciar uma revisão de reembolso, normalmente depois de ler o chamado, e a loja quer que toda revisão siga os mesmos passos. O texto do prompt nomeia a ferramenta e o recurso de que a revisão precisa, para que o modelo parta da política e do pedido, e não de uma suposição. Um prompt não é um prompt de sistema que o usuário escreve: a loja o escreve uma vez, no servidor, e todo host que se conecta recebe o mesmo texto. Empacote um fluxo de trabalho como prompt transforma review_refund na revisão completa, com o valor do reembolso como um segundo argumento.
Regra prática: Transforme um fluxo de trabalho em prompt quando uma pessoa deve iniciá-lo e toda execução deve seguir os mesmos passos, e mantenha o texto do prompt no servidor, de modo que uma mudança chegue a todos os hosts de uma só vez. Se nenhuma pessoa escolhe quando ele é executado, não é um prompt: torne os passos uma ferramenta ou coloque-os nas instruções próprias do host.
Envie a versão e as capacidades em cada requisição
O cliente de Coloque cada capacidade na primitiva certa fez três chamadas, e o servidor respondeu a cada uma sem lembrar das outras, por design. Na revisão fixada não há handshake: toda requisição carrega, no campo _meta, a versão do protocolo e as capacidades do cliente, e esses campos "DEVEM ser incluídos em toda requisição" (protocolo base). Cada requisição também deve carregar o nome e a versão do cliente, e cada resultado, o nome e a versão do servidor.
Três regras da mesma página definem como o servidor da loja usa esses campos:
- Uma requisição sem um campo obrigatório é rejeitada com o erro JSON-RPC
-32602(invalid params) e, sobre HTTP, com status 400. - Um servidor não deve depender de uma capacidade que o cliente não declarou naquela requisição. Se precisar dela, responde com o erro
-32021, cujo data lista as capacidades ausentes. clientInfoeserverInfosão autodeclarados. As implementações "NÃO DEVEM depender deles para decisões de segurança", então o servidor da loja nunca trata o nome do cliente como identidade.
_meta também carrega chaves suas, sob um prefixo de nome de domínio invertido que termina em /. Um prefixo cujo segundo rótulo é modelcontextprotocol ou mcp é reservado ao protocolo, assim como traceparent, tracestate e baggage, que pertencem ao OpenTelemetry (protocolo base). O domínio da loja é fernhill.example, então suas chaves começam com example.fernhill/.
Para ver o envelope, o cliente chama get_order_status por meio de lib.wire, que registra em log cada linha trocada entre o cliente e o servidor. Ele passa uma chave própria da loja, um ID de requisição que a equipe de suporte pode citar. Em seguida envia uma requisição tools/list sem as capacidades do cliente, por meio de um segundo pequeno módulo, lib.raw_stdio, que inicia um servidor stdio e escreve linhas JSON-RPC à mão. O código precisa disso porque mcp.Client nunca envia uma requisição malformada.
1"""Show the _meta that every request and result carries, add one key of the shop's own, and send a request without2the client's capabilities. The prose's claims about the envelope come from the printed keys and the bare request's error code."""3import asyncio4import json5import sys6from pathlib import Path78from mcp import Client, StdioServerParameters9from mcp.types import Implementation1011from lib import byte_meter, loopback, raw_stdio, shop_api, wire1213COMMAND = [sys.executable, "list-what-the-server-offers.py", "--serve"]141516async def main() -> None:17 Path("meta.jsonl").unlink(missing_ok=True) # the relay appends to its log18 with loopback.serve(shop_api.create_app()) as base_url:19 server = StdioServerParameters(command=COMMAND[0], args=COMMAND[1:], env=shop_api.server_env(base_url))20 # the relay logs every line the client and server exchange, so the byte counts are of lines as sent21 async with Client(wire.relay(server, log="meta.jsonl"),22 # the name and version the SDK sends as clientInfo in _meta; the server must not rely on them23 client_info=Implementation(name="shop-host", version="0.1.0")) as client:24 # a key under the shop's own prefix, which the protocol leaves to the shop to define25 await client.call_tool("get_order_status", {"order_id": "O-2476"},26 meta={"example.fernhill/requestId": "req-0001"})27 trace = [message for _, message in wire.read_trace("meta.jsonl")]28 call = next(m for m in trace if m.get("method") == "tools/call") # the first tools/call request in the log29 result = next(m for m in trace if m.get("id") == call["id"] and "result" in m) # its response, with the same id30 for key, value in call["params"]["_meta"].items():31 print(f"request {key}:", json.dumps(value))32 for key, value in result["result"]["_meta"].items():33 print(f"result {key}:", json.dumps(value))34 lines = [json.loads(entry)["line"] for entry in Path("meta.jsonl").read_text(encoding="utf-8").splitlines()] # as sent35 print("request _meta bytes:", byte_meter.meta_bytes(lines, call["params"]["_meta"]))36 print("result _meta bytes:", byte_meter.meta_bytes(lines, result["result"]["_meta"]))3738 with raw_stdio.launch(COMMAND, env={}) as raw: # the same request, without clientCapabilities39 # capabilities=None leaves clientCapabilities out of _meta: the request the server must reject40 reply = raw.request("tools/list", meta=raw_stdio.envelope("2026-07-28", capabilities=None))41 print("without capabilities, error code:", reply["error"]["code"])42 print("without capabilities, message:", reply["error"]["message"])434445asyncio.run(main())
python request-meta-on-the-wire.pyrequest example.fernhill/requestId: "req-0001"
request io.modelcontextprotocol/protocolVersion: "2026-07-28"
request io.modelcontextprotocol/clientInfo: {"name": "shop-host", "version": "0.1.0"}
request io.modelcontextprotocol/clientCapabilities: {}
result io.modelcontextprotocol/serverInfo: {"name": "shop-support", "version": "0.2.0"}
request _meta bytes: 228
result _meta bytes: 88
without capabilities, error code: -32602
without capabilities, message: params._meta is missing the required envelope key(s): io.modelcontextprotocol/clientCapabilities
A chave da loja viaja ao lado das chaves do protocolo. A requisição tools/call tinha quatro chaves em _meta. A chave example.fernhill/requestId da loja, definida como "req-0001", veio primeiro, e o SDK acrescentou as três do protocolo depois: a versão, "2026-07-28", depois o nome, a versão e as capacidades do cliente, que a saída imprime, com as capacidades vazias porque este cliente não declara nenhuma. O _meta do resultado trazia o nome e a versão do servidor, também impressos.
A requisição sem capacidades falhou com o código -32602, e a mensagem do SDK nomeia a chave ausente: "params._meta is missing the required envelope key(s): io.modelcontextprotocol/clientCapabilities". Um cliente escrito à mão, ou um gateway que reescreve corpos e descarta _meta, falha assim na primeira requisição.
O custo para a loja são bytes em cada mensagem. Medido nas linhas como enviadas, o _meta da requisição, com a chave da loja, ocupou 228 bytes, e o do resultado, 88. Eles fazem parte do custo extra por chamada que Mantenha uma API HTTP onde o MCP não acrescenta nada mede. O que isso compra é um servidor que não precisa de memória de requisições anteriores: qualquer cópia de shop-support pode responder a qualquer requisição, o que permite que Execute réplicas sem sessões fixas coloque duas réplicas atrás de um único endereço.
Regra prática: Leia a versão e as capacidades do cliente de cada requisição, nunca de uma anterior, e responda -32021 quando uma chamada precisar de uma capacidade que a requisição não declarou. Coloque os metadados de requisição próprios da loja sob um prefixo de nome de domínio invertido seu, nunca sob io.modelcontextprotocol/ ou mcp. Registre em log clientInfo e serverInfo para depuração, e não decida nada com base neles.
Esta parte ainda não foi traduzida, por isso está em inglês.
Handle a version the server doesn't support
Every request in Carry the version and capabilities on every request named its protocol version, so a server can meet, on any request, a version it doesn't implement. No negotiation step settles it in advance. A server that doesn't implement the requested version "MUST respond with an UnsupportedProtocolVersionError listing the versions it does support", error code -32022, with the supported versions and the requested one in its data. The client SHOULD pick a version from that list that both sides support, and retry, or else show the user an error (versioning). Over Streamable HTTP the version also travels in the MCP-Protocol-Version header, which must match the body, and an unsupported version gets status 400 (Streamable HTTP).
The shop meets this when a host built for a later revision connects to shop-support. Showing the error means sending a version the server doesn't know, and the obvious way fails first: mcp.Client accepts as its mode only "auto", "legacy" or one of the SDK's per-request revisions, such as 2026-07-28, and raises before it sends anything (mcp/client/client.py). So the script tries that first, then uses lib.raw_stdio from the previous section to write the request by hand. It asks for 2099-01-01, a made-up revision that stands for any the server lacks, then retries with a version from the server's list.
1"""Ask shop-support for a revision it doesn't implement, read its -32022 error, and retry with the newest revision both2sides list. The prose reads the error code, the versions in its data and the retry's tool list from the printed lines."""3import sys45from mcp import Client, StdioServerParameters6from mcp_types.version import MODERN_PROTOCOL_VERSIONS78from lib import raw_stdio910COMMAND = [sys.executable, "list-what-the-server-offers.py", "--serve"]11UNKNOWN = "2099-01-01" # stands for any revision this server doesn't implement1213try:14 # the SDK's client checks the mode when it is built, so this raises before anything is sent15 Client(StdioServerParameters(command=COMMAND[0], args=COMMAND[1:]), mode=UNKNOWN)16except ValueError as refused:17 print("client refuses:", type(refused).__name__)1819with raw_stdio.launch(COMMAND, env={}) as server:20 # capabilities={} declares no client capabilities: the request is well formed, and only its version is unknown21 error = server.request("tools/list", meta=raw_stdio.envelope(UNKNOWN, capabilities={}))["error"]22 print("error code:", error["code"])23 print("error message:", error["message"])24 print("server supports:", ", ".join(error["data"]["supported"])) # the server lists its versions in the error's data25 print("client asked for:", error["data"]["requested"])2627 # the versions both sides know, in the order the SDK lists them28 mutual = [version for version in MODERN_PROTOCOL_VERSIONS if version in error["data"]["supported"]]29 if not mutual:30 sys.exit("no version in common: show the user an error instead of retrying")31 print("retry with:", mutual[-1]) # the last of that list is the newest version both sides know32 # the same process: at this revision each request names its own version, so the retry needs no new connection33 retry = server.request("tools/list", meta=raw_stdio.envelope(mutual[-1], capabilities={}))34 print("retry tools:", ", ".join(tool["name"] for tool in retry["result"]["tools"]))
python unsupported-version-error.pyclient refuses: ValueError
error code: -32022
error message: Unsupported protocol version
server supports: 2026-07-28
client asked for: 2099-01-01
retry with: 2026-07-28
retry tools: get_order_status
The SDK's client never reached the server: it refused the unknown mode before sending anything, with the error the output beside the example shows. The server's answer is what makes the retry possible. Given the raw request, it refused with the code and message the output prints, and its data listed the versions it supports, 2026-07-28, beside the one the client asked for. From that list the script picked 2026-07-28, the newest version both sides know, and the retry listed get_order_status. The retry went to the same process, because a connection carries no agreed version at the pinned revision, so the next request may name another one.
Two details of the SDK at 2.3.0 matter when you read this error from someone else's server. First, an SDK stdio server decides from the client's first request which era of the protocol to speak. A request whose _meta has a protocol version opens a connection at the pinned revision, even when the version is unknown, which is why this request got -32022 instead of a demand for the 2025 initialize handshake (mcp/server/runner.py). Second, the server's supported list holds only the versions that use per-request _meta, although the same server still accepts 2025 clients through initialize (mcp/shared/inbound.py). The specification's own example of the error lists a 2025 revision as well; the SDK's list doesn't. The SDK's client, in its default auto mode, reads a -32022 whose list shares nothing with its own as a real incompatibility, and any other error on its first request as a 2025 server that needs the old handshake (mcp/client/_probe.py). Serve old and new clients through the window covers that second path.
Working rule: When a server answers -32022, pick the newest version in both your list and its supported list, retry once, and show the user an error naming both lists if they share none. Don't retry in a loop, and don't guess a version the server didn't list. On your own server, keep the supported list exact, because clients choose from it.
Armazenar em cache os resultados de listagem
A resposta de server/discover e a lista de ferramentas em Separe o host, o cliente e o servidor mudam apenas quando a loja é implantada, mas um cliente sem estado poderia perguntar antes de cada turno do modelo. Cada resultado de server/discover, tools/list, prompts/list, resources/list, resources/templates/list e resources/read deve trazer duas dicas de armazenamento em cache na revisão fixada (armazenamento em cache):
ttlMs, quantos milissegundos o resultado permanece fresco, como omax-agedo HTTP. Zero significa que ele fica obsoleto imediatamente.cacheScope, que pode ser"public", caso em que um cache pode compartilhá-lo entre chamadores, ou"private", caso em que ele NÃO DEVE ser compartilhado entre contextos de autorização.
A mesma página limita o que as dicas significam. Um TTL é uma dica de frescor, não um intervalo de consulta: o cliente verifica o frescor quando precisa dos dados, e qualquer consulta periódica deve usar jitter e backoff. Uma notificação list_changed invalida um resultado em cache que ainda está fresco. E cacheScope não é controle de acesso: um servidor "NÃO DEVE depender somente de cacheScope para impedir acesso não autorizado".
Armazenar em cache uma lista de ferramentas só funciona se a lista for estável. A especificação diz que a lista de ferramentas devolvida por tools/list NÃO DEVE variar de uma conexão para outra, embora possa variar com a autorização da requisição, e que servidores devem devolver as ferramentas em ordem determinística, o que ajuda os caches de prompt a acertar com mais frequência (ferramentas). O MCPServer do SDK lista as ferramentas na ordem em que você as registra, o que atende a essa regra (mcp/server/mcpserver/tools/tool_manager.py).
No SDK, as dicas padrão de um servidor são ttl_ms=0 e "private", então nada é reaproveitado a menos que o servidor opte por isso. shop-support opta por isso para a sua lista de ferramentas com cache_hints={"tools/list": CacheHint(ttl_ms=300_000, scope="public")}: cinco minutos e compartilhável (mcp/server/caching.py). Do outro lado, mcp.Client armazena em cache por padrão, na memória, segundo as dicas do servidor, e cada chamada de listagem recebe um cache_mode de "use", "refresh" ou "bypass". Uma chamada que passa o próprio meta sempre chega ao servidor, e o cliente limita qualquer TTL a 24 horas (mcp/client/caching.py). Para contar o que o cache economiza, liste as ferramentas duas vezes no servidor do capítulo 1, que não define dica, e depois duas vezes em shop-support, e conte na rede, com lib.wire, quantos requests tools/list chegaram a cada servidor.
1"""Call list_tools() twice on each of two servers, one that sets no cache hint and one with a five-minute public hint,2and count the tools/list requests that reach each; the prose reads the three counts."""3import asyncio4import sys5from pathlib import Path67from mcp import Client, StdioServerParameters89from lib import wire101112async def list_twice(script: str, second_call: str = "use") -> tuple[str, str, int]:13 log = Path(script).with_suffix(".jsonl") # the relay's log, beside the server file14 log.unlink(missing_ok=True) # the relay appends to its log15 server = StdioServerParameters(command=sys.executable, args=[script, "--serve"], env={})16 async with Client(wire.relay(server, log=str(log))) as client:17 first = await client.list_tools() # cache_mode="use" is the default18 await client.list_tools(cache_mode=second_call)19 name = client.server_info.name20 # responses carry no method, so this counts only the requests that reached the server21 sent = sum(1 for _, message in wire.read_trace(str(log)) if message.get("method") == "tools/list")22 return name, f"ttlMs {first.ttl_ms}, cacheScope {first.cache_scope}", sent232425async def main() -> None:26 name, hint, sent = await list_twice("order-status-server.py") # chapter 1's server, which sets no hint27 print(f"{name} hint:", hint)28 print(f"{name} tools/list sent for two calls:", sent)29 name, hint, sent = await list_twice("list-what-the-server-offers.py") # this chapter's server, with its tool-list hint30 print(f"{name} hint:", hint)31 print(f"{name} tools/list sent for two calls:", sent)32 name, hint, sent = await list_twice("list-what-the-server-offers.py", second_call="bypass") # bypass skips the cache33 print(f"{name} tools/list sent when the second call bypasses:", sent)343536asyncio.run(main())
python cache-the-tool-list.pyshop-orders hint: ttlMs 0, cacheScope private
shop-orders tools/list sent for two calls: 2
shop-support hint: ttlMs 300000, cacheScope public
shop-support tools/list sent for two calls: 1
shop-support tools/list sent when the second call bypasses: 2
A dica decide quantos requests chegam. O shop-orders do capítulo 1 devolveu ttlMs 0, cacheScope private, então as duas chamadas foram ao servidor, 2 requisições no total. A lista de shop-support voltou com ttlMs 300000, cacheScope public, então o cache do cliente respondeu à segunda chamada, e apenas 1 requisição chegou ao servidor. Com cache_mode="bypass" na segunda chamada, as duas chamadas chegaram ao servidor de novo, e a saída ao lado do exemplo conta cada uma. Um host que renderiza a lista de ferramentas em cada turno do modelo economiza uma requisição por turno. E como a lista mantém a ordem, o início do prompt do modelo tem os mesmos bytes, que é o que o cache de prompt de um provedor precisa.
A lista de ferramentas da loja pode ser pública porque todos os chamadores veem as mesmas ferramentas. Os dados por cliente da loja não podem. Quando Endereçar registros com templates de recursos serve um recurso por pedido, essas leituras permanecem "private", então um cache compartilhado nunca entrega o pedido de um cliente à sessão de outro cliente. Se a lista de ferramentas um dia depender do token do chamador, como pode acontecer quando Limite as ferramentas pelo que o token permite for aplicado, ela também passa a ser privada.
Regra prática: Defina um TTL e um escopo "public" para listas iguais para todos os chamadores, como a lista de ferramentas da loja, e escolha um TTL não maior do que você aceitaria para uma lista desatualizada após uma implantação: minutos, não horas. Mantenha "private", o padrão do SDK, em qualquer coisa que dependa de quem está pedindo, e nunca deixe cacheScope substituir uma verificação de autorização. No cliente, mantenha o cache padrão, que descarta uma entrada quando uma notificação de mudança chega por um stream iniciado com client.listen(tools_list_changed=True) (mcp/client/client.py), o tipo de stream que Avise os clientes quando um recurso mudar abre. Sem esse stream nenhuma notificação chega ao cliente, então abra um, e use cache_mode="refresh" quando tiver outro motivo para desconfiar de uma entrada, em vez de consultar com base no TTL.
Esta parte ainda não foi traduzida, por isso está em inglês.
Keep an HTTP API where MCP adds nothing
Each section so far showed something MCP adds to the shop's API. Separate the host, the client and the server added run-time discovery, and Put each capability in the right primitive gave each capability a control model. Carry the version and capabilities on every request made every request versioned and self-describing. The host's consent step, in Ask for consent before side effects, is another. Each of those helps when a model or a user's host chooses among capabilities at run time. None of them helps a program whose developer already knows which endpoint it will call.
The specification doesn't say when not to use MCP, so this is the book's judgement, not a protocol rule. We recommend a plain HTTP API for three kinds of work:
- Service-to-service calls with no model choosing, such as the warehouse's nightly read of stock levels. Its code calls fixed endpoints, so nobody reads the discovery answers or the descriptions.
- Fixed workflows, where the same steps run in the same order every time. Write them as code over the API, and if a model needs to start one, expose the whole workflow as one tool.
- High-volume batch work, where every byte and round trip is multiplied.
We recommend MCP where a model or a user's host chooses among capabilities at run time, as the support team's host does. The two don't compete. Meet the shop and its API kept the shop's API as the system of record, and shop-support is a thin adapter over it, so the warehouse keeps its API calls while the support team's host uses MCP.
This run prices the adapter, so the trade-off rests on numbers. The script fetches order O-2476 twice: once from the shop's API, with GET /orders/O-2476, and once through shop-support's get_order_status tool over Streamable HTTP, the transport Move the server from stdio to HTTP teaches. lib.byte_meter, a small module for this measurement, puts a TCP relay in front of each server and counts every byte both ways, headers included, and counts the HTTP requests each server handles. Everything runs in one process on 127.0.0.1, over HTTP/1.1 without TLS. On the MCP side, the count covers a host's setup on opening a client, including the tool listing, but not the tool call. That setup is measured twice: in the default auto mode, which first probes the server with server/discover, and with the version pinned. The tool call itself is made with the version pinned. No times are measured, because times on one machine's loopback say little about a network.
1"""Fetch order O-2476 from the shop's API, then through shop-support's tool over Streamable HTTP, and count the cost.2The prose's comparison comes from the byte totals and the request counts the script prints."""3import asyncio4import os5import runpy67import httpx28from mcp import Client910from lib import byte_meter, loopback, shop_api111213async def session(url, traffic, requests, mode: str, calls: int) -> tuple[list[str], int]:14 """Open a client, list the tools as a host does, make `calls` tool calls, close it: the requests and bytes."""15 traffic.reset()16 requests.reset()17 # auto mode first sends server/discover to probe the server; a pinned revision skips that probe18 async with Client(f"{url}/mcp", mode=mode) as client:19 await client.list_tools()20 for _ in range(calls):21 await client.call_tool("get_order_status", {"order_id": "O-2476"})22 return list(requests.names), traffic.sent + traffic.received # bytes both ways, from the relay232425async def main() -> None:26 print("setup: one process, 127.0.0.1, HTTP/1.1, no TLS, bytes counted at a TCP relay, headers included")27 api_app, api_requests = byte_meter.count_requests(shop_api.create_app())28 with loopback.serve(api_app) as api_url, byte_meter.relay(api_url) as (url, traffic):29 # the one API call, sent through the relay so that its bytes are counted the way the tool's are30 httpx2.get(f"{url}/orders/O-2476", headers={"X-API-Key": shop_api.DEMO_API_KEY}).raise_for_status()31 api_bytes = traffic.sent + traffic.received32 print("api call round trips:", api_requests.count)33 print("api call bytes:", api_bytes)3435 os.environ.update(shop_api.server_env(api_url)) # the tool calls the API directly, not through a relay36 shop_support = runpy.run_path("list-what-the-server-offers.py")["server"] # defined there, not run37 mcp_app, mcp_requests = byte_meter.count_requests(shop_support.streamable_http_app())38 with loopback.serve(mcp_app) as mcp_url, byte_meter.relay(mcp_url) as (url, traffic):39 for mode, label in (("auto", "auto"), ("2026-07-28", "pinned")):40 names, setup_bytes = await session(url, traffic, mcp_requests, mode, calls=0) # setup only, no tool call41 print(f"mcp {label} setup request count:", len(names))42 print(f"mcp {label} setup requests:", ", ".join(names))43 print(f"mcp {label} setup bytes:", setup_bytes)44 names, with_call = await session(url, traffic, mcp_requests, "2026-07-28", calls=1)45 call_bytes = with_call - setup_bytes # a pinned session with one call, less the pinned setup46 print("mcp tool call round trips:", names.count("tools/call"))47 print("mcp tool call bytes:", call_bytes)48 print("tool call bytes per api call byte:", round(call_bytes / api_bytes, 1)) # one decimal place, as the prose quotes495051asyncio.run(main())
python api-call-versus-tool-call.pysetup: one process, 127.0.0.1, HTTP/1.1, no TLS, bytes counted at a TCP relay, headers included
api call round trips: 1
api call bytes: 591
mcp auto setup request count: 2
mcp auto setup requests: server/discover, tools/list
mcp auto setup bytes: 2157
mcp pinned setup request count: 1
mcp pinned setup requests: tools/list
mcp pinned setup bytes: 1147
mcp tool call round trips: 1
mcp tool call bytes: 1357
tool call bytes per api call byte: 2.3
On the wire the tool call costs more bytes, not more round trips. The API call takes 1 round trip and the tool call takes 1, but it sends 2.3 times the bytes, which the output beside the example counts. The difference is the JSON-RPC envelope, the _meta on the request and on the result, the routing headers that Streamable HTTP adds, and the order itself, which the SDK returns as indented JSON inside a text block, with its quotes escaped, as Read the messages on the wire showed.
Setup costs more on top of that. In auto mode, opening the client sent 2 requests before its first call; with the version pinned it skipped the server/discover probe and sent 1. The output beside the example lists the requests and their bytes. Behind the server, each tool call also made its own request to the shop's API, which the counts leave out because the caller never sees it.
Some of those bytes buy something without a model. The headers Mcp-Method, on every request, and Mcp-Name, on tools/call, resources/read and prompts/get, let a gateway route by method and by tool without parsing bodies (Streamable HTTP). For the support team's host, which makes a few calls per ticket, 1357 bytes a call is small beside the model's own tokens. For the warehouse's nightly read of 64 products, every call pays for an envelope its code never reads, and the adapter adds a process to a job that ran without one.
Working rule: Keep a plain HTTP API for callers whose code knows which endpoint to call, such as other services, fixed workflows and batch jobs, and put an MCP server in front of the same API for hosts where a model or a user chooses at run time. Measure the overhead on your own transport before you route high-volume traffic through MCP, and pin the protocol version in clients you control, so they skip the discovery probe. Keep auto mode for clients that may meet servers you don't control, which may speak only the 2025 protocol.
O que dá errado em produção
As partes que este capítulo acrescentou falham de algumas maneiras reconhecíveis, e cada uma deixa um rastro que você pode procurar.
Uma capacidade cai na primitiva errada. Uma política servida como ferramenta é ignorada quando o modelo não pensa em buscá-la, e um reembolso servido como recurso não deixa ao host nenhum ponto em que possa pedir consentimento. O sinal é um comportamento que varia de chamado para chamado sem motivo aparente no próprio chamado: respostas sobre dinheiro dadas sem a política, ou efeitos colaterais sem nenhuma etapa de consentimento nos logs. Pergunte, para cada capacidade, quem deve decidir quando ela é executada, como faz Coloque cada capacidade na primitiva certa.
Um gateway descarta ou reescreve _meta. Proxies e gateways de API projetados para APIs JSON simples às vezes reescrevem os corpos das requisições. Uma requisição que perde sua versão ou suas capacidades falha com -32602, como mostrou Leve a versão e as capacidades em toda requisição. No Streamable HTTP, um corpo que já não corresponde aos seus cabeçalhos falha com -32020, porque os cabeçalhos MCP-Protocol-Version, Mcp-Method e Mcp-Name devem concordar com o corpo (Streamable HTTP). Deixe o tráfego MCP passar sem alterações e faça o roteamento pelos cabeçalhos, em vez de editar os corpos.
clientInfo é usado como identidade. O nome do cliente em _meta é o que o cliente escolheu enviar, e a especificação diz que não se deve confiar nele para segurança (protocolo base). Um servidor que concede mais a um cliente chamado shop-host concede isso a qualquer um que envie esse nome. A autorização vem de tokens, pelos quais começa Encontre o servidor de autorização a partir do recurso.
Uma entrada de cache pública vaza entre clientes. Um resultado marcado como "public" pode ser compartilhado entre contextos de autorização, mesmo quando veio de um endpoint autenticado (cache). Um servidor que marca como público dados de cada cliente permite que um cache compartilhado entregue o pedido de um cliente a outro. Mantenha o padrão "private" do SDK para tudo que dependa de quem chama, e trate cada dica "public" em uma revisão de código como uma afirmação a ser verificada.
Um TTL longo esconde um deploy. Quando a lista de ferramentas fica válida por horas, um cliente continua oferecendo uma ferramenta que o servidor já removeu, e as chamadas a ela falham. O sinal são erros de ferramenta desconhecida que param quando os clientes são reiniciados. Mantenha os TTLs da lista de ferramentas em minutos, e deixe que os clientes atualizem ao receber uma notificação de mudança, que só chega a um cliente por um stream subscriptions/listen que ele abriu, como configura Avise os clientes quando um recurso mudar.
Um cliente chama uma ferramenta que nunca listou. Na versão 2.3.0, mcp.Client verifica o resultado de uma ferramenta contra o esquema de saída dela e, se ainda não tiver listado as ferramentas, envia primeiro tools/list (mcp/client/session.py). Um cliente que chama ferramentas sem listá-las paga uma requisição extra na primeira chamada. Liste as ferramentas quando o cliente abrir, como um host costuma fazer de qualquer forma.
Códigos de erro antigos vindos de material antigo. A revisão fixada reserva de -32020 a -32099 para a especificação, trata de -32000 a -32019 como uma faixa legada que código novo não deve usar, e pede códigos de aplicação fora da faixa que o JSON-RPC reserva (protocolo base). A revisão renumerou seus códigos de erro no caminho até a liberação (changelog), então material escrito com base em um rascunho pode mostrar outros números para os mesmos erros. Confira os códigos de erro com a especificação, não com um post de blog.
A especificação continua evoluindo. O MCP é governado pela Agentic AI Foundation, um fundo dirigido sob a Linux Foundation, que assumiu o MCP como projeto fundador em dezembro de 2025 (anúncio). As revisões têm data, e um recurso descontinuado permanece por pelo menos doze meses (ciclo de vida dos recursos). O prazo é menor apenas quando há um risco de segurança ativo, e nesse caso de pelo menos noventa dias, ou quando o registro de recursos descontinuados assim indicar. Consulte o registro ao planejar a próxima liberação de um servidor, e observe nos logs as ocorrências de -32022 vindas de clientes feitos para uma revisão posterior.
Regra prática: Verifique quatro coisas em qualquer servidor que você esteja prestes a publicar: a primitiva de cada capacidade corresponde a quem decide quando ela é executada, nada entre cliente e servidor edita corpos MCP, nada é decidido com base em clientInfo, e toda dica de cache "public" cobre dados que são iguais para todos os chamadores. Registre a versão do protocolo e o código de erro de cada requisição que falhar, porque erros de versão e de envelope são o primeiro sinal de que um cliente ou um gateway mudou.
Decisões tomadas neste capítulo
- Um cliente por servidor, no host. A conversa e tudo o que atravessa servidores ficam no código do host; um servidor vê apenas as requests enviadas a ele.
- O servidor da loja é
shop-support, com a ferramentaget_order_statusdo capítulo 1, a política de reembolso como recurso emshop://policies/refund, ereview_refundcomo prompt. - Cada capacidade vai para a primitiva cujo controlador deve decidir quando ela é executada: o modelo para ferramentas, o código do host para recursos, a pessoa no balcão para prompts.
- A versão e as capacidades são lidas de cada request, nunca de uma anterior, e uma capacidade ausente recebe
-32021. - As chaves próprias da loja em
_metausam o prefixoexample.fernhill/. Nada é decidido com base emclientInfoouserverInfo. - Em
-32022, o cliente tenta novamente uma vez com a versão mais recente que os dois lados listam, e mostra um erro caso contrário. - A lista de ferramentas é pública, com TTL de cinco minutos. Os dados por cliente permanecem privados, e a lista de ferramentas passa a ser privada se passar a depender do token.
- JSON-RPC escrito à mão, por meio de
lib.raw_stdio, serve apenas para mostrar erros que o cliente do SDK nunca causaria. - Recomendamos uma API HTTP simples para chamadas entre serviços, fluxos de trabalho fixos e trabalho em lote, e MCP quando um modelo ou o host de um usuário escolhe em tempo de execução, com base nas contagens de bytes e de viagens de ida e volta em
api-call-versus-tool-call.
Este capítulo, nesta edição
Edição 2026.11.14Exemplos aprovados em 19 de nov de 20266 de 6 exemplos exemplos deste capítulo passam
Traduzido do livro em inglês, edição 2026.11.14.