Teste um servidor e acompanhe sua execução

Cerca de 38 minutos min de leitura, com 6 exemplos em 8 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

Ao final deste capítulo, você será capaz de testar as ferramentas de um servidor Model Context Protocol em memória e por HTTP, identificar uma mudança de esquema que quebraria os clientes antes de ela ser publicada, reproduzir uma execução gravada do host como teste de regressão, rastrear chamadas de ferramentas com OpenTelemetry, medir com que frequência um modelo escolhe a ferramenta certa e aposentar uma ferramenta sem quebrar os clientes que a usam. As afirmações sobre o protocolo valem para a revisão 2026-07-28 da especificação, e as afirmações sobre o SDK valem para o SDK de Python, mcp 2.3.0.

Crie um host que trabalha com tickets terminou com o host que a equipe de suporte da loja usa, lib.ticket_host, trabalhando em todos os 48 tickets da loja com dois servidores, o da loja e o de rastreamento de encomendas do parceiro, com as respostas do modelo extraídas da gravação ticket-runs. Uma gravação é uma saída de modelo salva em examples/data/recorded/, então a execução é reproduzida da mesma forma em qualquer máquina, sem chamada ao modelo.

Essa execução deixou dois problemas. O host escolheu a primeira ferramenta certa para 36 of 48 tickets, mas nada indicava quais ele errou nem por quê. Nos tickets de reembolso, o modelo escrevia aos clientes como se os reembolsos já tivessem sido feitos, enquanto 0 of 7 dos tickets que pediam reembolso chegaram a issue_refund. O servidor e o host da loja não param de mudar: uma descrição é reescrita, um campo é renomeado, uma ferramenta é substituída. Qualquer uma dessas mudanças pode quebrar um cliente sem que uma única chamada falhe do lado do servidor.

Para construir verificações, a equipe obtém alguns recursos do Model Context Protocol (MCP): esquemas tipados para cada ferramenta, contexto de rastreamento no _meta de cada requisição e notificações de mudança para a lista de ferramentas. Este capítulo constrói as verificações da loja sobre eles. Três módulos novos concentram a configuração. lib.testing executa um módulo do pytest e imprime uma linha estável por teste. lib.contract compara duas versões dos esquemas de uma ferramenta. lib.queue_replay reproduz a execução da fila do capítulo 10 e verifica o que cada resposta promete contra as chamadas que o host fez. Dois exemplos deste capítulo reproduzem a gravação ticket-runs; os demais não usam modelo, e o capítulo não faz chamadas de modelo próprias.

Testar ferramentas em memória

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

Um teste das ferramentas de um servidor deve rodar sem porta e sem subprocesso, para que possa rodar a cada mudança. O Client do SDK Python oferece isso: recebendo um objeto de servidor em vez de uma URL ou de parâmetros de inicialização, ele se conecta ao servidor no mesmo processo. O guia de testes do SDK chama isso de a forma de testar um servidor, com a frase "No subprocess. No port. Nothing on a wire" (testing). No modo padrão, mode="auto", a conexão é um par de DirectDispatcher, que entrega cada requisição ao handler do servidor como um objeto Python, sem streams, sem enquadramento JSON-RPC e sem o handshake de initialize (mcp/client/client.py, _connect_inproc; mcp/shared/direct_dispatcher.py).

Dois detalhes importam em um teste. raise_exceptions=True faz com que uma falha fora do corpo de uma ferramenta, como um bug em um handler, chegue com a mensagem real em vez de um "Internal server error" sanitizado. Isso não muda o comportamento da exceção da própria ferramenta: ela continua sendo um resultado com is_error=True, como para qualquer cliente (testing). O SDK também carimba a identidade do servidor no _meta de cada resultado, então um teste que compara resultados inteiros precisa primeiro limpar result.meta (mesma página). Fazer asserções apenas sobre os campos que interessam ao teste evita tanto o carimbo quanto a biblioteca de snapshots do guia do SDK, inline-snapshot, que o livro não fixa. Testes assíncronos não precisam de plugin extra: o anyio, do qual o SDK depende, traz um plugin de pytest que executa qualquer teste marcado com pytest.mark.anyio (AnyIO testing).

O que o caminho em memória deixa de fora importa tanto quanto o que ele cobre. Sem a camada HTTP, um teste em memória nunca encontra as verificações que um servidor Streamable HTTP faz nos cabeçalhos Origin e Host, nunca recebe um server-sent event e nunca carrega contexto de rastreamento, como mostra Rastrear chamadas com OpenTelemetry. O guia do SDK acrescenta que o caminho in-process não entrega notificações independentes, como uma mudança na lista de ferramentas (client caching). Uma suíte totalmente em memória pode passar enquanto todo cliente HTTP falha.

Os testes do shop rodam contra o servidor do capítulo 3, lib.shop_tools, de Projetar ferramentas que um modelo pode usar, com a API do shop em loopback para cada teste, servida pelo fixture shop_api_env de lib.testing. Três testes rodam em memória: o status de um pedido volta como campos estruturados, um pedido desconhecido volta como erro de execução de ferramenta que cita find_orders, e um ID de pedido no formato errado é recusado antes que a ferramenta rode. O quarto serve as mesmas ferramentas por Streamable HTTP em loopback e envia uma requisição tools/call cujo cabeçalho Mcp-Name nomeia uma ferramenta diferente do corpo: uma requisição que o cliente do SDK nunca envia e que um cliente em memória não consegue expressar. Executado como script, o arquivo roda os próprios testes com pytest 9.2.0.

