Migrar um servidor da era 2025

Cerca de 36 minutos min de leitura, com 6 exemplos em 9 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ê saberá migrar um servidor do Model Context Protocol escrito para as revisões de 2025 e para a linha 1.x do SDK de Python para a especificação na revisão 2026-07-28 e mcp 2.3.0. As afirmações sobre o alvo valem para essa revisão e essa versão do SDK. Você verá do que ele depende, removerá suas sessões, sairá do transporte HTTP+SSE, substituirá sampling, roots, logging e Dynamic Client Registration, portará o código e servirá clientes das duas eras enquanto os antigos ainda existirem.

Todos os capítulos anteriores construíram o servidor da loja, o único caso deste livro, como shop-support para a revisão fixada desde o início. A maioria das equipes não começa assim. Elas têm um servidor que uma equipe da era 2025 escreveu para as revisões 2025-03-26 a 2025-11-25 com o SDK 1.x, e hosts que ainda falam essas revisões. Este capítulo é o único que ensina o protocolo de 2025, e apenas como aquilo de que você migra.

Entre essas revisões e a revisão fixada, o Model Context Protocol (MCP) removeu o handshake initialize e as sessões do protocolo, removeu requisições que um servidor envia ao cliente no meio de uma chamada, e descontinuou cinco funcionalidades e dois valores de um campo de sampling (changelog). O servidor da loja da era 2025 usa a maior parte do que essas revisões removeram ou descontinuaram. A listagem a seguir é esse servidor, como uma equipe o escreveria para mcp==1.30.0:

"""shop-support as a 2025-era team wrote it, for SDK 1.x and revisions up to 2025-11-25."""
import os

from mcp.server.fastmcp import Context, FastMCP
from mcp.server.session import ServerSession
from mcp.types import SamplingMessage, TextContent
from pydantic import BaseModel

import shop_calls                                   # the shop's API, as chapter 3 calls it; not shown

server = FastMCP("shop-support", "Answers the support team's questions about orders, refunds and stock.",
                 port=8000, stateless_http=False)
quotes: dict[ServerSession, dict] = {}              # each connection's open quote

class Release(BaseModel):
    release: bool

@server.tool()
async def quote_refund(order_id: str, ctx: Context) -> dict:
    quotes[ctx.session] = quote = shop_calls.quote(order_id)
    await ctx.info(f"quoted {quote['amount']} for {order_id}")
    return quote

@server.tool()
async def issue_refund(ctx: Context) -> dict:
    quote = quotes.pop(ctx.session)                 # the quote this connection made last
    if not quote["within_limit"]:
        answer = await ctx.elicit(f"Refund {quote['amount']}? It is above the policy limit.", Release)
        if answer.action != "accept" or not answer.data.release:
            return shop_calls.hold(quote)
    return shop_calls.refund(quote)

@server.tool()
async def triage_ticket(text: str, ctx: Context) -> str:
    reply = await ctx.session.create_message(
        [SamplingMessage(role="user", content=TextContent(type="text", text=text))],
        max_tokens=20, system_prompt="Name the one shop tool this ticket needs.")
    return reply.content.text

@server.tool()
async def save_restock_report(ctx: Context) -> str:
    folder = (await ctx.session.list_roots()).roots[0].uri.path
    return shop_calls.write_restock_report(folder)

server.run(transport="sse" if os.environ.get("SHOP_OLD_HOSTS") else "streamable-http")   # HTTP+SSE: the 2024 transport

A listagem é o servidor da loja da era 2025, e um módulo compartilhado deste capítulo, lib.legacy, o guarda como texto, com a configuração de OAuth do host e as regras para localizar cada dependência. Ele é mostrado e analisado, nunca executado. O SDK 1.x e o SDK 2.x são ambos a distribuição mcp, por isso um ambiente comporta apenas um deles, e o ambiente dos exemplos fixa a versão 2.x. Todo exemplo executa o servidor portado na 2.x ou lê a listagem. shop_calls representa as chamadas à API da loja que as ferramentas do capítulo 3 fazem, e a listagem não a mostra.

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

Inventory what the old server depends on

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

A migration starts with a list, because the pinned revision treats each old feature in one of three ways, and each way sets its own deadline. The first group was removed at revision 2026-07-28, with no window: the initialize handshake, protocol sessions and the Mcp-Session-Id header, requests a server sends to the client in the middle of a call, whatever they ask for, the HTTP GET stream, resources/subscribe, ping, logging/setLevel and stream resumability (changelog). A client at the pinned revision never uses any of them, so code that depends on one fails for that client the first time it runs.

The second group is deprecated: roots, sampling, logging, the HTTP+SSE transport and Dynamic Client Registration. The changelog says that roots, sampling and logging stay "fully functional during the deprecation window" (same source), and the specification's registry gives each deprecated feature a migration path and an earliest removal (deprecated features). An earliest removal is the date when a feature becomes eligible to go, not when it goes. Removal is a decision the core maintainers make when they prepare a revision, so a feature may stay deprecated much longer (feature lifecycle). The window runs at least twelve months from the release of the revision that first marks the feature deprecated, and it can be cut to ninety days for an active security risk, so the windows differ from feature to feature. Dropping a feature from the specification doesn't oblige an SDK to drop it, because each SDK's own policy decides (same source).

The third kind isn't a protocol change at all. SDK 2.x renamed and moved parts of the 1.x API, so a 1.x server fails to start on 2.x even where the protocol didn't change (migration guide).

We parse the server listing in this chapter and the host's OAuth setup, shown in Replace dynamic client registration, with Python's ast module, and match each node against lib.legacy.RULES. Each rule names a dependency, its status at the pinned revision, its replacement and, for a deprecated feature, the registry's earliest removal. The scan then prints them grouped by status, with the function each one sits in.

