2025년형 서버 이전하기

읽는 데 약 66분분 걸린다, 9절에 6개 예제이(가) 있음.

2026.11.14판 예제 통과 2026년 11월 19 70개 예제 중 70개 통과 변경 사항

AI로 번역함. 영어 원문을 사람이 검증함. 우리가 책을 만드는 방식

영어판 2026.11.14판을 번역한 것이다. 원문 읽기

이 장을 마치면 2025년 개정판들과 Python SDK의 1.x 계열에 맞춰 작성한 Model Context Protocol 서버를 사양의 2026-07-28 개정판과 mcp 2.3.0로 옮길 수 있다. 목표에 관한 설명은 모두 그 개정판과 SDK 버전에서 성립한다. 서버가 무엇에 의존하는지 찾아내고, 세션을 제거하고, HTTP+SSE 전송에서 벗어나게 하고, 샘플링, 루트, 로깅, 동적 클라이언트 등록을 대체하고, 코드를 이식한다. 그리고 옛 클라이언트가 남아 있는 동안 두 시대의 클라이언트를 모두 지원한다.

앞의 모든 장은 이 책의 유일한 사례인 상점의 서버를 처음부터 고정된 개정판에 맞춘 shop-support로 만들었다. 대부분의 팀은 거기서 시작하지 않는다. 이들에게는 2025년의 팀이 2025-03-26부터 2025-11-25까지의 개정판과 SDK 1.x에 맞춰 작성한 서버가 있고, 그 개정판들을 아직 사용하는 호스트가 있다. 이 장은 2025년 프로토콜을 가르치는 유일한 장이며, 이전해 나갈 출발점으로서만 다룬다.

그 개정판들과 고정된 개정판 사이에서 Model Context Protocol(MCP)은 initialize 핸드셰이크와 프로토콜 세션을 없앴고, 서버가 호출 도중에 클라이언트로 밀어 보내는 요청을 없앴으며, 다섯 가지 기능과 샘플링 필드 하나의 값 두 개를 폐기 예정으로 두었다(변경 기록). 상점의 2025년형 서버는 그 개정판들이 없애거나 폐기 예정으로 둔 것을 대부분 사용한다. 이어지는 목록은 팀이 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

이 목록은 2025년형 상점 서버이며, 이 장의 공유 모듈 lib.legacy이 호스트의 OAuth 설정과 각 의존성을 찾는 규칙과 함께 이를 텍스트로 담고 있다. 목록은 보여 주고 검사할 뿐 실행하지 않는다. SDK 1.x와 SDK 2.x는 둘 다 mcp 배포판이므로 한 환경에는 둘 중 하나만 설치할 수 있고, 예제의 환경은 2.x에 고정되어 있다. 모든 예제는 이식한 서버를 2.x에서 실행하거나 목록을 읽는다. shop_calls는 3장의 도구들이 상점의 API에 보내는 호출을 나타내며, 목록에는 나오지 않는다.

이 부분은 아직 번역되지 않았으므로 영어로 표시된다.

Inventory what the old server depends on