test-tools-in-memory.py Python 3.12.15 · cryptography 50.0.2 · httpx2 2.16.2 · jsonschema 4.26.0 · mcp 2.3.0 · mcp-types 2.3.0 · pydantic 2.14.3 · pytest 9.2.0 · starlette 1.10.0 · uvicorn 0.54.0 Aprovado
"""Four pytest tests of the shop's tools: three through the SDK's in-process client, and one over Streamable HTTP onloopback, which reaches a check an in-memory test never makes. The prose's point rests on the unknown-order test'sline and on the last line, which counts the passes."""import pytestfrom mcp import Clientfrom lib import http_mcp, loopback, shop_toolsfrom lib.testing import anyio_backend, run, shop_api_envpytestmark = pytest.mark.anyio                            # runs the async tests on anyio's pytest pluginasync def test_order_status_fields(shop_api_env):        # shop_api_env serves the shop's API on loopback for this test    # raise_exceptions=True: a bug outside a tool's body raises here, with its own message    async with Client(shop_tools.create_server(), raise_exceptions=True) as client:        result = await client.call_tool("get_order_status", {"order_id": "O-1873"})    assert not result.is_error    assert result.structured_content["order_id"] == "O-1873"    assert result.structured_content["status"] == "delivered"async def test_unknown_order_is_a_tool_error(shop_api_env):    async with Client(shop_tools.create_server(), raise_exceptions=True) as client:        result = await client.call_tool("quote_refund", {"order_id": "O-7144"})    assert result.is_error                                    # raise_exceptions doesn't make it raise    assert "find_orders" in result.content[0].text            # the model is told what to do insteadasync def test_malformed_order_id_is_refused(shop_api_env):    async with Client(shop_tools.create_server(), raise_exceptions=True) as client:        result = await client.call_tool("get_order_status", {"order_id": "1873"})    assert result.is_error    text = result.content[0].text                             # only argument validation writes this error:    assert "order_id" in text and "string_pattern_mismatch" in text   # the field and pydantic's pattern checkdef test_http_refuses_a_mismatched_header(shop_api_env):    with loopback.serve(shop_tools.create_server().streamable_http_app()) as base_url:        # the header names check_stock while the body calls get_order_status: the mismatch the server must refuse        reply = http_mcp.post(base_url + "/mcp", "tools/call", {"name": "get_order_status",                              "arguments": {"order_id": "O-1873"}}, headers={"Mcp-Name": "check_stock"})    assert reply.status_code == 400    assert reply.json()["error"]["code"] == -32020        # the JSON-RPC code the server returns for the mismatchif __name__ == "__main__":    run(__file__)
Saídapython test-tools-in-memory.py
test_order_status_fields: passed
test_unknown_order_is_a_tool_error: passed
test_malformed_order_id_is_refused: passed
test_http_refuses_a_mismatched_header: passed
tests passed: 4 of 4

Uma ferramenta que falha é um resultado sobre o qual um modelo pode agir. A execução informa 4 of 4, e o teste do pedido desconhecido passed com raise_exceptions=True ativado: a ferramenta lançou ToolError, e o cliente recebeu um resultado comum, com a flag de erro definida e o conselho do servidor no texto, que é o que um modelo precisa para se corrigir (Report failures as tool results).

O ID malformado nunca chegou à ferramenta. O teste afirma que o erro cita order_id e o string_pattern_mismatch do pydantic, que só a validação de argumentos escreve. O SDK validou os argumentos contra o modelo de parâmetros da ferramenta, do qual seu esquema de entrada é gerado, antes de chamar a ferramenta (mcp/server/mcpserver/server.py, _handle_call_tool). O teste HTTP cobre a camada que os outros deixam de lado: o servidor recusou o cabeçalho divergente com status 400 e o erro JSON-RPC -32020, como descreve Ler uma troca HTTP, antes de qualquer código da ferramenta rodar.

Regra prática: Teste cada ferramenta em memória com Client(server, raise_exceptions=True), e faça asserções sobre os campos structured_content e sobre is_error, não sobre resultados inteiros. Mantenha ao menos um teste por transporte que você entrega e que passe por ele em loopback, para as verificações de cabeçalho, origem e streaming que um teste em memória não alcança, e coloque ali também os testes de propagação de rastreamento e de mudanças na lista.

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

Check schemas as a contract

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

The in-memory tests from the previous section check that a tool does what its own release says. They don't check that the release still fits the clients using the last one. A client depends on a tool through its schemas: it sends arguments that its copy of the inputSchema accepts, and it reads the fields that its copy of the outputSchema promises. When a tool declares an output schema, the server MUST return structured content that conforms to it, and clients SHOULD validate it (tools, "Structured Content").

The Python SDK's client does validate, and it validates against its own copy. It keeps one compiled validator per tool, built from the output schema in the last tools/list it absorbed, and replaces it only when a later listing brings a different schema (mcp/client/session.py, _output_schema_validator and _absorb_tool_listing). A non-error result that doesn't match raises RuntimeError in the caller (mcp/client/session.py, validate_tool_result). So a server that renames an output field breaks every connected client that listed its tools before the release, at the moment each one next calls the tool, and the server sees nothing wrong.

In the shop's case, release 2 of the server renames the per-warehouse on_hand field of check_stock to count. To see the break, a client connects to release 1 in memory and lists the tools. It keeps its connection while the server swaps check_stock for release 2's version, as a rolling deploy would. Then the client calls the tool, lists again and calls once more. Last, a contract test runs the two checks it makes before a release ships: lib.contract.breaking_changes, a diff of the two releases' schemas, and a validation of release 2's real result against release 1's published output schema with jsonschema, the library the client uses.

schema-change-breaks-a-client.py Python 3.12.15 · cryptography 50.0.2 · httpx2 2.16.2 · jsonschema 4.26.0 · mcp 2.3.0 · mcp-types 2.3.0 · pydantic 2.14.3 · pytest 9.2.0 · starlette 1.10.0 · uvicorn 0.54.0 Aprovado
"""What a client connected before a release sees when the release renames check_stock's on_hand to count, and whatthe contract checks report about the same change. The prose's point rests on the client's error line, which namesthe missing field, and on the contract check's line."""import asynciofrom mcp import Clientfrom pydantic import BaseModelfrom lib import confirmations, contract, shop_toolsfrom lib.testing import shop_api_hereclass Warehouse(BaseModel):    warehouse: str    count: int                                            # release 1 called it on_hand    last_counted: strclass StockReport(BaseModel):    sku: str    available: int    warehouses: list[Warehouse]def check_stock(sku: shop_tools.Sku) -> StockReport:    report = confirmations.chapter3_tools()["check_stock"].fn(sku)       # release 1's tool does the reading    return StockReport(sku=sku, available=report.available, warehouses=[Warehouse(        warehouse=w.warehouse, count=w.on_hand, last_counted=str(w.last_counted)) for w in report.warehouses])async def main() -> None:    server = shop_tools.create_server()    with shop_api_here():                                  # the server's tools run in this process        async with Client(server) as client:            listing = await client.list_tools()            print("release 1's tools/list cache hint:", f"ttlMs {listing.ttl_ms}")            server.remove_tool("check_stock")                                  # the release, swapped in while connected            server.add_tool(check_stock, description=shop_tools.DESCRIPTIONS["check_stock"])            try:                await client.call_tool("check_stock", {"sku": "KG-1031"})            except RuntimeError as error:                print("client that listed before the release:", error.args[0].splitlines()[0])  # the message's first line            new = next(tool for tool in (await client.list_tools()).tools if tool.name == "check_stock")  # the release 2 schema            result = await client.call_tool("check_stock", {"sku": "KG-1031"})            print("client after listing again:", "result" if not result.is_error else "tool error")    old = next(tool for tool in listing.tools if tool.name == "check_stock")    print("contract check:", "; ".join(contract.breaking_changes(old, new)) or "no breaking change")    validator = contract.validator(old.output_schema)(old.output_schema)    # by the dialect the schema declares    print("validator for release 1's schema:", type(validator).__name__ + ", as it declares",          old.output_schema.get("$schema", "no $schema"))    # the first error the schema finds in release 2's real result    print("release 2's result against release 1's schema:", next(validator.iter_errors(result.structured_content)).message)asyncio.run(main())
Saídapython schema-change-breaks-a-client.py
release 1's tools/list cache hint: ttlMs 0
client that listed before the release: Invalid structured content returned by tool check_stock: 'on_hand' is a required property
client after listing again: result
contract check: output warehouses[].on_hand: removed
validator for release 1's schema: Draft202012Validator, as it declares no $schema
release 2's result against release 1's schema: 'on_hand' is a required property