scan-a-2025-server.py Python 3.12.15 Aprovado
"""Sorts the 2025-era server's dependencies, and its host's OAuth setup, into removed, deprecated and SDK changes, eachwith its replacement. The prose's point, that removed dependencies fail for every client at the pinned revision, rests on the first group'scount and the functions it names."""import astfrom lib import legacyfound: dict[str, list[str]] = {rule.feature: [] for rule in legacy.RULES}def where(tree: ast.Module, node: ast.AST, listing: str) -> str:    """The function a node sits in, or the listing's setup when it sits in none."""    for function in ast.walk(tree):        if isinstance(function, ast.AsyncFunctionDef | ast.FunctionDef) and node in ast.walk(function):            return function.name    return f"{listing} setup"                # module-level code, outside every functionfor listing, source in legacy.LISTINGS.items():    tree = ast.parse(source)                   # parsed, never run: SDK 1.x can't install beside 2.x    for node in ast.walk(tree):        for rule in legacy.RULES:            # each function is listed once per feature, however many of its nodes match            if rule.matches(node) and where(tree, node, listing) not in found[rule.feature]:                found[rule.feature].append(where(tree, node, listing))print("written for:", legacy.WRITTEN_FOR)for kind in ("removed", "deprecated", "sdk"):    rules = [rule for rule in legacy.RULES if rule.kind == kind and found[rule.feature]]   # a rule with no match is left out    print(f"{kind} dependencies:", len(rules))    for rule in rules:        print(f"  {rule.feature}: {', '.join(found[rule.feature])} -> {rule.replacement}")        if rule.removal:                          # only deprecated features have a removal date            print(f"  {rule.feature} earliest removal: {rule.removal}")
Saídapython scan-a-2025-server.py
written for: mcp==1.30.0
removed dependencies: 2
  sessions: server setup, quote_refund, issue_refund -> a handle the server mints, passed back as a tool argument
  pushed requests: triage_ticket, issue_refund, save_restock_report -> an input request in a Multi Round-Trip Request
deprecated dependencies: 5
  sampling: triage_ticket -> a model call the host or the server makes itself
  sampling earliest removal: first revision released on or after 2027-07-28
  roots: save_restock_report -> a tool parameter, a resource URI or server configuration
  roots earliest removal: first revision released on or after 2027-07-28
  logging: quote_refund -> stderr on stdio, or OpenTelemetry
  logging earliest removal: first revision released on or after 2027-07-28
  HTTP+SSE transport: server setup -> Streamable HTTP
  HTTP+SSE transport earliest removal: three months after SEP-2596 reaches Final
  dynamic client registration: host setup -> a Client ID Metadata Document
  dynamic client registration earliest removal: first revision released on or after 2027-07-28
sdk dependencies: 3
  FastMCP: server setup -> mcp.server.mcpserver.MCPServer
  positional instructions: server setup -> instructions= by keyword
  transport settings on the constructor: server setup -> arguments to run() or streamable_http_app()

The removed ones come first, because they fail for every client at the pinned revision. The scan found 2 removed dependencies, 5 deprecated ones and 3 SDK changes. The removed dependencies are the sessions that quote_refund and issue_refund share, and the requests that three tools push in the middle of a call: ctx.elicit in issue_refund, create_message in triage_ticket and list_roots in save_restock_report.

So sampling and roots are on both lists. As features they are deprecated, and they keep working through their window: for a 2025-era client as written, and for a client at the pinned revision only when the server asks for them through a round trip, as Replace sampling, roots and logging shows. Pushed mid-call, they fail for that client as ctx.elicit does, with SDK 2.3.0 raising NoBackChannelError (mcp/server/_streamable_http_modern.py). Of sampling, roots and logging, only logging works as written for a client at the pinned revision, and only for a request whose _meta asks for a log level. For any other request the SDK drops the line (mcp/server/connection.py).

Four of the deprecated features share one earliest removal, the first revision released on or after 2027-07-28. The HTTP+SSE transport's date is different, and Move from HTTP+SSE to Streamable HTTP gives it.

The SDK at 2.3.0 doesn't warn about all of these either. Its sampling, roots and logging APIs emit MCPDeprecationWarning, a UserWarning that prints by default (what's new). Its HTTP+SSE app and client and its registration code carry no deprecation marker: we searched mcp/server/sse.py, mcp/client/sse.py, mcp/server/auth/handlers/register.py and mcp/client/auth/oauth2.py for "deprecat" and found nothing. A server can run on 2.x without a single warning and still depend on two deprecated features.

Working rule: Inventory before you change anything, and sort the list by status. Fix every removed dependency before you let a client at the pinned revision connect, because there is no window for it, and count every request the server pushes mid-call as removed, even when the feature it asks for is only deprecated. Give each deprecated one a date of your own, earlier than the registry's earliest removal, and don't wait for warnings: run a scan like this one in CI, because the SDK is silent about some deprecated features.

Remover initialize e os IDs de sessão

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

A varredura em Inventariar do que o servidor antigo depende listou primeiro as sessões. Nas revisões de 2025, uma conexão começava com initialize, e um servidor Streamable HTTP podia atribuir um ID de sessão em sua resposta. Em seguida, o cliente tinha de enviar Mcp-Session-Id em toda requisição, iniciar uma nova sessão quando o servidor respondesse 404 e encerrá-la com DELETE (transportes de 2025-11-25). Um servidor podia manter o que quisesse por sessão.

A revisão fixada remove o handshake e as sessões. Cada requisição leva sua versão do protocolo e as capacidades do cliente em _meta. Um cliente pergunta o que um servidor suporta com server/discover, que todo servidor DEVE implementar, e um servidor que precisa de estado entre chamadas cria um handle explícito e faz o cliente devolvê-lo como um argumento comum da ferramenta (changelog). Levar a versão e as capacidades em toda requisição mostra as chaves de _meta.

O servidor da era 2025 mantém um pedaço de estado por sessão. quote_refund armazena a cotação em ctx.session, o objeto do SDK para a conexão, e issue_refund não recebe argumento e reembolsa a última cotação feita por aquela conexão. Com o SDK 1.x, um único objeto atende todas as requisições de uma conexão (mcp/server/lowlevel/server.py na 1.x), então isso funcionava. Movemos as duas ferramentas para a 2.x sem alterações, ao redor das funções de cotação e reembolso do capítulo 3, e chamamos cada uma uma vez, a partir de um cliente, na revisão fixada. Em seguida, chamamos o servidor do capítulo 3, cujo quote_refund devolve um quote_id que issue_refund recebe, da mesma forma.