마지막으로 변경된 판: 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 통과
"""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}")
출력python 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.

initialize와 세션 ID 제거하기

마지막으로 변경된 판: 2026.11.11판

이전 서버가 의존하는 것 조사하기의 점검에서는 세션을 가장 먼저 꼽았다. 2025년 개정판에서 연결은 initialize로 시작했고, Streamable HTTP 서버는 응답에 세션 ID를 지정할 수 있었다. 그러면 클라이언트는 모든 요청에 Mcp-Session-Id를 보내야 했고, 서버가 404로 응답하면 새 세션을 시작해야 했으며, 세션을 끝낼 때는 DELETE를 보내야 했다(2025-11-25 전송 방식). 서버는 세션마다 원하는 것을 무엇이든 보관할 수 있었다.

고정한 개정판은 핸드셰이크와 세션을 모두 없앤다. 각 요청은 프로토콜 버전과 클라이언트의 기능을 _meta에 담아 보낸다. 클라이언트는 서버가 무엇을 지원하는지 server/discover로 물으며, 모든 서버는 이를 반드시 구현해야 한다(MUST). 호출 사이에 상태가 필요한 서버는 명시적인 핸들을 발급하고, 클라이언트가 그 핸들을 일반 도구 인자로 다시 전달하게 한다(변경 내역). 모든 요청에 버전과 기능을 싣기에서 _meta의 키를 볼 수 있다.

2025년 방식의 서버는 세션마다 상태 하나를 보관한다. quote_refund는 견적을 ctx.session에 저장하는데, 이는 SDK가 연결을 나타내는 객체이다. issue_refund는 인자를 받지 않고, 해당 연결이 마지막으로 만든 견적을 환불한다. SDK 1.x에서는 한 연결의 모든 요청을 객체 하나가 처리하므로(mcp/server/lowlevel/server.py, 1.x) 이 방식이 동작했다. 이 두 도구를 3장의 견적 함수와 환불 함수를 감싸는 형태로 그대로 2.x로 옮기고, 고정한 개정판의 클라이언트 하나에서 각각 한 번씩 호출한다. 그런 다음 3장의 서버를 같은 방식으로 호출한다. 이 서버의 quote_refund는 quote_id를 반환하고, issue_refund는 그 값을 받는다.

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 통과
"""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())
출력python 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

변경 없이 실행하자 이식한 서버는 두 번째 호출에서 실패했다. "Error executing tool issue_refund: There is no open quote in this session. Call quote_refund first." 두 호출은 한 클라이언트에서 한 프로세스로 들어왔지만, 서로 다른 세션 객체 2개를 보았다. 고정한 개정판에는 세션이 속할 연결이 없으므로 SDK는 요청마다 별도의 객체를 준다. 견적을 저장할 때는 아무것도 실패하지 않았고, 무언가 그 값을 다시 읽을 때에야 버그가 드러난다. Mcp-Session-Id 헤더로 상태를 구분하던 서버는 더 나쁜 결과를 맞는다. 고정한 개정판에서는 어떤 클라이언트도 이 헤더를 보내지 않으므로, 모든 클라이언트의 상태가 같은 키 None 아래에 쌓이게 된다.

핸들을 쓰자 환불이 처리되었다. requested 23.98. 이것은 엔드포인트가 아닌 작업을 중심으로 도구 설계하기가 3장을 위해 택한 설계이다. 이러한 핸들에 대한 명세의 지침은 핸들이 불투명해야 하고 만료되어야 하며, 인증을 사용하는 서버는 호출마다 핸들에 대해 호출자의 권한을 확인해야 한다는 것이다(도구). 서버가 혼동된 대리인이 되지 않게 하기에서는 상점의 견적 ID를 그 ID가 발급된 고객에게 묶는 방법을 다룬다. 한 프로세스의 메모리에 있는 핸들은 여전히 프로세스와 함께 사라지므로, 서버를 복제본으로 실행하는 순간 핸들은 공유 저장소에 둔다. 고정 세션 없이 복제본 실행하기가 SQLite로 그렇게 한다.

작업 규칙: 이전 서버에서 세션, 세션 ID, 연결별로 저장된 모든 것의 사용처를 찾아, 각 상태를 한 도구가 반환하고 다음 도구가 인자로 받는 핸들로 바꾼다. 핸들은 불투명하게 만들고, 만료 시점을 정해 이를 생성 도구의 설명에 밝히며, 호출마다 호출자가 사용할 수 있는지 확인하고, 모든 복제본이 읽을 수 있는 곳에 저장한다. 이후 호출에 필요한 것은 세션을 키로 하는 딕셔너리에 두지 않는다. 세션이 남아 있는 2025년 방식의 클라이언트에 대해서도 마찬가지이다.

HTTP+SSE에서 Streamable HTTP로 옮기기

마지막으로 변경된 판: 2026.11.11판

