MCP end to end

Cerca de 29 minutos min de leitura, com 5 exemplos em 7 seções.

Edição 2026.11.14 Exemplos aprovados em 19 de nov de 2026 70 de 70 exemplos passam O que mudou

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

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

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

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

Conheça a loja e a sua API

Última alteração na edição 2026.11.11

Um servidor MCP raramente começa do zero. A maioria das equipes que precisam de um já mantém uma API HTTP com dados, autenticação e clientes próprios, e o trabalho do servidor é colocar parte dela à frente de um modelo. Portanto, a primeira coisa de que você precisa é da API que você vai encapsular, em execução onde os seus exemplos possam alcançá-la.

Todos os capítulos trabalham com esta loja, a Fernhill Supply, à qual chamamos de a loja. A loja é fictícia e não representa nenhum negócio real; o domínio dela, fernhill.example, é um nome reservado que nunca pode ser resolvido. A equipe de suporte responde a chamados de clientes, e a maioria dos chamados exige uma consulta aos sistemas da loja: onde está um pedido, se um produto está em estoque ou quanto daria um reembolso. O objetivo do livro é um host que leia esses chamados e chame as ferramentas da loja para respondê-los.

A loja já tem o "antes" que cada capítulo encapsula: a API da loja, uma API HTTP para pedidos, estoque e reembolsos que verifica uma chave de API no cabeçalho X-API-Key. Os registros dela são os dados da loja, gerados pelo próprio código do livro a partir de uma semente fixa, de modo que cada execução vê os mesmos clientes, pedidos e chamados. Três módulos compartilhados em examples/lib/ contêm essa configuração, para que os exemplos fiquem curtos:

  • lib.shop_data gera os dados da loja. load_shop() retorna seus clientes, produtos, níveis de estoque, pedidos, reembolsos e chamados como dataclasses do Python.
  • lib.shop_api é a API da loja, uma aplicação Starlette sobre esses dados.
  • lib.loopback sobe uma aplicação em 127.0.0.1, em uma porta livre, e a encerra quando o bloco termina.

Antes de encapsular a API, execute-a como qualquer cliente faria: uma vez com a chave, uma vez sem ela e uma vez para um pedido que não existe.

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

A semente é 4217, e a saída ao lado do exemplo conta os clientes, produtos, pedidos e chamados que essa semente produz. Os e-mails ficam em example.com, os telefones aparecem mascarados, deixando apenas dois dígitos, e o pagamento mostra apenas "card ending" com os quatro últimos dígitos de um cartão de teste publicado. O cartão de dados em examples/data/shop/README.md lista todos os campos.

Com a chave, a API responde 200: o pedido O-2476 tem o status shipped e foi enviado em 2026-06-24, por um total de €99.00. A loja precifica tudo em euros, e a sua API envia os valores como decimais simples, sem código de moeda.

Sem a chave, ela responde 401, e um pedido que não existe recebe 404. Essas três respostas são o contrato que o servidor MCP precisa respeitar. O servidor vai guardar a chave, chamar o mesmo endpoint, GET /orders/{order_id}, e transformar as respostas em algo que um modelo consiga ler; ele não vai reimplementar a lógica de pedidos.

Regra prática: Encapsule a API que você já executa e mantenha-a como sistema de registro. O servidor MCP deve ser um adaptador enxuto que chama a API com as próprias credenciais e traduz as respostas, de modo que a validação, a autorização e os logs da API continuem funcionando para todos os clientes, e não apenas para modelos. Construa diretamente sobre o banco de dados somente quando não houver API a encapsular e, nesse caso, mantenha as regras de negócio em um único lugar, compartilhado por ambos os tipos de cliente.

Esta parte ainda não foi traduzida, por isso está em inglês.

Wrap one endpoint as a tool

Última alteração na edição 2026.11.14

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

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

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

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

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

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

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

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

Chame a ferramenta a partir de um cliente

Última alteração na edição 2026.11.11