Release 1's tool list carried the SDK's default cache hint, ttlMs 0, so the list was stale the moment it arrived, and the client still validated against it. The call after the release failed inside the client: "Invalid structured content returned by tool check_stock: 'on_hand' is a required property". The server had returned a correct release 2 result. After the client listed the tools again, the same call came back as a result. A zero TTL doesn't protect a connected client, because the validator follows the last listing, not the cache: a client that lists once at startup holds that schema for as long as it runs.

Both contract checks caught the change without a client. The schema diff reported output warehouses[].on_hand: removed, and validating release 2's result against release 1's schema failed with the client's own message: "'on_hand' is a required property". The diff is a reviewer's aid: it compares field paths, types and required inputs, and its docstring lists what it leaves out, such as patterns and enums. The validation is the test to keep, because it checks the server's real output against the exact schema that clients hold.

Breaking changes aren't symmetric. On the output side, removing, renaming or retyping a field breaks clients, and adding an optional field doesn't. On the input side, adding a required argument breaks old callers, and removing one breaks them quietly, because the SDK's server drops arguments it doesn't know without an error, as Treat ticket text as untrusted data shows. The pinned revision allows any JSON Schema 2020-12 keyword in both schemas, and reads a schema with no $schema as 2020-12 (tools). A schema may name another dialect in $schema, and clients and servers MUST validate by the declared dialect, or by 2020-12 when none is declared (base protocol, "JSON Schema Usage"). So choose the validator from the schema, as the SDK's client does with jsonschema's validator_for (mcp/client/session.py, _output_schema_validator). lib.contract.validator does the same for the shop's checks, with 2020-12 as the default. pydantic writes no $schema, so release 1's schema got Draft202012Validator, as it declares no $schema.

Working rule: Keep the last release's tools/list in the repository, and in CI validate every structured result your tests produce against it as well as against the new schema, each by the dialect it declares and by 2020-12 when it declares none. Treat a removed, renamed or retyped output field and a new required input as a breaking change: add the new field beside the old one, or add a new tool, and retire the old shape through a window (Change tools without breaking clients). Don't rely on a short TTL to protect clients that are already connected.

Reproduzir execuções gravadas do host

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

Testes de ferramentas e testes de contrato cobrem o servidor. O host de suporte, de Construa um host que trabalha com tickets, tem lógica própria entre o modelo e os servidores: ele roteia nomes, pede consentimento, devolve resultados e limita turnos, e uma mudança ali pode fazer todos os tickets darem errado sem que nenhuma ferramenta falhe. Uma reprodução cobre essa camada. Ela executa o host real contra os servidores reais, com as respostas do modelo tiradas de uma gravação, de modo que um teste possa verificar o que o host fez em cada ticket.

Uma reprodução testa o host e os servidores contra saídas fixas do modelo. Ela não testa o modelo: um modelo diferente, ou o mesmo com outra amostragem, precisa de uma nova gravação. E ela só vale enquanto as mensagens permanecerem como foram gravadas. ReplayModel de lib.host busca cada resposta pelo SHA-256 das mensagens exatas, que incluem todas as definições de ferramentas e todos os resultados de ferramentas até então, e levanta RecordingMismatch quando elas diferem (Execute o laço do host). Assim, uma reprodução funciona também como um alarme: qualquer mudança no que o modelo veria a interrompe, e a equipe então decide se deve gravar de novo.

A reprodução também dá aos resultados da fila uma segunda leitura. Trabalhe a fila de tickets constatou que o modelo dizia aos clientes que os reembolsos estavam a caminho para pedidos que ele nunca reembolsou. Uma resposta é a afirmação do modelo, e o registro de chamadas do host é o registro do que de fato aconteceu; por isso o host pode comparar os dois antes que uma resposta chegue a um cliente. lib.queue_replay traz uma versão pequena dessa verificação, construída sobre a verificação de frases com que o capítulo 10 fez sua contagem, ticket_host.promises_refund, que procura frases como "will be refunded" ou "we'll refund". Reutilizá-la faz com que as contagens deste capítulo e as do capítulo 10 sejam a mesma medida. Seu unbacked_refund é verdadeiro quando a última resposta de uma execução faz essa promessa e nenhuma chamada de issue_refund na execução retornou um resultado. A lista de frases é uma heurística escrita contra as respostas desta gravação, não um classificador, e a docstring do módulo diz o que ela deixa passar.

queue_replay.replay_queue reproduz a fila inteira, com o host de suporte configurado exatamente como o work-the-ticket-queue do capítulo 10 o configura. A execução imprime a sequência de ferramentas de um ticket, conta os reembolsos e as respostas que prometem um, e reproduz o primeiro ticket depois de uma frase ter sido acrescentada à descrição de quote_refund.

replay-ticket-runs.py Python 3.12.15 · cryptography 50.0.2 · httpx2 2.16.2 · jsonschema 4.26.0 · mcp 2.3.0 · mcp-types 2.3.0 · pydantic 2.14.3 · starlette 1.10.0 · uvicorn 0.54.0 Aprovado
"""Replay chapter 10's queue run, the recording ticket-runs, through the support host, and check each reply's promiseagainst the host's call log. The prose's point rests on the refund lines, which compare refunds issued with repliesthat promise one, and on the last line, which shows what a one-sentence rewording does to the replay."""import asynciofrom lib import queue_replay, shop_tools, ticket_hostfrom lib.host import RecordingMismatchfrom lib.shop_data import load_shopdef reword_quote_refund(host) -> None:              # the server's next release adds a sentence to one description    changed = {**shop_tools.DESCRIPTIONS}    changed["quote_refund"] += " Quotes are in the order's currency."    host.listed["shop"] = shop_tools.with_descriptions(host.listed["shop"], changed)async def main() -> None:    tickets = {ticket.ticket_id: ticket for ticket in load_shop().tickets}    runs = await queue_replay.replay_queue()    print("tickets replayed:", len(runs))    print("T-0009 tools:", " then ".join(turn.tool for turn in runs["T-0009"].calls))   # its calls, in order    print("refunds issued:", sum(queue_replay.refunded(run) for run in runs.values()))    # the phrase check from chapter 10, a rule of thumb: see the module's docstring for what it misses    promised = [ticket_id for ticket_id, run in runs.items() if ticket_host.promises_refund(run.answer)]    # a promise with no refund behind it: no issue_refund call in the run returned a result    unbacked = [ticket_id for ticket_id in promised if queue_replay.unbacked_refund(runs[ticket_id])]    print("replies that promise a refund:", len(promised))    print("of which no call made:", len(unbacked))    for tag in ("issue_refund", "quote_refund"):           # the tickets tagged with each refund tool        group = [t for t in tickets.values() if t.expected_tool == tag]        print(f"{tag} tickets flagged:", f"{sum(t.ticket_id in unbacked for t in group)} of {len(group)}")    print("flagged:", ", ".join(unbacked))    try:        await queue_replay.replay_queue(change=reword_quote_refund, tickets=[tickets["T-0001"]])    except RecordingMismatch:        print("after rewording quote_refund, T-0001 replays:", "no, RecordingMismatch")asyncio.run(main())
Saídapython replay-ticket-runs.py
tickets replayed: 48
T-0009 tools: shop.quote_refund then shop.find_orders
refunds issued: 0
replies that promise a refund: 11
of which no call made: 11
issue_refund tickets flagged: 6 of 7
quote_refund tickets flagged: 5 of 9
flagged: T-0007, T-0020, T-0029, T-0034, T-0036, T-0037, T-0040, T-0042, T-0045, T-0046, T-0048
after rewording quote_refund, T-0001 replays: no, RecordingMismatch