initialize와 세션 ID 제거하기에서 다룬 세션은 Streamable HTTP의 2025년 형태에 속한다. 상점의 2025년 시기 서버에는 더 오래된 두 번째 전송 방식이 아직 남아 있다. SHOP_OLD_HOSTS가 설정되면 서버의 마지막 줄이 HTTP+SSE를 제공하는데, 이는 2025-03-26 리비전이 대체한 전송 방식이다. 이 전송 방식에서 클라이언트는 한 엔드포인트에 이벤트 스트림을 열어 둔 채 메시지는 다른 엔드포인트로 POST한다(Streamable HTTP). SDK 1.x는 이 쌍을 /sse와 /messages/에서 제공한다(1.x에서는 mcp/server/fastmcp/server.py). 2025-03-26 리비전은 이를 Streamable HTTP로 대체했고(2025-03-26 변경 내역), 고정된 리비전은 이 전송 방식을 더 짧은 기간으로 수명 주기 정책의 적용 대상에 포함한다(변경 내역).

서버 쪽에서 이 이전은 삭제 작업이다. 포팅한 상점 서버는 서버를 stdio에서 HTTP로 옮기기에서처럼 streamable_http_app() 또는 run(transport="streamable-http")으로 한 엔드포인트에서 서비스하며, 도구에는 바뀌는 것이 없다. 고정된 리비전에서 HTTP로 연결하는 모든 클라이언트는 Streamable HTTP를 사용하므로, 전송 방식 자체가 이들의 걸림돌은 아니다. 옛 전송 방식을 언제 없앨 수 있는지는 여전히 HTTP+SSE로 연결하는 호스트가 결정하며, 이들은 정의상 2025년 시기의 클라이언트다.

이런 호스트에게는 두 가지 길이 있다. 이들을 계속 지원해야 하는 서버는 옛 SSE 엔드포인트와 POST 엔드포인트를 Streamable HTTP 엔드포인트와 함께 호스팅할 수 있으며, 명세는 2025-03-26 리비전부터 이를 허용해 왔다(Streamable HTTP). SDK 2.3.0에도 1.x와 같은 두 경로를 가진 MCPServer.sse_app()가 여전히 있고, run(transport="sse")도 있다(mcp/server/mcpserver/server.py). 옛 서버가 의존하는 것 조사하기에서 확인했듯이 둘 다 사용 중단 경고를 내지 않는다. 다른 길은 호스트가 Streamable HTTP로 옮기는 것이며, SDK 1.x의 클라이언트는 이미 이를 지원한다(1.x에서는 mcp/client/streamable_http.py).

레지스트리가 제시하는 HTTP+SSE의 가장 이른 제거 시점은 three months after SEP-2596 reaches Final이며, 이미 지났을 수도 있다. 그렇다고 SDK가 그날 sse_app()를 없앤다는 뜻은 아니다. 각 SDK가 스스로 결정하기 때문이다(기능 수명 주기). 이 전송 방식은 SEP-2596이 수명 주기 정책을 정했을 때 이미 1년 넘게 사용 중단 상태였으므로, 12개월이 아니라 3개월의 유예 기간을 받았고, 제안서 페이지는 이를 날짜 없이 Final로 표시한다. 이 날짜는 호스트가 다음 리비전 이후에도 이 전송 방식이 남아 있으리라고 기대할 수 없다는 뜻이며, 여러분도 마찬가지다.

상점의 지원팀은 날짜를 정했다. 옛 엔드포인트는 서버 로그에 /sse로 연결하는 호스트가 보이는 동안에만 유지하며, 지원팀은 그러한 각 호스트의 소유자에게 엔드포인트가 사라지는 날짜를 알린다. 그때까지 옮기지 못하는 호스트는 옛 서버의 1.x 배포에 대해 SDK 1.x를 그대로 사용할 수 있으며, 이는 코드를 SDK 1.x에서 2.x로 포팅하기에서 다룬다.