Envolva um endpoint como uma ferramenta definiu shop-orders, mas nunca a executou, porque um servidor stdio só roda quando algo o inicia. No caso da loja, esse algo é o host, e a parte do host que conversa com um servidor é um cliente. Pelo stdio, um cliente inicia o servidor como um subprocesso, escreve requisições na sua entrada padrão e lê as respostas na sua saída padrão (transporte stdio).

Na revisão fixada, não há handshake nem sessão. Cada requisição é independente e carrega a versão do protocolo e as capacidades do cliente no seu campo _meta, e a especificação diz que um servidor "NÃO DEVE depender de requisições anteriores pela mesma conexão para estabelecer contexto" (protocolo base). A mesma página também diz que uma conexão aberta, como um processo stdio, não é uma conversa nem uma sessão. As revisões até 2025-11-25 abriam cada conexão com um handshake initialize; Remova o initialize e os IDs de sessão explica como abandonar esse handshake.

O cliente de alto nível do SDK em Python é mcp.Client, e, dado um StdioServerParameters, ele inicia o comando como um subprocesso. No modo padrão mode="auto", ele primeiro envia server/discover na revisão fixada. Ele recorre ao antigo handshake initialize sempre que a sondagem expira ou falha com qualquer erro, exceto um -32022 cuja lista de versões não tem nenhuma em comum com as do cliente, caso que Trate uma versão que o servidor não suporta aborda (mcp/client/client.py, mcp/client/_probe.py). Um servidor da era 2025 responde a server/discover com um erro, então recebe o antigo handshake. Use Client, e não um initialize() chamado manualmente sobre um ClientSession de baixo nível, que sempre fala o handshake anterior a 2026 (guia de migração).

O comando é sys.executable, o Python que executa o exemplo, e não "python", para que o servidor rode no mesmo ambiente, com os mesmos pacotes fixados, qualquer que seja o primeiro item no PATH. O endereço e a chave da API da loja vão explicitamente em env=, porque o cliente stdio não repassa o ambiente do processo pai. No Linux e no macOS, ele passa apenas HOME, LOGNAME, PATH, SHELL, TERM e USER, mais o que você fornecer (mcp/client/stdio.py). O cliente também se identifica como shop-host, para que os logs do servidor e o tráfego mostrem quem fez a chamada.

O próximo exemplo faz três chamadas para mostrar falhas do ponto de vista do cliente: uma para um pedido real, uma para um ID de pedido que não existe e uma de um segundo cliente que esquece o ambiente.

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

A primeira chamada funciona. O pedido real volta como um resultado comum, não como erro, com status shipped, a mesma resposta que a API da loja deu diretamente. Nesse processo, o cliente e o servidor concordaram com a revisão 2026-07-28, e a resposta server/discover deu ao cliente o nome e a versão do servidor, shop-orders 0.1.0.

O ID errado, O-7144, volta como um resultado sinalizado, não como exceção, e seu texto é a mensagem ToolError, precedida pelo SDK. Um modelo que lê "Os IDs de pedido têm o formato O-1873" pode perguntar de novo ao cliente. A terceira chamada falha de outra forma. O servidor foi iniciado sem SHOP_API_URL, então a ferramenta levantou um KeyError, e o cliente recebeu apenas Error executing tool get_order_status. O KeyError em si foi para o erro padrão do servidor, onde um operador pode encontrá-lo e um modelo não. Essa divisão é deliberada, pois coloca a variável ausente nos logs do servidor e nunca na conversa.

Regra prática: Conecte com mcp.Client, inicie servidores stdio com sys.executable e um env= explícito, e dê um nome ao cliente. Passe cada variável que o servidor precisa e nada mais do seu ambiente, de modo que nenhum servidor veja segredos destinados a outro programa. Quando uma ferramenta falhar apenas com a mensagem genérica do SDK, leia o erro padrão do servidor antes de alterar o cliente.

Leia as mensagens no fio

Última alteração na edição 2026.11.11