Todos os 48 tickets foram reproduzidos, e o ticket T-0009 seguiu o caminho que tomou no capítulo 10: shop.quote_refund then shop.find_orders. Uma asserção sobre essa sequência é um teste de regressão para o host. Se uma mudança no roteamento ou no tratamento de erros fizesse o primeiro erro de execução de ferramenta voltar de outra forma, o segundo turno do modelo deixaria de corresponder à gravação, e a reprodução pararia.

lib.queue_replay sinaliza as promessas que nenhuma chamada sustenta, e um host deve enviar essas respostas a uma pessoa, em vez de enviá-las ao cliente. O host emitiu 0 reembolsos, porém 11 respostas prometem um, e 11 delas não têm reembolso por trás.

Dos tickets que pedem reembolso, 6 of 7 estão sinalizados, e dos tickets que pedem apenas saber o que um reembolso seria, 5 of 9 estão, cada resposta dizendo ao cliente que o dinheiro estava a caminho. O único pedido de reembolso não sinalizado, T-0024, terminou com o modelo perguntando qual produto o cliente quis dizer, o que não promete nada. Os tickets sinalizados são T-0007, T-0020, T-0029, T-0034, T-0036, T-0037, T-0040, T-0042, T-0045, T-0046, T-0048.

A reescrita no fim mostra o alarme. Depois de uma frase ter sido acrescentada a uma descrição, a reprodução do primeiro ticket deu no, RecordingMismatch. O prompt de cada ticket contém a descrição de todas as ferramentas, de modo que alterar qualquer descrição altera todos os prompts. Esse é o custo das reproduções, e também o seu uso: uma descrição reescrita é a mudança que pode alterar o que o modelo escolhe, e a reprodução não deixa isso passar sem medição.

Regra prática: Reproduza uma execução gravada da fila inteira no CI, faça asserções sobre a sequência de ferramentas de cada ticket e execute uma verificação que compare as promessas de cada resposta com as chamadas que retornaram um resultado. Mantenha IDs gerados e relógios fixos nos servidores contra os quais a reprodução roda; do contrário ela para por motivos que não são mudanças. Depois, trate RecordingMismatch como um sinal, não como um teste instável: quando você alterar uma descrição, um prompt ou a saída de uma ferramenta, grave de novo com o script de gravação e compare as pontuações da nova execução com as da antiga antes de publicar.

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

Trace calls with OpenTelemetry

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

Tests run before a release; traces show what a server does after it. OpenTelemetry is the common way to get them: an application creates spans, each a named, timed operation with attributes and a parent, and an exporter sends them to a tracing backend. MCP adds one thing of its own. At the pinned revision, the _meta keys traceparent, tracestate and baggage are reserved for trace context, and their values MUST follow the W3C Trace Context and Baggage formats (base protocol). That is how a client's trace and a server's trace join into one, whatever the transport.

The Python SDK traces with no setup in your server's code. Every server installs OpenTelemetryMiddleware, which wraps each inbound message in a SERVER span and does nothing until an OpenTelemetry SDK and exporter are installed (mcp/server/lowlevel/server.py; OpenTelemetry). The source marks the middleware provisional, so its details may change in a 2.x minor release. On the client side, the JSON-RPC paths, which are URLs, stdio and the legacy in-memory mode, open a CLIENT span named MCP send {method} {target} and inject traceparent into the request's _meta, and the server extracts it as the parent of its span (mcp/shared/jsonrpc_dispatcher.py, mcp/shared/_otel.py). The in-process path from Test tools in memory sends no JSON-RPC, so it creates no client span and injects nothing.

The shop wants a trace for each tool call, findable by tool name and showing whether it failed. The script installs OpenTelemetry's SDK, opentelemetry-sdk 1.45.2, with an InMemorySpanExporter, which keeps finished spans in a list that a test can read (opentelemetry/sdk/trace/export/in_memory_span_exporter.py). The script serves chapter 3's tools from Design tools a model can use over Streamable HTTP on loopback in the same process, so the client's and the server's spans land in the same list. It calls find_orders and then quote_refund for an order that doesn't exist. Then it makes the same find_orders call in memory twice, the second time inside a span of the test's own.