작업 규칙: 로그에 HTTP+SSE를 아직 사용하는 호스트가 보이지 않는다면, 서버의 HTTP+SSE 전송 방식은 포팅하지 말고 삭제한다. 사용하는 호스트가 있다면 옛 엔드포인트를 Streamable HTTP 엔드포인트 옆에서 함께 제공하고, 이 엔드포인트로의 모든 연결을 클라이언트별로 기록하며, 제거 날짜를 정해 각 호스트의 소유자에게 알린다. 이 전송 방식의 기간은 12개월이 아니라 3개월이었으므로, 이미 제거 대상이 될 수 있는 것으로 취급한다.

이 부분은 아직 번역되지 않았으므로 영어로 표시된다.

Replace sampling, roots and logging

마지막으로 변경된 판: 2026.11.11판

Three of the dependencies that Inventory what the old server depends on found have two changes stacked on them, and it pays to keep them apart. The first is a mechanism. A 2025 server sent its own request to the client in the middle of a call (elicitation/create, sampling/createMessage, roots/list) and waited for the answer. The pinned revision says that pattern "is no longer supported" and that this is a breaking change. A server asks through a Multi Round-Trip Request instead, returning an input request whose values may be an ElicitRequest, a CreateMessageRequest or a ListRootsRequest (Multi Round-Trip Requests). The second is the features themselves. Roots, sampling and logging are deprecated, with migration paths in the registry: roots to tool parameters, resource URIs or server configuration; sampling to integrating with a model provider's API directly; logging to stderr on stdio, or OpenTelemetry (deprecated features).

So a Multi Round-Trip Request replaces the push, not sampling. A server that moves its sampling/createMessage into an input request still depends on a deprecated feature. Elicitation is the one of the three that isn't deprecated, so it is the only one worth moving into the round trip and keeping.

The 2025-era issue_refund pushes its confirmation with ctx.elicit, which fails at the pinned revision, as See why a stateless server can't wait for an answer showed. The port asks with a resolver. A parameter declared Annotated[Release, Resolve(confirm)] is filled by running confirm before the tool, and when confirm returns Elicit(...), the SDK asks the person at the host (Ask for structured input with elicitation). confirm asks only when the shop's API holds the refund for confirmation. We quote order O-2289, whose refund is above the policy's limit, call issue_refund once by hand to see the first round, and then let Client run the rounds with the scripted lead from chapter 5, who says yes.

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 통과
"""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())
출력python replace-pushed-requests.py
first round: input_required
first round asks: elicitation/create
refund after the lead's yes: requested

The first round came back as input_required, with one question, elicitation/create: the same request the 2025 server pushed, carried in a result instead. After the lead's yes, the refund's status was requested. The resolver also works for 2025-era clients, because the SDK sends its questions in whichever form the client's revision uses (mcp/server/mcpserver/resolve.py). Serve old and new clients through the window runs both.

The port's log line uses Python's logging, not ctx.info. MCPServer configures logging to stderr when it is built (mcp/server/mcpserver/utilities/logging.py), so the line goes to the server's own logs and never to the client. On stdio, stdout carries only the protocol's messages, and stderr is where a server's logs belong (stdio). Trace calls with OpenTelemetry covers the other path.

Sampling goes entirely. The 2025-era triage_ticket asked the host's model, through sampling, which tool a ticket needs, and the port deletes that tool. The host's own model already reads every ticket and picks the tools (Work through the ticket queue), so the server was asking the host to do what the host does anyway. A server that needs a model for its own work calls a model provider with its own credentials, which also lets it choose and pay for the model.

save_restock_report asked the client for its roots and wrote to the first one. Its port takes the folder as a parameter and checks it against the folders the server's configuration allows, in SHOP_EXPORT_DIRS, after resolving the path, so that .. can't climb out.

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 통과
"""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())
출력python 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.