O cliente da seção anterior escondia cada mensagem atrás de call_tool(). Quando um servidor se comporta mal, ou quando você precisa saber o que a revisão fixada realmente envia, leia as mensagens. Sobre stdio, cada mensagem é uma linha de JSON-RPC na entrada ou na saída padrão do servidor, sem quebras de linha embutidas. O servidor "NÃO DEVE" escrever em sua saída padrão nada que não seja uma mensagem MCP válida, e seus logs pertencem à saída de erro padrão (transporte stdio).

Um rastreamento fiel precisa de um subprocesso real. O cliente in-process do SDK, Client(server) recebendo um objeto de servidor, despacha chamadas diretamente no modo automático padrão, sem enviar nenhum JSON-RPC (mcp/client/client.py), então não consegue mostrar o fio. O impressor de rastreamento do livro, lib.wire, coloca um pequeno retransmissor entre o cliente e o servidor: o cliente inicia o retransmissor, o retransmissor inicia o servidor real, e o retransmissor copia cada linha nos dois sentidos sem alterações, enquanto a acrescenta a um log.

wire.print_trace() então imprime esse log em ordem, com mensagens numeradas, setas indicando a direção (-> do cliente para o servidor, <- de volta) e IDs de requisição renumerados para que a saída permaneça estável. Valores sob nomes que parecem segredos são impressos como [redacted]; este rastreamento não tem nenhum.

Para ver o fio, execute a chamada para o pedido O-2476 do exemplo do cliente pelo retransmissor. Três de suas mensagens são impressas por completo, e as demais em uma linha cada.

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

Nada aqui é um handshake: não há initialize. A troca tem 6 mensagens, e os métodos, em ordem, são server/discover, tools/list, tools/call. Lendo uma por uma:

  1. server/discover é a primeira requisição. Seus params contêm apenas _meta, com três entradas: io.modelcontextprotocol/protocolVersion, io.modelcontextprotocol/clientInfo com o nome shop-host, e io.modelcontextprotocol/clientCapabilities, que está vazio porque este cliente não declara nenhuma. Todo servidor deve implementar server/discover (descoberta).
  2. Seu resultado lista supportedVersions e as capabilities do servidor, e o próprio _meta do servidor carrega io.modelcontextprotocol/serverInfo. O resultado também tem resultType e duas dicas de cache, ttlMs e cacheScope, que Cache de resultados de listagem explica.
  3. tools/list carrega o mesmo _meta novamente.
  4. Seu resultado contém a definição da ferramenta que o exemplo do servidor imprimiu.
  5. tools/call nomeia a ferramenta e fornece seus arguments, e mais uma vez carrega a versão do protocolo, o nome do cliente e suas capacidades.
  6. Seu resultado contém o pedido como texto em content, com isError definido como falso e resultType definido como "complete".

Três requests, cada um dizendo quem está pedindo e em qual revisão, porque nenhuma requisição pode depender da anterior.

Todo resultado carrega resultType, e "complete" marca uma resposta comum. O outro tipo, uma requisição de entrada no meio de uma chamada, é o assunto de Retornar uma requisição de entrada em vez de um resultado. Um cliente trata como completo um resultado sem o campo, vindo de um servidor mais antigo (protocolo base). O servidor do SDK acrescenta resultType e o carimbo serverInfo por conta própria (mcp/server/runner.py).

Uma coisa está ausente do rastreamento de propósito: a chave de API da loja. Ela chegou ao servidor pelo ambiente do subprocesso, e o servidor a enviou somente para a API da loja. A especificação quer que servidores stdio obtenham credenciais do ambiente, e não sigam o fluxo OAuth que Autorize clientes com OAuth ensina para HTTP (protocolo base).

Regra prática: Quando uma chamada se comporta de forma inesperada, rastreie o fio antes de ler o código do SDK: um retransmissor que copia e registra linhas funciona com qualquer cliente e qualquer servidor. Nunca escreva na saída padrão a partir de um servidor stdio, nem mesmo um print() de depuração, porque o cliente lê cada linha ali como uma mensagem. Use logging, que o SDK envia para a saída de erro padrão, ou escreva na saída de erro padrão você mesmo.