trace-a-tool-call.py Python 3.12.15 · cryptography 50.0.2 · httpx2 2.16.2 · jsonschema 4.26.0 · mcp 2.3.0 · mcp-types 2.3.0 · opentelemetry-api 1.45.2 · opentelemetry-sdk 1.45.2 · opentelemetry-semantic-conventions 0.66b2 · pydantic 2.14.3 · pytest 9.2.0 · starlette 1.10.0 · uvicorn 0.54.0 Aprovado
"""The OpenTelemetry spans the SDK emits for the shop's tool calls, over Streamable HTTP on loopback and in memory.The prose's point rests on two printed lines: the HTTP server span, which shows the trace context crossing the wire,and the in-memory server span parents, which show what happens without it."""import asynciofrom mcp import Clientfrom opentelemetry import tracefrom opentelemetry.sdk.trace import TracerProviderfrom opentelemetry.sdk.trace.export import SimpleSpanProcessorfrom opentelemetry.sdk.trace.export.in_memory_span_exporter import InMemorySpanExporterfrom opentelemetry.semconv._incubating.attributes.mcp_attributes import McpMethodNameValuesfrom lib import loopback, shop_toolsfrom lib.testing import shop_api_herespans = InMemorySpanExporter()trace.set_tracer_provider(provider := TracerProvider())provider.add_span_processor(SimpleSpanProcessor(spans))      # each span, as it ends, into memorydef finished(name: str) -> list:                 # every finished span with this name, in the order they ended    return [span for span in spans.get_finished_spans() if span.name == name]def parent(span) -> str:    return next((s.name for s in spans.get_finished_spans() if span.parent and s.context.span_id ==                 span.parent.span_id), "none")      # "none" for a span with no parent, or whose parent never finishedasync def main() -> None:    server = shop_tools.create_server()    with shop_api_here(), loopback.serve(server.streamable_http_app()) as base_url:        async with Client(base_url + "/mcp") as client:            await client.call_tool("find_orders", {"customer_id": "C-0127"})            await client.call_tool("quote_refund", {"order_id": "O-7144"})            # a tool error        print("HTTP spans:", ", ".join(sorted(span.name for span in spans.get_finished_spans())))        # the test makes one call of each, so the first finished span of each name is the call's        call, error = finished("tools/call find_orders")[0], finished("tools/call quote_refund")[0]        print("HTTP server span:", call.name, f"({call.kind.name}), parent: {parent(call)}")        for key in sorted(set(call.attributes) - {"jsonrpc.request.id"}):   # the request ID changes on every run            print(f"attribute {key}:", call.attributes[key])        print("tool error span status:", error.status.status_code.name)        print("tool error span error.type:", error.attributes["error.type"])        spans.clear()        async with Client(server) as client:            await client.call_tool("find_orders", {"customer_id": "C-0127"})            # a span of the test's own, which the in-memory server falls back to as the parent            with trace.get_tracer("shop-tests").start_as_current_span("test find_orders"):                await client.call_tool("find_orders", {"customer_id": "C-0127"})        print("in-memory spans:", ", ".join(sorted(span.name for span in spans.get_finished_spans())))        print("in-memory server span parents:", ", ".join(parent(s) for s in finished("tools/call find_orders")))    # the pinned conventions predate the pinned revision, and this list has no server/discover    assert "server/discover" not in {m.value for m in McpMethodNameValues}asyncio.run(main())
Saídapython trace-a-tool-call.py
HTTP spans: MCP send server/discover, MCP send tools/call find_orders, MCP send tools/call quote_refund, MCP send tools/list, server/discover, tools/call find_orders, tools/call quote_refund, tools/list
HTTP server span: tools/call find_orders (SERVER), parent: MCP send tools/call find_orders
attribute gen_ai.operation.name: execute_tool
attribute gen_ai.tool.name: find_orders
attribute mcp.method.name: tools/call
attribute mcp.protocol.version: 2026-07-28
tool error span status: ERROR
tool error span error.type: tool_error
in-memory spans: server/discover, test find_orders, tools/call find_orders, tools/call find_orders, tools/list
in-memory server span parents: none, test find_orders

Over HTTP the spans came in pairs, each server span paired with a client span of the same method: MCP send server/discover, MCP send tools/call find_orders, MCP send tools/call quote_refund, MCP send tools/list, server/discover, tools/call find_orders, tools/call quote_refund, tools/list. The client listed the tools before its first call, because it validates the result against the output schema. The trace shows the server's span for the call, tools/call find_orders (SERVER), parent: MCP send tools/call find_orders, so the trace context crossed in _meta.

Its attributes name the method, tools/call, the operation, execute_tool, the tool, find_orders, and the revision (mcp/server/_otel.py).

The failed quote's span has the status ERROR and the error.type tool_error, although the call returned a result and not a JSON-RPC error, so a tracing backend can count tool execution errors without reading result bodies.

A test of trace propagation needs HTTP or stdio, because in memory the server has nothing to extract. In memory there were no client spans, only the server's spans and the test's own test find_orders: server/discover, test find_orders, tools/call find_orders, tools/call find_orders, tools/list. The two server spans' parents were none, test find_orders, in that order. With nothing to extract, the server falls back to whatever span is current, and only the test's own span gave it one (mcp/shared/_otel.py, extract_trace_context).

The names a server emits are the part to treat with care. OpenTelemetry's semantic conventions for MCP have the status Development; they recommend span names of the form {mcp.method.name} {target} and define metrics such as mcp.server.operation.duration (MCP semantic conventions, read 2026-10-31). They have also moved: the page the MCP specification links to shows a notice that the GenAI conventions moved to a repository of their own, which has no tagged release (moved notice). The SDK's server spans follow the recommended naming. Its client span name, MCP send …, doesn't, and the SDK emits no metrics: the source of mcp 2.3.0 never creates a meter. The pinned conventions package, opentelemetry-semantic-conventions 0.66b2, predates the pinned revision. Its list of method names has initialize and logging/setLevel, it still defines mcp.session.id, and it has no server/discover (opentelemetry/semconv/_incubating/attributes/mcp_attributes.py).

For logs, the pinned revision deprecates MCP's own Logging messages, notifications/message, and points servers to standard error on stdio and to OpenTelemetry otherwise (changelog). Replace sampling, roots and logging covers the move.

Working rule: Install an OpenTelemetry SDK and exporter in every server and host you run, and let the SDK's middleware make the server spans. Build dashboards on the attributes the SDK emits, mcp.method.name, gen_ai.tool.name and error.type, and label them as following a Development-status convention at a named version, because the names may change. Don't validate method names against the pinned conventions package. Test propagation over a real transport, and wrap in-memory calls in a span of your own when a test needs a parent.

Meça com que frequência a ferramenta certa é escolhida

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

O replay em Replay de execuções gravadas do host pergunta se o host ainda faz o que fazia. Uma segunda pergunta é com que frequência o modelo escolhe bem, com as ferramentas e descrições que a loja lhe oferece. A primeira medida usual é a acurácia de seleção de ferramenta: a proporção de casos em que a primeira chamada do modelo usa a ferramenta que um agente correto usaria, frequentemente chamada de acurácia top-1. Benchmarks também avaliam os argumentos. O Berkeley Function Calling Leaderboard, por exemplo, verifica o nome e os argumentos de cada chamada em conjunto, comparando-os com os esperados por meio da correspondência de suas árvores de sintaxe abstrata (BFCL).

Um número obtido de uma gravação fixa mede algo restrito: os nomes e descrições de ferramentas da loja, em relação a um único modelo, Qwen3-4B-Instruct-2507, quantizado como Q4_K_M e amostrado com temperatura 0.7 (Trabalhe a fila de tickets), com o único prompt e a única seed do livro, sobre os 48 tickets que o livro escreveu.

É um único sorteio dessa configuração, e os grupos são pequenos: o menor tem 8 tickets, de modo que um ticket representa uma grande parcela da sua pontuação. Ele não diz nada sobre modelos em geral, e qualquer mudança em uma descrição exige uma nova gravação antes que o número tenha sentido, o que o RecordingMismatch do replay garante. Cada ticket traz a ferramenta que um agente correto chama primeiro. O script avalia com ticket_host.expected_first_tool, como o capítulo 10 faz: um pedido de reembolso conta como certo quando começa com quote_refund, porque issue_refund precisa de uma cotação primeiro.