The allowed folder worked: "Saved 5 products to reorder in exports/restock.csv." The path that climbs out did not: "Error executing tool save_restock_report: exports/../private isn't an export folder. Use one of: exports." The host or the model now passes the folder, and the server, not the client, decides where it may write.

Working rule: Move every pushed elicitation into a resolver, which serves both eras. Delete sampling rather than move it: let the host's model do model work, or call a provider from the server with the server's own credentials. Turn roots into a parameter checked against an allow-list in the server's configuration, and send log lines to stderr and your traces, never to the client.

이 부분은 아직 번역되지 않았으므로 영어로 표시된다.

Replace dynamic client registration

마지막으로 변경된 판: 2026.11.11판

The last deprecated dependency that the inventory found is in the host, not the server, but it decides whether the support team's host can get a token for the ported server at all. The 2025 host registered itself with each authorization server it met, through 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,
)

SDK 1.x's OAuthClientProvider registers this way when it isn't given a client_metadata_url (mcp/client/auth/oauth2.py in 1.x). The pinned revision deprecates Dynamic Client Registration in favour of Client ID Metadata Documents, which revision 2025-11-25 had already recommended, and keeps it for backward compatibility (changelog; 2025-11-25 changelog). Its earliest removal is the first revision released on or after 2027-07-28.

A Client ID Metadata Document makes the client ID an https:// URL where the host publishes its own metadata, so no authorization server has to register it first. Identify the client with a metadata document builds one for the shop's host and shows the order the pinned revision ranks the options in: pre-registered credentials, then a metadata document, then registration.

The port is one argument. The host passes its document's URL as client_metadata_url, and SDK 2.x's OAuthClientProvider then uses the document when the authorization server advertises client_id_metadata_document_supported. When the server doesn't, the provider falls back to registration without saying so, as chapter 8's example showed, and the SDK's registration code at 2.3.0 raises no deprecation warning. So the authorization server is half of the port. It has to advertise metadata document support, and it should keep its registration endpoint only for the window and only for hosts that can't publish a document.

Two rules from the pinned revision matter while registration lingers. A client MUST key the credentials it stores by the authorization server's issuer and register again when the authorization server changes (changelog; client registration). A client that registers MUST send an appropriate application_type, which SHOULD be native for a host that runs on the user's machine with a loopback redirect, as this one does (changelog; client registration). A 2025 host that stored one client ID per MCP server's URL breaks the first rule the day the shop moves its authorization server.

Working rule: Publish a Client ID Metadata Document for every host and pass its URL as client_metadata_url. Make every authorization server you run advertise support for it, keep its registration endpoint only until the hosts that need it have moved, and log which kind of client ID each token was issued to, so that you can see when registration traffic has stopped.

이 부분은 아직 번역되지 않았으므로 영어로 표시된다.

Port the code from SDK 1.x to 2.x

마지막으로 변경된 판: 2026.11.11판

The sections so far changed what the shop's server does. The SDK changes that Inventory what the old server depends on found are a separate job, and they stop the old file from starting on 2.x. Two facts shape that job. The first is that the 1.x line is still maintained. The first 2.x release and a 1.x release both shipped on 2026-07-28, the day of the pinned revision, and the 1.x release on 2026-09-07, mcp==1.30.0, is a "maintenance release of the 1.x line" (PyPI; release notes). The migration guide says the 1.x line keeps receiving critical bug fixes and security patches, and nobody has published an end date (migration guide). The second fact is that both lines are the one mcp distribution, so a deployment runs one or the other, never both.

The guide lists the breaks. Those that touch a server like the shop's: mcp.server.fastmcp.FastMCP is mcp.server.mcpserver.MCPServer; McpError is MCPError(code, message, data); fields are snake_case (input_schema, is_error); the HTTP client is httpx2, not httpx; streamablehttp_client is gone, in favour of streamable_http_client; host, port, stateless_http and json_response moved from the constructor to run() and streamable_http_app(); instructions is no longer the second positional argument; MCP_* environment variables are no longer read; the WebSocket transport is removed; and ctx.log takes data, not message (migration guide).