Deixe um modelo escolher a ferramenta

Última alteração na edição 2026.11.11

No exemplo do cliente, o código escolhia a ferramenta e os seus argumentos. No caso da loja, essa escolha deve ser feita por um modelo. As ferramentas são controladas pelo modelo. O host mostra ao modelo as ferramentas disponíveis, e o modelo decide qual chamar e com quais argumentos (ferramentas). O host continua no comando de todo o resto. Ele monta o prompt, lê a resposta do modelo, faz a chamada por meio do seu cliente e decide o que fazer com o resultado.

O loop de host do livro, lib.host, é um host pequeno que o próprio livro escreve, para que cada passo fique visível. Aqui ele executa um turno: renderiza as ferramentas do servidor no prompt de sistema próprio do livro, informando o nome, a descrição e o esquema de entrada de cada ferramenta, e então envia esse prompt e um ticket a um modelo e interpreta a resposta. Uma resposta que contenha um bloco <tool_call> com o nome e os argumentos de uma ferramenta é uma escolha; qualquer outra resposta é uma resposta em palavras. O loop mantém o prompt e a interpretação no código do livro, e não em uma biblioteca de modelos, de modo que o mesmo código conduza o modelo real quando a gravação é feita e a reprodução nos exemplos.

Os exemplos aqui nunca chamam um modelo, porque a saída dele não é determinística e os exemplos precisam rodar offline. Uma gravação guarda as respostas brutas do modelo em examples/data/recorded/, feita uma vez por um script em recordings/, e os exemplos a reproduzem com ReplayModel. A reprodução falha de forma explícita se o prompt, o ticket ou as ferramentas tiverem mudado. Todas as gravações deste livro usam o Qwen3-4B-Instruct-2507, um modelo aberto sob a licença Apache-2.0, quantizado em 4 bits (Q4_K_M, em uma conversão GGUF de terceiros) e executado na CPU com llama.cpp, para que qualquer pessoa possa refazer as gravações. O script recordings/pick_a_tool.py fez a gravação deste capítulo, pick-a-tool, contra o mesmo servidor e o mesmo prompt, e o seu manifesto registra a revisão e o hash do arquivo do modelo.

A parte incerta é o modelo, por isso o exemplo lhe dá três tickets: um cita um ID de pedido do jeito que a loja o escreve, outro traz apenas o número do pedido, e o terceiro pergunta sobre estoque, o que nenhuma ferramenta deste servidor consegue responder.

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

O modelo escolheu a consulta para os dois tickets que precisam de um pedido e recusou o que precisa de estoque. No ticket T-0003 ele escolheu get_order_status para o pedido que o ticket menciona, e a chamada do host encontrou esse pedido: shipped. O ticket T-0010 trouxe apenas um número solto, mas o modelo ainda enviou O-2496, a forma que tanto a descrição quanto o prompt mostram. Para a pergunta sobre estoque no T-0015, o modelo não chamou ferramenta alguma, none, e disse em palavras que não podia verificar o estoque. Esse é o comportamento correto para um servidor que oferece apenas consultas de pedidos, e o capítulo 3 acrescenta a ferramenta check_stock de que o ticket precisa.

Três escolhas gravadas mostram o loop funcionando. Elas não medem com que frequência um modelo escolhe bem. Escreva descrições que o modelo entenda compara descrições em mais tickets, e Meça com que frequência a ferramenta certa é escolhida mede a precisão sobre toda a fila de tickets.

Este host chama get_order_status sem pedir autorização a ninguém, o que se afasta da especificação. A especificação atribui o consentimento ao host: os hosts "devem obter consentimento explícito do usuário antes de invocar qualquer ferramenta", e o próprio MCP não consegue impor isso (visão geral da especificação). A página sobre ferramentas acrescenta que DEVE haver sempre um humano no circuito, capaz de negar uma chamada de ferramenta (ferramentas). Deixamos essa etapa de fora aqui, porque a ferramenta apenas lê, a partir de um servidor que a loja mantém, e uma chamada errada não altera nada. Recomendamos deixar essa etapa de fora apenas nesse caso. Peça consentimento antes de efeitos colaterais, no capítulo sobre o modelo de segurança do MCP, acrescenta a etapa de consentimento.