Para avaliar o replay, o script pega a primeira chamada de ferramenta de cada ticket e imprime a acurácia geral, por ferramenta esperada e para cada confusão. Para as chamadas certas que nomeiam um pedido, ele também avalia o argumento order_id de duas formas: contra o ID como o ticket o escreveu e contra o pedido que o cliente quis dizer. As duas diferem nos 5 tickets em que um cliente digitou o número errado.

tool-choice-accuracy.py Python 3.12.15 · cryptography 50.0.2 · httpx2 2.16.2 · jsonschema 4.26.0 · mcp 2.3.0 · mcp-types 2.3.0 · pydantic 2.14.3 · starlette 1.10.0 · uvicorn 0.54.0 Aprovado
"""Score the first tool call of every ticket in chapter 10's queue run against the tool each ticket is tagged with,overall, per tag and by confusion, and check the order IDs of the right calls. The prose's point rests on theaccuracy lines, the per-tag line for refunds, and the two order-ID lines, which differ."""import asynciofrom collections import Counterfrom lib import queue_replay, ticket_hostfrom lib.shop_data import load_shopasync def main() -> None:    tickets = load_shop().tickets    runs = await queue_replay.replay_queue()    scored = []                                            # (ticket, expected tool, first tool called)    for ticket in tickets:        calls = runs[ticket.ticket_id].calls        # the first call, or None when the host made none; a refund ticket expects quote_refund first        scored.append((ticket, ticket_host.expected_first_tool(ticket), calls[0] if calls else None))    right = [(t, call) for t, expected, call in scored if call and call.tool == expected]    print("first tool right:", f"{len(right)} of {len(scored)}")    print("top-1 accuracy:", f"{len(right) / len(scored):.2f}")    for expected, count in sorted(Counter(expected for _, expected, _ in scored).items()):        hits = sum(1 for t, e, call in scored if e == expected and call and call.tool == expected)        print(f"expected {expected}:", f"{hits} of {count}")    confusions = Counter((expected, call.tool if call else "no tool") for _, expected, call in scored                         if not call or call.tool != expected)    for (expected, chosen), count in confusions.most_common():        print(f"expected {expected}, called {chosen}:", count)    with_order = [(t, call) for t, call in right if t.order_id and "order_id" in call.arguments]  # right calls naming an order    as_written = sum(call.arguments["order_id"] == t.cited_order_id for t, call in with_order)   # the ID the ticket gave    meant = sum(call.arguments["order_id"] == t.order_id for t, call in with_order)              # the customer's order    print("right tool, order ID as the ticket wrote it:", f"{as_written} of {len(with_order)}")    print("right tool, order the customer meant:", f"{meant} of {len(with_order)}")    # tickets whose cited ID isn't the order the customer meant    typos = [(t, e, call) for t, e, call in scored if t.cited_order_id and t.cited_order_id != t.order_id]    print("tickets with a mistyped order ID:", len(typos))    print("of which the right tool was called:", sum(1 for _, e, call in typos if call and call.tool == e))    for t, _, call in [(t, e, call) for t, e, call in typos if not call or call.tool != e]:        print(f"mistyped {t.ticket_id}, first tool:", call.tool if call else "no tool")    print("smallest expected-tool group, tickets:", min(Counter(e for _, e, _ in scored).values()))    manifest = queue_replay.manifest()    print("recorded model:", manifest["model"].split("/")[-1])   # the model's name, without its publisher's path    print("recorded quantization:", manifest["quantization"])asyncio.run(main())
Saídapython tool-choice-accuracy.py
first tool right: 36 of 48
top-1 accuracy: 0.75
expected shop.check_stock: 10 of 10
expected shop.find_orders: 8 of 8
expected shop.get_order_status: 12 of 14
expected shop.quote_refund: 6 of 16
expected shop.quote_refund, called shop.get_order_status: 8
expected shop.get_order_status, called partner.track_parcel: 2
expected shop.quote_refund, called shop.find_orders: 2
right tool, order ID as the ticket wrote it: 18 of 18
right tool, order the customer meant: 14 of 18
tickets with a mistyped order ID: 5
of which the right tool was called: 4
mistyped T-0042, first tool: shop.get_order_status
smallest expected-tool group, tickets: 8
recorded model: Qwen3-4B-Instruct-2507
recorded quantization: Q4_K_M

A primeira ferramenta esteve certa em 36 of 48 tickets, uma acurácia top-1 de 0.75, o mesmo 36 of 48 que o capítulo 10 contou.

O número geral esconde onde estão os erros. Perguntas sobre estoque obtiveram 10 of 10 e buscas de pedidos 8 of 8, mas os tickets de reembolso apenas 6 of 16, e a maior parte dos erros, 8, foi para get_order_status, embora sua descrição diga para usar quote_refund em caso de reembolso e a descrição de quote_refund diga para chamá-la primeiro. Esse par de descrições é o que deve ser trabalhado a seguir, e a fila é o conjunto de tickets a ser gravado de novo quando elas mudarem. As duas perguntas de status que foram para partner.track_parcel são o caso do número de rastreamento do capítulo 10 (Trabalhe a fila de tickets).

Os argumentos mostram por que a referência importa. Com a ferramenta certa, o modelo usou o ID do pedido como o ticket o escreveu em 18 of 18 chamadas, e o pedido que o cliente quis dizer em 14 of 18 chamadas.

Os erros são digitações dos clientes. Entre os tickets com número digitado errado, 4 chegaram à ferramenta certa e são avaliados aqui, e o outro, T-0042, foi primeiro para shop.get_order_status, por isso conta entre as ferramentas erradas. Nenhum modelo consegue ver através de uma digitação sem consultar os pedidos do cliente. Avaliado contra o que o cliente quis dizer, o modelo parece descuidado; avaliado contra o que recebeu, ele é fiel. A lacuna pertence ao fluxo do host, que deveria verificar se um pedido pertence ao cliente do ticket antes de agir sobre ele.

Benchmarks publicados apontam na mesma direção. Um preprint, RAG-MCP, relata que recuperar uma lista restrita de ferramentas antes de o modelo escolher elevou a acurácia de seleção de 13.62% para 43.13% em suas tarefas de benchmark, avaliadas por um modelo que atua como juiz (RAG-MCP). MCP-Bench, com 28 servidores ativos e 250 ferramentas, relata desafios persistentes em tarefas cujas instruções não nomeiam a ferramenta (MCP-Bench). Cada um é um único preprint sobre suas próprias tarefas, e nenhum deles diz algo sobre os números da loja.

Regra prática: Avalie cada execução gravada pela primeira ferramenta por tag, e não apenas no geral, e avalie os argumentos separadamente, contra o que o ticket deu ao modelo e contra a verdade. Trabalhe primeiro nas descrições por trás da maior confusão, grave de novo e compare as pontuações por tag entre as duas gravações. Informe o modelo, o prompt e o conjunto de tickets ao lado de cada pontuação, e nunca compare pontuações de configurações diferentes.