Most of these fail loudly, which is the kind you want. One doesn't. We run the 2025-era server's setup lines on 2.3.0 and see the import, the exception it raised, and the constructor. Then we build the server twice, once with the arguments as written and once ported, and ask each what a client sees.

port-to-sdk-2.py Python 3.12.15 · mcp 2.3.0 통과
"""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())
출력python 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.

The import failed with a message that names the rename and the import to use instead: "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, which exists only to raise it). McpError failed with "cannot import name 'McpError' from 'mcp.shared.exceptions'", and the constructor with "MCPServer.init() got an unexpected keyword argument 'port'". Each points at the line to change.

The constructor as written didn't fail. In 2.x the second positional argument is title (mcp/server/mcpserver/server.py), so the server's instructions became its title. A client saw the title "Answers the support team's questions about orders, refunds and stock." and no instructions (None), and a host that puts a server's instructions in the model's context would silently lose them. With instructions= by keyword, the ported server's title is None and its instructions arrive. The port number moves to the last line, as server.run(transport="streamable-http", port=8000).

The silent breaks share a shape: an argument that still type-checks, or a setting nothing reads, like the MCP_* environment variables. Find them by reading the guide's list against the code, not by waiting for errors, and check what a client sees with a test like the one that builds the server twice.

Working rule: Keep a 2025-era server pinned to mcp<2 until its port passes its tests, then port in one change: the imports and renames the errors point at, then each silent break from the migration guide, checked with a test against what a client sees. Pin the 2.x release exactly afterwards, and treat each 2.x release as a change to test, since the SDK's warnings and defaults move between releases.

이 부분은 아직 번역되지 않았으므로 영어로 표시된다.

Serve old and new clients through the window

마지막으로 변경된 판: 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 통과
"""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())
출력python 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.

이 부분은 아직 번역되지 않았으므로 영어로 표시된다.

What goes wrong in production

마지막으로 변경된 판: 2026.11.11판

A migration fails in the gaps between the two eras: one client sees the old server, a proxy sees the new one, a warning says nothing. These are the failures to watch for.

A 2025 session lands on another replica. The sign is 404 with "Session not found" from 2025-era clients only, after a deployment or a scale-out, as on replica b in Serve old and new clients through the window. A 2025 client that follows its revision starts a new session on 404 (2025-11-25 transports), so the symptom may be lost state rather than an error. Route by Mcp-Session-Id, and count 404s by client.

A proxy drops the version header. The SDK's app picks the era from MCP-Protocol-Version alone, and its source marks routing by the body as a later step (mcp/server/streamable_http_manager.py). A proxy that strips headers it doesn't know sends a 2026-era request down the 2025 path, which expects a handshake first. The sign is failures from clients at the pinned revision behind that proxy only. Make every proxy pass the MCP headers, as Read one HTTP exchange lists them.

Error codes moved. A missing resource is -32602 at the pinned revision, not -32002, though clients SHOULD still accept -32002 (resources). The revision adds -32020 for headers that disagree with the body, -32021 for a missing client capability and -32022 for an unsupported protocol version (changelog). A host that branches on the old codes treats the codes the pinned revision added as unknown ones. Search client code for each numeric code before the server moves.