Regra prática: Mantenha no seu próprio código o prompt do host e a interpretação da resposta do modelo, e teste o loop com respostas gravadas em vez de um modelo ao vivo. Grave o texto bruto do modelo, não objetos do SDK, para que uma nova versão do SDK não invalide uma gravação, e faça uma reprodução falhar quando a sua entrada mudar. Use um modelo ao vivo somente nas execuções de medição que decidem quais descrições e qual modelo você vai lançar.

O que dá errado em produção

Última alteração na edição 2026.11.11

O primeiro servidor da loja funciona em uma máquina. Levado para produção, os mesmos poucos componentes falham de algumas maneiras, cada uma com um sinal a observar.

Qualquer coisa na saída padrão quebra o canal. Uma biblioteca que imprime um banner, ou um print() esquecido durante a depuração, coloca na saída padrão do servidor uma linha que não é JSON-RPC, o que o transporte stdio proíbe (transporte stdio). O cliente mostra isso como erros de análise ou respostas perdidas, muitas vezes apenas no único caminho de código que imprime. O log do próprio SDK vai para o erro padrão (mcp/server/mcpserver/utilities/logging.py), então direcione o seu para lá também.

O servidor herda menos do que você imagina. O cliente stdio repassa uma lista curta de variáveis e mais nenhuma (mcp/client/stdio.py), então um servidor que funciona a partir do seu shell falha quando um host o inicia. O sinal é o mesmo que o exemplo do cliente mostrou: um Error executing tool genérico no cliente e um KeyError no erro padrão do servidor. Passe toda variável em env= e falhe na inicialização se alguma estiver faltando, não na primeira chamada. O servidor da loja lê suas variáveis dentro da ferramenta de propósito, para que o exemplo do cliente pudesse mostrar a falha tardia; um servidor que você publica deve lê-las uma vez, antes de atender requisições.

O servidor morre no meio de uma chamada. A especificação pede que o cliente reinicie um servidor stdio que termina e, como o protocolo não guarda estado, "as requisições em andamento simplesmente se perdem, e o cliente pode reenviá-las" (transporte stdio). mcp.Client não reinicia nada em 2.3.0: uma chamada em andamento falha com um MCPError que diz Connection closed, e o host precisa abrir um novo Client e tentar de novo (mcp/client/stdio.py, mcp/shared/jsonrpc_dispatcher.py). Uma chamada a get_order_status reenviada é inofensiva, mas um reembolso reenviado não é, e por isso a ferramenta de reembolso da loja precisa de uma verificação feita uma única vez no servidor (Manter o estado de ida e volta à prova de adulteração). No encerramento, o cliente fecha a entrada padrão do servidor e espera; o SDK concede 2 segundos antes de escalar para um sinal (mcp/client/stdio.py), então os servidores devem sair prontamente ao receber o fim da entrada.

Um início lento custa tempo e pode mudar a revisão. O cliente do SDK espera 10 segundos pela resposta a server/discover (mcp/client/session.py). Um servidor que carrega um modelo grande ou abre muitas conexões antes de ler sua primeira mensagem pode perder essa janela em uma máquina fria. O modo automático, então, trata o tempo esgotado como uma sondagem malsucedida e envia o antigo handshake initialize, que não tem limite de tempo padrão (mcp/client/_probe.py). Um servidor construído sobre este SDK que já respondeu à sondagem tardia rejeita initialize com suas versões suportadas, e o cliente sonda mais uma vez, de modo que a conexão tem sucesso mais de 10 segundos depois. Um servidor de outro SDK que também responde a initialize pode acabar em uma revisão de 2025 sem nenhum erro. O sinal é o valor de client.protocol_version, e não um servidor morto. Faça a configuração lenta sob demanda, ou depois que o servidor ler sua entrada.