stateless-after-migration.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
"""Ports the 2025 server's per-connection quote to SDK 2.x unchanged, then with the handle the pinned revision asks for.The prose's point rests on the session-keyed failure, the count of session objects, and the handle's refund line."""import asyncioimport osfrom mcp import Clientfrom mcp.server.mcpserver import Context, MCPServerfrom mcp.server.mcpserver.exceptions import ToolErrorfrom lib import confirmations, loopback, shop_api, shop_toolschapter3 = confirmations.chapter3_tools()          # quote_refund and issue_refund from lib.shop_toolsserver = MCPServer("shop-support", version="0.12.0")quotes = {}                                        # the 2025 code: each connection's open quote, by its sessionsessions_seen = set()@server.tool(description="Quote a refund for a whole order, for issue_refund to refund.")def quote_refund(order_id: str, ctx: Context) -> str:    sessions_seen.add(id(ctx.session))       # each request gets its own session object at the pinned revision    quotes[ctx.session] = chapter3["quote_refund"].fn(order_id, sku="KG-1050")   # chapter 3's quote needs a SKU; the port pins one    return f"Quoted {quotes[ctx.session].amount}."@server.tool(description="Refund the quote this connection made last.")def issue_refund(ctx: Context) -> shop_tools.Refund:    sessions_seen.add(id(ctx.session))    if ctx.session not in quotes:        raise ToolError("There is no open quote in this session. Call quote_refund first.")    return chapter3["issue_refund"].fn(quotes.pop(ctx.session).quote_id)   # pop: a quote is used onceasync def main() -> None:    with loopback.serve(shop_api.create_app()) as api_url:        os.environ.update(shop_api.server_env(api_url))      # both servers run in this process        with loopback.serve(server.streamable_http_app()) as old, \             loopback.serve(shop_tools.create_server().streamable_http_app()) as new:            async with Client(old + "/mcp") as client:                await client.call_tool("quote_refund", {"order_id": "O-2415"})                print("session-keyed issue_refund:", (await client.call_tool("issue_refund", {})).content[0].text)                print("session objects in two calls:", len(sessions_seen))            async with Client(new + "/mcp") as client:                quote = await client.call_tool("quote_refund", {"order_id": "O-2415", "sku": "KG-1050"})                refund = await client.call_tool("issue_refund", {"quote_id": quote.structured_content["quote_id"]})                print("handle issue_refund:", refund.structured_content["status"], refund.structured_content["amount"])asyncio.run(main())
Saídapython stateless-after-migration.py
session-keyed issue_refund: Error executing tool issue_refund: There is no open quote in this session. Call quote_refund first.
session objects in two calls: 2
handle issue_refund: requested 23.98

Executada sem alterações, a versão migrada falhou na segunda chamada: "Error executing tool issue_refund: There is no open quote in this session. Call quote_refund first." As duas chamadas partiram de um cliente para um mesmo processo, mas viram 2 objetos de sessão diferentes. Na revisão fixada não existe conexão à qual uma sessão possa pertencer, então o SDK dá a cada requisição a sua própria. Nada falhou quando a cotação foi armazenada, e o erro só aparece quando algo a lê de volta. Um servidor que indexasse seu estado pelo cabeçalho Mcp-Session-Id se sairia pior: na revisão fixada nenhum cliente envia esse cabeçalho, então o estado de todos os clientes cairia sob a mesma chave, None.

Com o handle, o reembolso foi concluído: requested 23.98. Este é o desenho que Modelar ferramentas em torno de tarefas, não de endpoints escolheu para o capítulo 3. A orientação da especificação para esses handles é que sejam opacos e expirem, e que um servidor com autenticação verifique a autorização de quem chama em relação ao handle a cada chamada (ferramentas). Impedir que o servidor atue como um deputado confuso vincula os IDs de cotação da loja ao cliente para quem foram emitidos. Um handle na memória de um processo ainda morre com o processo, então, quando o servidor rodar em réplicas, os handles vão para um armazenamento compartilhado, como faz Executar réplicas sem sessões fixas com SQLite.

Regra prática: Procure no servidor antigo cada uso da sessão, o seu ID e tudo o que é armazenado por conexão, e transforme cada pedaço de estado em um handle que uma ferramenta devolve e a seguinte recebe como argumento. Torne o handle opaco, dê a ele uma validade que a descrição da ferramenta que o cria informe, verifique em cada chamada se quem chama pode usá-lo e armazene-o onde todas as réplicas possam lê-lo. Não guarde em um dicionário indexado pela sessão nada de que uma chamada posterior precise, mesmo para clientes da era 2025 que ainda tenham um.

Migração de HTTP+SSE para Streamable HTTP

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

As sessões em Remover initialize e IDs de sessão pertencem à forma de 2025 do Streamable HTTP. Um segundo transporte, mais antigo, ainda está no servidor da loja de 2025: a última linha dele serve HTTP+SSE, o transporte que a revisão 2025-03-26 substituiu, quando SHOP_OLD_HOSTS está definido. Nesse transporte, o cliente mantém um fluxo de eventos aberto em um endpoint e envia suas mensagens a um segundo (Streamable HTTP). O SDK 1.x serve o par em /sse e /messages/ (mcp/server/fastmcp/server.py no 1.x). A revisão 2025-03-26 colocou o Streamable HTTP no lugar dele (changelog de 2025-03-26), e a revisão fixada passa a submetê-lo à política de ciclo de vida, com uma janela mais curta (changelog).

Para o servidor, a migração é uma remoção. O servidor da loja já portado serve streamable_http_app(), ou run(transport="streamable-http"), em um único endpoint, como em Migrar o servidor de stdio para HTTP, e nada nas suas ferramentas muda. Todo cliente na revisão fixada que se conecta por HTTP usa Streamable HTTP, portanto o transporte não é o que os impede. O que decide quando o transporte antigo pode sair são os hosts que ainda se conectam por HTTP+SSE, e eles são, por definição, clientes da era de 2025.

Esses hosts têm duas saídas. Um servidor que precisa mantê-los pode hospedar os endpoints SSE e POST antigos ao lado do seu endpoint Streamable HTTP, o que a especificação permite desde a revisão 2025-03-26 (Streamable HTTP). O SDK 2.3.0 ainda tem MCPServer.sse_app(), com os mesmos dois caminhos do 1.x, e run(transport="sse") (mcp/server/mcpserver/server.py). Como Inventariar do que o servidor antigo depende constatou, nenhum dos dois emite aviso de descontinuação. Ou os hosts migram para Streamable HTTP, que o cliente do SDK 1.x já fala (mcp/client/streamable_http.py no 1.x).