Altere ferramentas sem quebrar clientes

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

O teste de contrato em Verifique schemas como contrato diz quando uma mudança quebra clientes; ele não diz como fazer a mudança. A especificação também não diz. A definição de uma ferramenta não tem campo de depreciação, e nada na revisão fixada marca uma ferramenta como em vias de sair (ferramentas). O que segue é prática: a recomendação do livro, construída a partir de partes que a especificação define, e não um recurso do protocolo.

Há três dessas partes. Um cliente pede mudanças na lista de ferramentas com subscriptions/listen e é avisado sobre cada uma delas nesse stream (assinaturas), como Avise clientes quando um recurso muda mostra para recursos. Um resultado de tools/list traz uma dica de cache, ttlMs, e uma notificação de mudança invalida uma lista em cache que ainda esteja fresca; clientes MAY buscar a lista novamente antes do prazo quando uma chamada falha de um modo que sugere que a ferramenta mudou, por exemplo com um método desconhecido ou parâmetros inválidos (cache). E um erro de execução de ferramenta é o que clientes SHOULD entregar ao modelo para que ele possa se corrigir (ferramentas, "Error Handling"). A partir dessas partes, o livro recomenda este procedimento: adicione a nova ferramenta ao lado da antiga; marque a antiga como "Deprecated: use …" na sua descrição; anuncie a mudança; reduza o TTL enquanto a mudança estiver em andamento; mantenha a ferramenta antiga funcionando durante uma janela; e, depois da janela, responda a ela com um erro de execução que nomeie a substituta.

A loja está substituindo find_orders por find_orders_v2, que também pode filtrar por SKU. Para percorrer as três releases, o script serve as ferramentas do capítulo 3 de Projete ferramentas que um modelo pode usar via Streamable HTTP em loopback, com um TTL de um minuto na lista de ferramentas, e conecta dois clientes: um que escuta mudanças na lista e um que apenas usa cache. A release 2 adiciona find_orders_v2 e reescreve find_orders, e o servidor publica a mudança. A release 3 substitui find_orders por uma função que lança ToolError. Um cliente em memória não serviria aqui, porque o caminho em processo não entrega mudanças de lista (Teste ferramentas em memória).

deprecate-a-tool.py Python 3.12.15 · cryptography 50.0.2 · httpx2 2.16.2 · jsonschema 4.26.0 · mcp 2.3.0 · mcp-types 2.3.0 · pydantic 2.14.3 · pytest 9.2.0 · starlette 1.10.0 · uvicorn 0.54.0 Aprovado
"""Retire find_orders in favour of find_orders_v2 over three releases, watched by a listening client and a cachingclient. The prose's point rests on the caching client's list and on the last line, the error the old name returnsafter the window."""import asynciofrom mcp import Clientfrom mcp.server.caching import CacheHintfrom mcp.server.mcpserver import MCPServerfrom mcp.server.mcpserver.exceptions import ToolErrorfrom mcp.server.subscriptions import InMemorySubscriptionBus, ToolsListChangedfrom lib import confirmations, loopback, shop_toolsfrom lib.testing import shop_api_herebus, tools = InMemorySubscriptionBus(), confirmations.chapter3_tools()server = MCPServer("shop-support", version="0.11.0", tools=list(tools.values()), subscriptions=bus,                   cache_hints={"tools/list": CacheHint(ttl_ms=60_000, scope="public")})   # a minute: short while a change is under wayold = tools["find_orders"]def find_orders_v2(customer_id: shop_tools.CustomerId, sku: shop_tools.Sku | None = None) -> shop_tools.OrderList:    """Search one customer's orders, newest first, optionally only those with one product's SKU."""    found = old.fn(customer_id, limit=50)    return found.model_copy(update={"orders": [o for o in found.orders if sku is None or sku in o.skus]})def retired(customer_id: shop_tools.CustomerId) -> shop_tools.OrderList:    raise ToolError("find_orders was retired. Call find_orders_v2 with the same customer_id.")async def replace_find_orders(fn, description: str) -> None:    server.remove_tool("find_orders")    server.add_tool(fn, name="find_orders", title=old.title, description=description, annotations=old.annotations)    await bus.publish(ToolsListChanged())                     # to every client listening for list changesasync def main() -> None:    with shop_api_here(), loopback.serve(server.streamable_http_app()) as base_url:        async with Client(base_url + "/mcp") as listening, Client(base_url + "/mcp") as cached:            listing, _ = await cached.list_tools(), await listening.list_tools()     # both cache release 1's list            print("release 1:", f"{len(listing.tools)} tools, ttlMs {listing.ttl_ms}")            async with listening.listen(tools_list_changed=True) as changes:   # a stream that carries list-change events                server.add_tool(find_orders_v2)                                       # release 2: the replacement first                await replace_find_orders(old.fn, "Deprecated: use find_orders_v2. " + old.description)                print("event:", type(await anext(changes)).__name__)            print("listening client sees:", ", ".join(t.name for t in (await listening.list_tools()).tools))            print("cached client sees:", ", ".join(t.name for t in (await cached.list_tools()).tools))            during = await cached.call_tool("find_orders", {"customer_id": "C-0127"})            print("find_orders during the window:", "tool error" if during.is_error else "result")            await replace_find_orders(retired, "Retired: use find_orders_v2.")         # release 3: the old name now errors            after = await cached.call_tool("find_orders", {"customer_id": "C-0127"})            print("find_orders after the window:", after.content[0].text)asyncio.run(main())
Saídapython deprecate-a-tool.py
release 1: 5 tools, ttlMs 60000
event: ToolsListChanged
listening client sees: get_order_status, quote_refund, issue_refund, check_stock, find_orders_v2, find_orders
cached client sees: find_orders, get_order_status, quote_refund, issue_refund, check_stock
find_orders during the window: result
find_orders after the window: Error executing tool find_orders: find_orders was retired. Call find_orders_v2 with the same customer_id.

A release 1 listou 5 tools, ttlMs 60000. Quando a release 2 foi publicada, o cliente que escuta recebeu ToolsListChanged. O SDK descarta uma lista em cache antes de entregar ao cliente esse evento (mcp/client/client.py), então a próxima listagem do cliente que escuta mostrou as duas ferramentas: get_order_status, quote_refund, issue_refund, check_stock, find_orders_v2, find_orders.

O cliente que usa cache não ouviu nada e serviu a lista da release 1 a partir do seu cache: find_orders, get_order_status, quote_refund, issue_refund, check_stock. Sua chamada para find_orders durante a janela ainda retornou result. Um modelo por trás de um cliente que usa cache não fica sabendo de find_orders_v2 até que o TTL expire ou que o cliente busque a lista novamente. Por isso o TTL deve ser curto enquanto a mudança estiver em andamento, e por isso a ferramenta antiga precisa continuar funcionando.