O outro lado fala uma revisão de 2025. Client no modo automático recorre ao handshake antigo para um servidor da era 2025. Depois do recurso ao handshake antigo, a conexão fala a revisão de 2025, e assim nenhum dos recursos da revisão fixada está presente (changelog), e client.protocol_version informa qual revisão você obteve. Um servidor que não oferece suporte à versão do cliente responde com um erro, o que Tratar uma versão que o servidor não suporta mostra. Quando o erro vem do servidor de outra pessoa, o rastreamento de Ler as mensagens no fio mostra qual revisão cada lado enviou.

Outras linguagens ficam para trás ou vão além. A documentação do MCP lista os SDKs oficiais por nível. O nível 1 é TypeScript, Python, C#, Go, Rust e Ruby, e os níveis mudam com o tempo (SDKs). Um host em uma linguagem e um servidor em outra podem implementar os detalhes de uma revisão de maneiras diferentes, e o fio é onde se resolve qual delas está certa.

Regra prática: Na máquina que inicia um servidor stdio em produção, verifique três coisas: nada além de JSON-RPC chega à saída padrão, toda variável de que o servidor precisa é passada explicitamente, e o servidor responde a server/discover em até 10 segundos após iniciar. Mantenha o erro padrão do servidor nos seus logs, porque é ali que aparecem seus erros reais.

Decisões tomadas neste capítulo

Última alteração na edição 2026.11.11
  • Os dados da loja vêm de uma única semente e terminam em uma data fixa, de modo que todo exemplo do livro enxerga os mesmos clientes, pedidos e chamados.
  • A API da loja continua como sistema de registro. O servidor MCP é um adaptador fino que a chama com sua própria chave.
  • Uma ferramenta somente leitura, get_order_status, envolve um endpoint. Sua docstring é escrita para um modelo.
  • Falhas em que o modelo pode agir levantam ToolError; outras exceções chegam ao cliente como uma mensagem genérica, e seus detalhes permanecem no erro padrão do servidor.
  • stdio primeiro, com o transporte padrão de MCPServer.run(). Streamable HTTP vem em Servindo via Streamable HTTP.
  • mcp.Client em seu modo automático padrão, nunca um ClientSession inicializado à mão, de modo que a primeira mensagem seja server/discover na revisão fixada.
  • Os servidores são iniciados com sys.executable e um env= explícito, e as credenciais trafegam no ambiente, nunca no canal de comunicação.
  • Os rastros vêm de um relay sobre um subprocesso stdio real, porque o cliente em processo não envia JSON-RPC.
  • O prompt e a análise do loop do hospedeiro são código próprio do livro, e os exemplos reproduzem gravações do Qwen3-4B-Instruct-2507, um modelo aberto executado na CPU.
  • Uma gravação responde apenas às mensagens exatas que viu. Um prompt, chamado ou lista de ferramentas alterado faz a reprodução falhar, em vez de devolver uma resposta obsoleta.
  • Nenhuma etapa de consentimento neste capítulo, um afastamento da especificação que aceitamos apenas para uma ferramenta somente leitura em um servidor que a loja executa. O consentimento aparece em Peça consentimento antes de efeitos colaterais.

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.

Citar esta seção

Formato

Cada formato cita o livro em inglês, que esta tradução acompanha.

Todos os formatos citam esta edição. Seu link abre a edição atual, em que o título de cada seção indica quando seu texto foi alterado pela última vez. As datas de acesso e de recuperação são o dia em que você abre esta página.

Nesta página

Capítulo 1 de 12: MCP end to end

  1. Conheça a loja e a sua API
  2. Wrap one endpoint as a tool
  3. Chame a ferramenta a partir de um cliente
  4. Leia as mensagens no fio
  5. Deixe um modelo escolher a ferramenta
  6. O que dá errado em produção
  7. Decisões tomadas neste capítulo

Voltar ao topoTodos os capítulos