A data de remoção mais cedo para HTTP+SSE no registro é three months after SEP-2596 reaches Final, que talvez já tenha passado. Isso não significa que o SDK deixe de oferecer sse_app() nesse dia, pois cada SDK decide por si (ciclo de vida de funcionalidades). O transporte já estava descontinuado havia mais de um ano quando a SEP-2596 definiu a política de ciclo de vida; por isso, recebeu um período de carência de três meses em vez de doze, e a página da proposta o marca como Final, sem data. A data significa que um host não pode contar com a sobrevivência do transporte na próxima revisão, e você também não.

A equipe de suporte da loja escolheu uma data. Os endpoints antigos permanecem apenas enquanto os logs do servidor mostrarem um host se conectando a /sse, e a equipe informa ao responsável por cada um desses hosts a data em que os endpoints serão desligados. Um host que não consiga migrar até lá pode continuar no SDK 1.x, com uma implantação 1.x do servidor antigo, o que é tratado em Portar o código do SDK 1.x para o 2.x.

Regra prática: Remova o transporte HTTP+SSE do servidor em vez de portá-lo, a menos que seus logs mostrem hosts que ainda o usam. Se usarem, sirva os endpoints antigos ao lado do endpoint Streamable HTTP, registre cada conexão a eles por cliente e defina uma data para removê-los, que você comunica ao responsável por cada host. Trate o transporte como já elegível para remoção, porque a janela dele foi de três meses, não de doze.

Substituir sampling, roots e logging

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

Três das dependências que Inventariar do que o servidor antigo depende encontrou têm duas mudanças empilhadas, e vale separá-las. A primeira é um mecanismo. Um servidor de 2025 enviava sua própria requisição ao cliente no meio de uma chamada (elicitation/create, sampling/createMessage, roots/list) e aguardava a resposta. A revisão fixada diz que esse padrão "não é mais suportado" e que se trata de uma mudança incompatível. Um servidor agora pede por meio de uma Requisição Multi Round-Trip, retornando uma requisição de entrada cujos valores podem ser um ElicitRequest, um CreateMessageRequest ou um ListRootsRequest (Requisições Multi Round-Trip). A segunda são as próprias funcionalidades. Roots, sampling e logging estão descontinuados, com caminhos de migração no registro: roots para parâmetros de ferramentas, URIs de recursos ou configuração do servidor; sampling para integração direta com a API de um provedor de modelos; logging para stderr no stdio, ou OpenTelemetry (funcionalidades descontinuadas).

Portanto, uma Requisição Multi Round-Trip substitui o envio, não o sampling. Um servidor que move seu sampling/createMessage para uma requisição de entrada continua dependendo de uma funcionalidade descontinuada. A elicitation é a única das três que não está descontinuada, por isso é a única que vale a pena mover para a ida e volta e manter.

O issue_refund da era de 2025 envia sua confirmação com ctx.elicit, o que falha na revisão fixada, como Veja por que um servidor sem estado não pode esperar uma resposta mostrou. A migração pede por meio de um resolvedor. Um parâmetro declarado como Annotated[Release, Resolve(confirm)] é preenchido executando confirm antes da ferramenta, e quando confirm retorna Elicit(...), o SDK pergunta à pessoa no host (Peça entrada estruturada com elicitation). confirm pergunta somente quando a API da loja mantém o reembolso para confirmação. Tomamos o pedido O-2289 como exemplo, cujo reembolso está acima do limite da política. Chamamos issue_refund uma vez manualmente para ver a primeira rodada, e então deixamos Client executar as rodadas com o líder de equipe roteirizado do capítulo 5, que diz sim.

replace-pushed-requests.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
"""Ports the 2025 server's pushed confirmation to a resolver that serves both eras, and its log line to stderr. The prose'spoint rests on the first round's result and the question it asks, and the refund's status after the lead's yes."""import asyncioimport loggingimport osfrom typing import Annotatedfrom mcp import Clientfrom mcp.server.mcpserver import Elicit, Resolvefrom pydantic import BaseModelfrom lib import confirmations, loopback, shop_api, shop_toolsserver, held = confirmations.shop_server(version="0.12.0")   # chapter 3's other tools; held is its issue_refundlog = logging.getLogger("shop-support")                       # to stderr, not to the clientclass Release(BaseModel):    release: booldef confirm(quote_id: confirmations.QuoteId) -> Elicit[Release] | Release:    refund = held.fn(quote_id)                                # the same quote always gives the same refund    if refund.status != "needs_confirmation":        return Release(release=False)                         # nothing held, so nothing to ask    # returning Elicit asks the person at the host; the SDK sends the question in the client's form    return Elicit(f"Refund {refund.amount} on order {refund.order_id}? It is above the policy limit.", Release)@server.tool(description=shop_tools.DESCRIPTIONS["issue_refund"], annotations=held.annotations)def issue_refund(quote_id: confirmations.QuoteId, answer: Annotated[Release, Resolve(confirm)]) -> shop_tools.Refund:    refund = held.fn(quote_id)    if refund.status == "needs_confirmation" and answer.release:        refund = confirmations.release(refund)    log.info("refund %s is %s", refund.refund_id, refund.status)    return refundasync def main() -> None:    with loopback.serve(shop_api.create_app()) as api_url:        os.environ.update(shop_api.server_env(api_url))      # the server runs in this process        with loopback.serve(server.streamable_http_app()) as url:            async with Client(url + "/mcp", elicitation_callback=confirmations.say_yes) as client:                quote = (await client.call_tool("quote_refund", {"order_id": "O-2289"})).structured_content                first = await client.session.call_tool("issue_refund", {"quote_id": quote["quote_id"]},                                                        allow_input_required=True)   # returns the input request, not an answer                print("first round:", first.result_type)                print("first round asks:", ", ".join(r.method for r in first.input_requests.values()))                refund = await client.call_tool("issue_refund", {"quote_id": quote["quote_id"]})   # Client answers with the lead's yes                print("refund after the lead's yes:", refund.structured_content["status"])asyncio.run(main())
Saídapython replace-pushed-requests.py
first round: input_required
first round asks: elicitation/create
refund after the lead's yes: requested

A primeira rodada voltou como input_required, com uma pergunta, elicitation/create: a mesma requisição que o servidor de 2025 enviava, agora carregada em um resultado. Depois do sim do líder de equipe, o status do reembolso foi requested. O resolvedor também funciona para clientes da era de 2025, porque o SDK envia suas perguntas na forma que a revisão do cliente usa (mcp/server/mcpserver/resolve.py). Atenda clientes antigos e novos durante a janela executa os dois casos.