Depois da release 3, a chamada do cliente que usa cache para find_orders voltou como um erro de execução a partir do qual o modelo pode agir: "Error executing tool find_orders: find_orders was retired. Call find_orders_v2 with the same customer_id.". Uma ferramenta removida teria produzido, em vez disso, o erro de ferramenta desconhecida do SDK, que informa ao modelo que o nome estava errado, mas não o que chamar (Relate falhas como resultados de ferramenta). O SDK devolve esse erro como erro de execução de ferramenta, embora a especificação trate uma ferramenta desconhecida como erro de protocolo (mcp/server/mcpserver/tools/tool_manager.py; ferramentas, "Error Handling").

A lista do cliente que escuta também mostra um efeito colateral: find_orders foi para o fim. MCPServer lista as ferramentas na ordem em que foram adicionadas, e a troca ao vivo da release, que remove a ferramenta e a adiciona de novo, a move (Cacheie resultados de listagem). Uma ordem diferente muda o início de todo prompt que renderiza a lista, que é justamente o que o cache de prompt de um provedor de modelo compara. Um servidor que reinicia com o código novo lista as ferramentas na ordem em que o seu código as registra. Por isso, adicione as ferramentas novas no fim e deixe as existentes onde estão.

Regra prática: Aposente uma ferramenta em três releases: adicione a substituta e marque a ferramenta antiga como depreciada na sua descrição; mantenha as duas funcionando durante uma janela que você anuncia; e então responda ao nome antigo com um erro de execução que nomeie a substituta. Reduza ttlMs em tools/list enquanto a mudança estiver em andamento, publique uma notificação de mudança de lista em cada release e abra um stream subscriptions/listen em todo host que você controla. Diga no seu changelog que a janela é uma política sua, já que o protocolo não define nenhuma.

O que dá errado em produção

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

As verificações aqui são executadas em um processo, em uma máquina. Em produção, os mesmos sinais vêm de muitas réplicas e clientes, e cada um pode enganar você à sua maneira.

Spans se multiplicam além do que um backend consegue indexar. O SDK nomeia um span de servidor a partir do método e da ferramenta, o que mantém o número de nomes distintos tão pequeno quanto a lista de ferramentas. Um ID de pedido, uma URI de recurso ou um ID de cliente em um nome de span gera um nome para cada valor; por isso, as convenções do MCP mantêm a URI do recurso em um atributo (convenções semânticas do MCP). O sinal é uma conta de rastreamento que cresce com o tráfego, e não com as funcionalidades.

Traces carregam os dados da loja. O SDK não registra argumentos nem resultados de ferramentas em seus spans (mcp/server/_otel.py), e as convenções marcam gen_ai.tool.call.arguments como opt-in (mesma fonte). Os argumentos da loja contêm IDs de clientes e de pedidos, e um argumento diz apenas o que o chamador enviou. Para registrar quem agiu, use o subject do token verificado, que no host de suporte é o funcionário, junto com o cliente do registro do chamado que o servidor verificou (Impeça que o servidor atue como um confused deputy). Adicione argumentos aos spans somente atrás de uma configuração, e mantenha-os fora de qualquer backend que a política de tratamento de dados da loja não cubra.

As convenções mudam sob os seus painéis. As convenções do MCP têm status de Development e já mudaram de repositório uma vez (aviso de mudança), e o middleware do SDK está marcado como provisório (mcp/server/lowlevel/server.py). Uma versão do SDK que renomeia um atributo esvazia um painel sem gerar erro. Mantenha os nomes dos atributos em um único lugar da sua configuração e verifique-os a cada atualização do SDK, como faria com qualquer gatilho de atualização.

Réplicas divergem durante uma implantação. Em uma implantação gradual, uma réplica serve o schema da versão 1 enquanto a seguinte serve o da versão 2, e um cliente que listou em uma e chama a outra recebe o RuntimeError de Verifique schemas como um contrato. O sinal são erros de validação no lado do cliente que aumentam durante a implantação e diminuem quando ela termina. Envie primeiro as mudanças aditivas, e remova a forma antiga somente quando todas as réplicas servirem a nova e a janela de transição tiver passado.

O registro envelhece. Um replay continua passando enquanto o modelo por trás do host de produção muda, de modo que as pontuações da gravação se afastam do que os clientes veem. Grave novamente a cada troca de modelo, como recomenda Trabalhe a fila de chamados, e execute a mesma verificação de promessa sem respaldo em uma amostra das execuções de produção, pois um replay não consegue encontrar uma falha que o modelo gravado nunca cometeu.

Regra prática: Antes de confiar em um trace ou em uma pontuação, verifique o que ele cobre: qual transporte, qual modelo e qual versão de cada schema. Mantenha os nomes de span limitados e os argumentos fora dos spans por padrão, fixe os nomes de atributos usados pelos seus painéis em uma versão nomeada da convenção, e execute o teste de contrato e o replay em cada versão antes que ela chegue a uma réplica.

Decisões tomadas neste capítulo

  • As ferramentas são testadas em memória com Client(server, raise_exceptions=True), verificando campos, com um teste de loopback por transporte para o que o caminho em processo deixa de fora.
  • O pytest roda com o plugin próprio do anyio, e sem inline-snapshot, que o livro não fixa. lib.testing imprime uma linha por teste para que a saída seja estável.
  • Os esquemas da última versão são o contrato. A CI valida novos resultados contra eles com o validador do dialeto declarado por cada esquema, 2020-12 por padrão, e lib.contract compara os esquemas para revisão.
  • A gravação do capítulo 10 em ticket-runs é reproduzida, não gravada de novo. Um RecordingMismatch após uma mudança na descrição significa que é preciso gravar de novo.
  • O host confere as respostas com o seu registro de chamadas. Uma resposta que promete um reembolso sem chamada correspondente vai para uma pessoa; a verificação por palavras-chave em lib.queue_replay é uma regra prática.
  • Os rastros vêm do middleware do SDK, com os atributos que ele emite identificados como uma convenção de status Development, e a propagação é testada sobre HTTP.
  • A escolha de ferramenta é pontuada por tag, e os argumentos à parte, com expected_first_tool, como o capítulo 10 pontua. Os IDs de pedido são pontuados tanto contra o texto do ticket quanto contra o pedido que o cliente quis dizer.
  • As ferramentas são aposentadas em três versões, com um TTL curto e uma mudança na lista a cada uma delas, e um erro de execução que nomeia o substituto após a janela. O procedimento é a prática do livro, não a especificação.

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.

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 11 de 12: Teste um servidor e acompanhe sua execução

  1. Testar ferramentas em memória
  2. Check schemas as a contract
  3. Reproduzir execuções gravadas do host
  4. Trace calls with OpenTelemetry
  5. Meça com que frequência a ferramenta certa é escolhida
  6. Altere ferramentas sem quebrar clientes
  7. O que dá errado em produção
  8. Decisões tomadas neste capítulo

Voltar ao topoTodos os capítulos