Warnings that teach people to ignore warnings. MCPDeprecationWarning is a UserWarning, so it prints by default (what's new), and a server that still uses sampling, roots or logging writes it into its logs. Turned off wholesale, it also hides the next deprecation. Filter each warning by its message only once the feature is on your inventory with a date.

Silence about HTTP+SSE and registration. The SDK at 2.3.0 warns about neither, as the inventory found. A server can pass its tests with no warnings and still lose its oldest hosts when the transport goes. Keep the scan from Inventory what the old server depends on in CI, and treat a later SDK release that adds these warnings as a reason to recheck the dates.

Reading the earliest removal as the end date. A team that plans to move off sampling or roots on 2027-07-28 has no margin, because the first revision released on or after that date may remove them. A team that reads the date as the day they disappear may also drop a feature its SDK keeps supporting for longer. Plan by the clients you serve: the registry gives the earliest date, and your logs give the real one.

Working rule: Prove the port through the real proxy path before it takes traffic, with four tests: a 2025 client completes a confirmation, a 2026 client completes the same one, a 2025 session survives a deployment, and the version header reaches the server. Then watch requests by era, 404s by client and every deprecation warning, until the 2025 count reaches zero.

이 장에서 내린 결정

  • 2025년 시기의 서버는 실행 예제가 아니라 코드 목록이다. lib.legacy는 이 서버를 SDK 1.x용 텍스트로 보관하며, 예제는 2.x로 이식한 버전만 실행한다. 하나의 환경에 두 계열을 함께 설치할 수 없기 때문이다.
  • 인벤토리는 의존성을 제거된 것, 사용 중단된 것, SDK 변경으로 나눈다. 사용 중단된 각 기능에는 레지스트리가 알려 주는 가장 이른 제거 시점을 적으며, 이는 가장 이른 날짜로 읽어야 하고 종료일로 읽어서는 안 된다.
  • 스캔은 전환 기간 내내 CI에서 실행한다. SDK는 샘플링, 루트, 로깅에 대해서는 경고하지만 HTTP+SSE나 등록에 대해서는 경고하지 않기 때문이다.
  • 세션별 상태는 핸들이 된다. 견적은 3장의 quote_id이며, 클라이언트가 이를 되돌려 보내고, 모든 레플리카가 읽을 수 있는 곳에 저장한다.
  • HTTP+SSE는 폐기한다. 쇼핑몰 서버는 Streamable HTTP만 제공하며, 로그에 이전 엔드포인트를 사용하는 호스트가 보이는 동안에만 해당 엔드포인트를 유지한다.
  • 엘리시테이션은 리졸버로 옮긴다. 리졸버는 두 시기를 모두 지원한다. 샘플링은 삭제하며, 티켓 분류는 호스트의 모델이 맡는다. 루트는 export_dir 매개변수가 되고 SHOP_EXPORT_DIRS와 대조해 검사한다. 로깅은 stderr와 트레이스로 보낸다.
  • 호스트는 Client ID Metadata Document를 사용한다. 이는 client_metadata_url를 통해 이루어지며, 인가 서버는 문서를 게시할 수 없는 호스트에 대해서만 등록을 유지한다.
  • 2.x로의 이식은 하나의 변경이다. 테스트가 통과할 때까지 mcp<2 뒤에 두며, instructions=는 키워드로 전달하고 전송 설정은 run()에서 지정한다.
  • 하나의 이중 시기 앱이 전환 기간 내내 두 시기를 모두 처리한다. 2025년 트래픽은 Mcp-Session-Id 기반의 스티키 라우팅으로 처리하고, stateless_http는 사용하지 않는다.

이 판의 이 장

2026.11.14판예제 통과 2026년 11월 19이 장에서 6개 예제개 중 6개가 통과한다

영어판 2026.11.14판을 번역한 것이다.

이 절 인용

형식

각 형식은 이 번역이 따르는 영문 원서를 출처로 표기한다.

모든 형식은 이 판을 명시한다. 링크는 현재 판을 열며, 여기서 절의 제목은 본문이 마지막으로 바뀐 시점을 알려 준다. 접근 날짜와 검색 날짜는 이 자료를 여는 날짜다.

이 페이지의 내용

12장 중 12장: 2025년형 서버 이전하기

  1. Inventory what the old server depends on
  2. initialize와 세션 ID 제거하기
  3. HTTP+SSE에서 Streamable HTTP로 옮기기
  4. Replace sampling, roots and logging
  5. Replace dynamic client registration
  6. Port the code from SDK 1.x to 2.x
  7. Serve old and new clients through the window
  8. What goes wrong in production
  9. 이 장에서 내린 결정

맨 위로 돌아가기전체 장