A linha de log da migração usa o logging do Python, não o ctx.info. O MCPServer configura o logging para stderr quando é construído (mcp/server/mcpserver/utilities/logging.py), então a linha vai para os logs do próprio servidor e nunca para o cliente. No stdio, o stdout carrega apenas as mensagens do protocolo, e o stderr é onde devem ficar os logs de um servidor (stdio). Rastreie chamadas com OpenTelemetry cobre o outro caminho.

O sampling sai por completo. O triage_ticket da era de 2025 pedia ao modelo do host, por meio de sampling, qual ferramenta um ticket precisa, e a migração remove essa ferramenta. O modelo do próprio host já lê todos os tickets e escolhe as ferramentas (Trabalhe a fila de tickets), então o servidor estava pedindo ao host que fizesse o que o host já faz. Um servidor que precisa de um modelo para o próprio trabalho chama um provedor de modelos com credenciais próprias, o que também lhe permite escolher e pagar pelo modelo.

save_restock_report pedia ao cliente seus roots e gravava no primeiro deles. Sua migração recebe a pasta como parâmetro e a verifica contra as pastas que a configuração do servidor permite, em SHOP_EXPORT_DIRS, depois de resolver o caminho, para que .. não consiga sair dali.

roots-to-a-parameter.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
"""Replaces the 2025 server's roots with a folder parameter that the server checks against its own allow-list. The prose'spoint rests on the two export lines: the allowed folder saves, and the path that climbs out is refused."""import asyncioimport osfrom pathlib import Pathfrom mcp import Clientfrom mcp.server.mcpserver import MCPServerfrom mcp.server.mcpserver.exceptions import ToolErrorfrom lib import loopback, restock, shop_apiserver = MCPServer("shop-support", version="0.12.0")EXPORT_DIRS = [Path(d).resolve() for d in os.environ.get("SHOP_EXPORT_DIRS", "exports").split(",")]   # the allow-list; a relative entry resolves from the working directory@server.tool(description="Recount stock and save the restock report as CSV in export_dir, a folder the server allows.")async def save_restock_report(export_dir: str) -> str:    folder = Path(export_dir).resolve()                  # "exports/../private" resolves outside exports    if folder not in EXPORT_DIRS:            # an exact match, so a subfolder of an allowed folder is refused too        raise ToolError(f"{export_dir} isn't an export folder. Use one of: {', '.join(d.name for d in EXPORT_DIRS)}.")    report = await restock.run(below=30, seconds=0)   # reports SKUs under 30 units; seconds=0 skips the per-SKU wait    folder.mkdir(exist_ok=True)    (folder / "restock.csv").write_text("sku,units\n" + "".join(f"{r.sku},{r.units}\n" for r in report.reorder))    return f"Saved {len(report.reorder)} products to reorder in {export_dir}/restock.csv."async def main() -> None:    with loopback.serve(shop_api.create_app()) as api_url:        os.environ.update(shop_api.server_env(api_url))      # the server runs in this process        async with Client(server) as client:            for folder in ("exports", "exports/../private"):                saved = await client.call_tool("save_restock_report", {"export_dir": folder})                print(f"export to {folder}:", saved.content[0].text)asyncio.run(main())
Saídapython roots-to-a-parameter.py
export to exports: Saved 5 products to reorder in exports/restock.csv.
export to exports/../private: Error executing tool save_restock_report: exports/../private isn't an export folder. Use one of: exports.

A pasta permitida funcionou: "Saved 5 products to reorder in exports/restock.csv." O caminho que sai da pasta não funcionou: "Error executing tool save_restock_report: exports/../private isn't an export folder. Use one of: exports." Agora o host ou o modelo passa a pasta, e o servidor, não o cliente, decide onde ele pode gravar.

Regra prática: Mova cada elicitation enviada para um resolvedor, que atende às duas eras. Remova o sampling em vez de movê-lo: deixe o modelo do host fazer o trabalho de modelo, ou chame um provedor a partir do servidor com as credenciais próprias do servidor. Transforme roots em um parâmetro verificado contra uma lista de permissões na configuração do servidor, e envie as linhas de log para o stderr e para seus rastreamentos, nunca para o cliente.

Substitua o registro dinâmico de cliente

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

A última dependência descontinuada que o inventário encontrou está no host, não no servidor, mas ela decide se o host da equipe de suporte consegue obter um token para o servidor portado. O host de 2025 registrava-se em cada servidor de autorização que encontrava, por meio do Registro Dinâmico de Cliente do OAuth (OAuth Dynamic Client Registration):

"""How the support team's 2025 host got tokens for shop-support: it registered itself with each authorization server."""
from mcp.client.auth import OAuthClientProvider
from mcp.shared.auth import OAuthClientMetadata

auth = OAuthClientProvider(
    server_url="https://mcp.fernhill.example/mcp",
    client_metadata=OAuthClientMetadata(client_name="Support desk", redirect_uris=["http://127.0.0.1:3030/callback"]),
    storage=token_store, redirect_handler=open_browser, callback_handler=wait_for_code,
)

O OAuthClientProvider do SDK 1.x registra-se dessa forma quando não recebe um client_metadata_url (mcp/client/auth/oauth2.py na 1.x). A revisão fixada descontinua o Registro Dinâmico de Cliente em favor dos Documentos de Metadados do ID de Cliente, que a revisão 2025-11-25 já recomendava, e o mantém por compatibilidade com versões anteriores (registro de mudanças; registro de mudanças de 2025-11-25). A data mais próxima possível para a remoção é first revision released on or after 2027-07-28.

Um Documento de Metadados do ID de Cliente torna o ID do cliente uma URL que começa com https://, em que o host publica os próprios metadados, de modo que nenhum servidor de autorização precise registrá-lo antes. Identifique o cliente com um documento de metadados constrói um para o host da loja e mostra a ordem em que a revisão fixada classifica as opções: credenciais pré-registradas, depois um documento de metadados e, por último, o registro.

A portabilidade depende de um único argumento. O host passa a URL do seu documento como client_metadata_url, e o OAuthClientProvider do SDK 2.x então usa o documento quando o servidor de autorização anuncia client_id_metadata_document_supported. Quando o servidor não anuncia, o provedor recorre ao registro sem avisar, como mostrou o exemplo do capítulo 8, e o código de registro do SDK na versão 2.3.0 (mantido) não emite nenhum aviso de descontinuação. Portanto, o servidor de autorização é metade da portabilidade. Ele precisa anunciar suporte a documentos de metadados e deve manter seu endpoint de registro apenas pelo período de transição e apenas para os hosts que não conseguem publicar um documento.

Duas regras da revisão fixada importam enquanto o registro continua em uso. Um cliente DEVE indexar as credenciais que armazena pelo emissor do servidor de autorização e registrar-se novamente quando o servidor de autorização mudar (registro de mudanças; registro de cliente). Um cliente que se registra DEVE enviar um application_type apropriado, que DEVERIA ser native para um host que roda na máquina do usuário com um redirecionamento loopback, como este (registro de mudanças; registro de cliente). Um host de 2025 que armazenava um ID de cliente por URL de servidor MCP quebra a primeira regra no dia em que a loja mudar seu servidor de autorização.

Regra prática: Publique um Documento de Metadados do ID de Cliente para cada host e passe a URL dele como client_metadata_url. Faça com que todo servidor de autorização que você opera anuncie suporte a ele, mantenha o endpoint de registro somente até que os hosts que precisam dele tenham migrado, e registre qual tipo de ID de cliente foi emitido para cada token, para que você possa ver quando o tráfego de registro tiver cessado.

Portar o código do SDK 1.x para o 2.x

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

As seções anteriores mudaram o que o servidor da loja faz. As mudanças no SDK que Inventariar do que o servidor antigo depende encontrou formam um trabalho à parte, e elas impedem o arquivo antigo de iniciar no 2.x. Dois fatos moldam esse trabalho. O primeiro é que a linha 1.x continua mantida. A primeira versão 2.x e uma versão 1.x foram publicadas em 2026-07-28, o dia da revisão fixada, e a versão 1.x de 2026-09-07, mcp==1.30.0, é uma "versão de manutenção da linha 1.x" (PyPI; notas de lançamento). O guia de migração diz que a linha 1.x continua recebendo correções críticas de bugs e patches de segurança, e ninguém publicou uma data de encerramento (guia de migração). O segundo fato é que as duas linhas são a mesma distribuição mcp, então uma implantação executa uma ou outra, nunca as duas.

O guia lista as quebras de compatibilidade. Entre as que afetam um servidor como o da loja: mcp.server.fastmcp.FastMCP é mcp.server.mcpserver.MCPServer; McpError é MCPError(code, message, data); os campos usam snake_case (input_schema, is_error); o cliente HTTP é httpx2, não httpx; streamablehttp_client foi removido, em favor de streamable_http_client; host, port, stateless_http e json_response passaram do construtor para run() e streamable_http_app(); instructions não é mais o segundo argumento posicional; as variáveis de ambiente MCP_* não são mais lidas; o transporte WebSocket foi removido; e ctx.log recebe data, não message (guia de migração).

A maioria delas falha de forma ruidosa, que é o tipo de falha que você quer. Uma delas não falha. Executamos as linhas de configuração do servidor da era 2025 em 2.3.0 e observamos o import, a exceção que ele levanta e o construtor. Depois construímos o servidor duas vezes, uma com os argumentos como estão escritos e outra portado, e perguntamos a cada um o que um cliente vê.

port-to-sdk-2.py Python 3.12.15 · mcp 2.3.0 Aprovado
"""Tries the 2025 server's setup lines on SDK 2.x: two breaks fail with an error, and one fails silently. The prose's point,that the second positional argument now sets the title, rests on the two title and instructions lines a client sees."""import asynciofrom mcp import Clientfrom mcp.server.mcpserver import MCPServerINSTRUCTIONS = "Answers the support team's questions about orders, refunds and stock."try:    from mcp.server.fastmcp import FastMCP          # the 2025 server's first importexcept ModuleNotFoundError as error:    print("import FastMCP:", str(error).split(". ", 1)[1].split("; see")[0])   # the message after its first sentencetry:    from mcp.shared.exceptions import McpError      # what 1.x tools raised for protocol errorsexcept ImportError as error:    print("import McpError:", str(error).split(" (")[0])   # drops the parentheticaltry:    MCPServer("shop-support", instructions=INSTRUCTIONS, port=8000, stateless_http=False)   # port and stateless_http moved to run() and streamable_http_app() in 2.xexcept TypeError as error:    print("port on the constructor:", error)as_written = MCPServer("shop-support", INSTRUCTIONS)                     # 1.x's second argument was instructionsported = MCPServer("shop-support", instructions=INSTRUCTIONS, version="0.12.0")   # a keyword, so the string can't become the titleasync def main() -> None:    for label, server in (("as written", as_written), ("ported", ported)):        async with Client(server) as client:            print(f"{label} title:", client.server_info.title)            print(f"{label} instructions:", client.instructions)asyncio.run(main())
Saídapython port-to-sdk-2.py
import FastMCP: This is mcp 2.x, where FastMCP was renamed to MCPServer (from mcp.server.mcpserver import MCPServer) and other APIs changed
import McpError: cannot import name 'McpError' from 'mcp.shared.exceptions'
port on the constructor: MCPServer.__init__() got an unexpected keyword argument 'port'
as written title: Answers the support team's questions about orders, refunds and stock.
as written instructions: None
ported title: None
ported instructions: Answers the support team's questions about orders, refunds and stock.

O import falhou com uma mensagem que informa o renomeio e o import a usar no lugar: "This is mcp 2.x, where FastMCP was renamed to MCPServer (from mcp.server.mcpserver import MCPServer) and other APIs changed" (mcp/server/fastmcp.py, que existe apenas para levantar essa exceção). McpError falhou com "cannot import name 'McpError' from 'mcp.shared.exceptions'", e o construtor com "MCPServer.init() got an unexpected keyword argument 'port'". Cada mensagem aponta a linha a ser alterada.

O construtor como escrito não falhou. No 2.x, o segundo argumento posicional é title (mcp/server/mcpserver/server.py), então as instruções do servidor se tornaram o seu título. Um cliente viu o título "Answers the support team's questions about orders, refunds and stock." e nenhuma instrução (None), e um host que coloca as instruções de um servidor no contexto do modelo perderia essas instruções silenciosamente. Com instructions= passado por nome, o título do servidor portado passa a ser None e as instruções chegam. O número da porta passa para a última linha, como server.run(transport="streamable-http", port=8000).

As quebras silenciosas têm um traço em comum: um argumento que ainda passa na verificação de tipos, ou uma configuração que ninguém lê, como as variáveis de ambiente MCP_*. Encontre-as confrontando a lista do guia com o código, e não esperando por erros, e verifique o que um cliente vê com um teste como o que constrói o servidor duas vezes.

Regra prática: Mantenha um servidor da era 2025 fixado em mcp<2 até que a migração passe nos testes, depois faça a migração em uma única alteração: os imports e renomeações que os erros apontam, depois cada quebra silenciosa do guia de migração, verificada com um teste contra o que um cliente vê. Depois, fixe a versão 2.x exatamente, e trate cada versão 2.x como uma mudança a ser testada, já que os avisos e padrões do SDK mudam entre as versões.

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

Serve old and new clients through the window

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

The ported server from Replace sampling, roots and logging answers clients at the pinned revision. The support team's hosts don't all move on one day, and a 2025-era host can't move forward on its own: it sends initialize and expects an answer. The pinned revision allows a dual-era server, which serves both eras on the same endpoint. An initialize request selects the 2025 semantics for that process on stdio or that session on HTTP, and a request with the pinned revision's _meta is served statelessly. A server that serves only the pinned revision SHOULD name the versions it supports in its error to initialize, because a 2025 client can't discover them any other way (versioning). On the other side, a 2.x Client in its default mode tries server/discover first and falls back to initialize (mcp/client/_probe.py; Call the tool from a client).

At 2.3.0, MCPServer.streamable_http_app() is dual-era with nothing to configure. It reads each request's MCP-Protocol-Version header: a request with no header, or with a version from 2024-11-05 to 2025-11-25, goes to the 2025 handler with its sessions, and anything else goes to the stateless handler (mcp/server/streamable_http_manager.py). The 2025 path keeps its sessions in the memory of the process that made them, so 2025-era clients keep their stickiness requirements (what's new).

We serve the ported server's app as replica a, recorded with chapter 6's lib.wire.record_http, and a second copy of it as replica b. A client in the default mode and a client in mode="legacy", which speaks the 2025 handshake, each quote a refund above the policy's limit and issue it on replica a, with the scripted lead saying yes. Then we send the 2025 client's session ID to each replica.

serve-two-revisions.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
"""Serves the ported refund confirmation from one app to a 2026-07-28 client and a 2025-11-25 client, then sends the 2025client's session ID to a second replica. The prose's point rests on the two "question came as" lines (one resolver, twoforms), the two refund lines, and the two session lines: the replica that made the session answers, and the other returns a 404."""import asyncioimport osimport httpx2from mcp import Clientfrom lib import confirmations, http_mcp, loopback, shop_api, wireLEGACY = {"MCP-Protocol-Version": "2025-11-25", "Accept": "application/json, text/event-stream"}   # a 2025 version routes to the 2025 handlerdef asked_how(exchanges: list[dict]) -> str:    messages = [m for e in exchanges for m in e["messages"]]    if any(m.get("method") == "elicitation/create" for m in messages):        return "a request the server pushed mid-call"    return "an input request in a result" if any(m.get("result", {}).get("resultType") == "input_required"                                                 for m in messages) else "never"async def main() -> None:    server = http_mcp.load_server("replace-pushed-requests.py")     # the ported issue_refund, with its resolver    with loopback.serve(shop_api.create_app()) as api_url:        os.environ.update(shop_api.server_env(api_url))        with loopback.serve(wire.record_http(server.streamable_http_app(), "a.jsonl")) as a, \             loopback.serve(http_mcp.load_server("replace-pushed-requests.py").streamable_http_app()) as b:            for mode, order in (("auto", "O-2289"), ("legacy", "O-1085")):     # both above the policy limit                seen = len(wire.read_http_trace("a.jsonl"))   # this client's exchanges come after this count                async with Client(a + "/mcp", mode=mode, elicitation_callback=confirmations.say_yes) as client:                    quote = (await client.call_tool("quote_refund", {"order_id": order})).structured_content                    refund = await client.call_tool("issue_refund", {"quote_id": quote["quote_id"]})                    # the first response from this client that set a session ID                    session = next((e["response_headers"]["mcp-session-id"] for e in wire.read_http_trace("a.jsonl")                                    [seen:] if "mcp-session-id" in e["response_headers"]), None)                    print(f"{mode} revision:", client.protocol_version)                    print(f"{mode} session header:", "set" if session else "none")                    for replica, url in (("a", a), ("b", b)) if session else ():   # no session, nothing to send                        sent = httpx2.post(url + "/mcp", headers={"Mcp-Session-Id": session, **LEGACY},                                           json={"jsonrpc": "2.0", "id": 9, "method": "tools/list"})                        listed = "tools listed" if "check_stock" in sent.text else sent.json()["error"]["message"]                        print(f"2025 session on replica {replica}: HTTP {sent.status_code},", listed)                print(f"{mode} question came as:", asked_how(wire.read_http_trace("a.jsonl")[seen:]))  # this client's exchanges, as replica a logged them                print(f"{mode} refund:", refund.structured_content["status"])asyncio.run(main())
Saídapython serve-two-revisions.py
auto revision: 2026-07-28
auto session header: none
auto question came as: an input request in a result
auto refund: requested
legacy revision: 2025-11-25
legacy session header: set
2025 session on replica a: HTTP 200, tools listed
2025 session on replica b: HTTP 404, Session not found
legacy question came as: a request the server pushed mid-call
legacy refund: requested

The default client settled on 2026-07-28, got no session header (none), and its question came as an input request in a result. Its refund ended requested.

The 2025 client settled on 2025-11-25, got a session header (set), and its question came as a request the server pushed mid-call. Its refund ended requested, and so did the default client's.

One resolver served both eras, and no code in issue_refund checks which one it is in. That is simpler than the ctx.protocol_version check around ctx.elicit() that See why a stateless server can't wait for an answer allows. A hand-built input request, like chapter 5's, doesn't serve both: a 2025 client receives it as an invalid result (What goes wrong in production in chapter 5).

The 2025 session worked on replica a, which answered HTTP 200, tools listed, and failed on replica b, which answered HTTP 404, Session not found. A 2026 client has no session to lose. What it needs from replicas is handles they all reach, as Run replicas without sticky sessions showed. Behind a load balancer, then, 2025-era traffic needs routing by Mcp-Session-Id to the replica that made the session, while the rest goes anywhere. The SDK's other choice, stateless_http=True, removes the sessions for 2025 clients but takes away their cancellation and their server-to-client requests (What goes wrong in production in chapter 6). For the shop that would break the pushed confirmation that the 2025 client had answered, so we recommend sticky routing for the 2025 path, kept as small as the remaining clients allow.

Working rule: Serve both eras from one streamable_http_app() through the window, write every question a tool asks as a resolver, and route requests that carry Mcp-Session-Id to the replica that minted it. Count requests by era. When the 2025 count has stayed at zero for as long as your slowest host takes to upgrade, serve the pinned revision only, and answer initialize with an error that names the versions you support, as the specification asks.

O que dá errado em produção

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

Uma migração falha nas lacunas entre as duas eras: um cliente enxerga o servidor antigo, um proxy enxerga o novo, e um aviso não diz nada. Estas são as falhas que você deve observar.

Uma sessão de 2025 cai em outra réplica. O sinal é 404 com "Session not found" apenas de clientes da era de 2025, após uma implantação ou um aumento de escala, como na réplica b em Atenda clientes antigos e novos durante a janela. Um cliente de 2025 que segue a sua revisão inicia uma nova sessão ao receber 404 (transportes de 2025-11-25), de modo que o sintoma pode ser perda de estado em vez de erro. Roteie por Mcp-Session-Id e conte os 404 por cliente.

Um proxy descarta o cabeçalho de versão. O app do SDK escolhe a era apenas a partir de MCP-Protocol-Version, e o seu código-fonte marca o roteamento pelo corpo como uma etapa posterior (mcp/server/streamable_http_manager.py). Um proxy que remove cabeçalhos que não conhece envia um request da era de 2026 pelo caminho de 2025, que espera primeiro um handshake. O sinal são falhas apenas de clientes na revisão fixada atrás desse proxy. Faça todo proxy repassar os cabeçalhos MCP, como listados em Leia uma troca HTTP.

Os códigos de erro mudaram. Um recurso ausente é -32602 na revisão fixada, e não -32002, embora os clientes DEVAM ainda aceitar -32002 (recursos). A revisão acrescenta -32020 para cabeçalhos que divergem do corpo, -32021 para uma capacidade ausente do cliente e -32022 para uma versão de protocolo não suportada (changelog). Um host que ramifica pelos códigos antigos trata como desconhecidos os códigos que a revisão fixada acrescentou. Pesquise o código dos clientes por cada código numérico antes de o servidor migrar.

Avisos que ensinam as pessoas a ignorar avisos. MCPDeprecationWarning é um UserWarning, por isso é exibido por padrão (novidades), e um servidor que ainda usa sampling, roots ou logging o grava em seus logs. Desligado em bloco, ele também oculta a próxima depreciação. Filtre cada aviso pela sua mensagem somente quando o recurso já estiver no seu inventário, com uma data.

Silêncio sobre HTTP+SSE e registro. O SDK na versão 2.3.0 não avisa sobre nenhum dos dois, como o inventário constatou. Um servidor pode passar em seus testes sem avisos e ainda perder seus hosts mais antigos quando o transporte for desativado. Mantenha a varredura de Inventarie aquilo de que o servidor antigo depende no CI, e trate uma versão posterior do SDK que acrescente esses avisos como motivo para revisar as datas.

Ler a remoção mais antecipada como data final. Uma equipe que planeja abandonar sampling ou roots em 2027-07-28 não tem margem, porque a primeira revisão lançada em ou após essa data pode removê-los. Uma equipe que lê a data como o dia em que eles desaparecem também pode descartar um recurso que o seu SDK continua suportando por mais tempo. Planeje de acordo com os clientes que você atende: o registro fornece a data mais antecipada, e os seus logs fornecem a real.

Regra prática: Comprove a migração pelo caminho real do proxy antes de ela receber tráfego, com quatro testes: um cliente de 2025 completa uma confirmação, um cliente de 2026 completa a mesma, uma sessão de 2025 sobrevive a uma implantação, e o cabeçalho de versão chega ao servidor. Em seguida, acompanhe os requests por era, os 404 por cliente e cada aviso de depreciação, até que a contagem de 2025 chegue a zero.

Decisões tomadas neste capítulo

  • O servidor da era de 2025 é uma listagem, não um exemplo em execução. lib.legacy o mantém como texto para o SDK 1.x, e os exemplos executam apenas a porta para a versão 2.x, porque um único ambiente não comporta as duas linhas.
  • O inventário separa as dependências em removidas, descontinuadas e mudanças do SDK, com a remoção mais antiga prevista no registro para cada recurso descontinuado, lida como a data mais antiga, nunca como data de encerramento.
  • A varredura roda no CI durante toda a janela, porque o SDK emite alertas sobre amostragem, roots e logging, mas não sobre HTTP+SSE nem sobre registro.
  • O estado por sessão passa a ser identificadores: a cotação é o quote_id do capítulo 3, devolvido pelo cliente e armazenado onde todas as réplicas o leem.
  • O HTTP+SSE é removido. O servidor da loja atende apenas Streamable HTTP e mantém os endpoints antigos somente enquanto seus logs mostrarem algum host que os utiliza.
  • A elicitação passa para um resolvedor, que atende às duas eras. A amostragem é excluída: o modelo do host faz a triagem dos chamados. Os roots tornam-se o parâmetro export_dir, verificado contra SHOP_EXPORT_DIRS. O logging passa a ir para stderr e para os traces.
  • O host usa um Client ID Metadata Document por meio de client_metadata_url, e os servidores de autorização mantêm o registro apenas para hosts que não conseguem publicar um.
  • A migração para a versão 2.x é uma única mudança, protegida por mcp<2 até que os testes passem, com instructions= por palavra-chave e as configurações de transporte em run().
  • Um único aplicativo de dupla era atende às duas eras durante a janela, com roteamento fixo por Mcp-Session-Id para o tráfego de 2025 e sem stateless_http.

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 12 de 12: Migrar um servidor da era 2025

  1. Inventory what the old server depends on
  2. Remover initialize e os IDs de sessão
  3. Migração de HTTP+SSE para Streamable HTTP
  4. Substituir sampling, roots e logging
  5. Substitua o registro dinâmico de cliente
  6. Portar o código do SDK 1.x para o 2.x
  7. Serve old and new clients through the window
  8. O que dá errado em produção
  9. Decisões tomadas neste capítulo

Voltar ao topoTodos os capítulos