diff --git a/content-manifest.json b/content-manifest.json index f887a81..ae43b15 100644 --- a/content-manifest.json +++ b/content-manifest.json @@ -2258,23 +2258,23 @@ { "id": "mcp-2026-07-28-migration", "type": "guide", - "content_version": 1, + "content_version": 2, "status": "reviewed", - "reviewed_on": "2026-09-06", + "reviewed_on": "2026-10-31", "locales": [ { "lang": "en-US", "path": "guides/mcp/migrate-2026-07-28.md", "title": "Migrate a Python MCP server to the 2026-07-28 specification", "summary": "Update a Python MCP server for the stateless 2026-07-28 specification by removing the initialize handshake, adopting the input_required round-trip, dropping deprecated features, and hardening authorization.", - "sha256": "063e285acdebc4854245cbdc2951060a1b38f0fdb814692c6bdc3cd0229d2316" + "sha256": "118d2eb5e13fec380e8ba582bd9f5643fd2218a9c9dba8280a7480d6adccb576" }, { "lang": "zh-CN", "path": "guides/mcp/migrate-2026-07-28_cn.md", "title": "将 Python MCP 服务端迁移到 2026-07-28 规范", "summary": "面向 2026-07-28 无状态规范更新 Python MCP 服务端,移除 initialize 握手、采用 input_required 多轮交互、放弃废弃特性并强化授权。", - "sha256": "cc5360996f1d45cd8155dd1a0cd7a6c418d988247c54ba31ca0d5efaa1e81c8f" + "sha256": "765c9a58237dea3526f152e53f5b6f48e41bf12546b8949ffd8c40bfb2eac079" } ] }, diff --git a/guides/mcp/migrate-2026-07-28.md b/guides/mcp/migrate-2026-07-28.md index 9f327f6..73b6606 100644 --- a/guides/mcp/migrate-2026-07-28.md +++ b/guides/mcp/migrate-2026-07-28.md @@ -4,9 +4,9 @@ type: guide title: Migrate a Python MCP server to the 2026-07-28 specification summary: Update a Python MCP server for the stateless 2026-07-28 specification by removing the initialize handshake, adopting the input_required round-trip, dropping deprecated features, and hardening authorization. lang: en-US -content_version: 1 +content_version: 2 status: reviewed -reviewed_on: 2026-09-06 +reviewed_on: 2026-10-31 --- # Migrate a Python MCP server to the 2026-07-28 specification @@ -33,8 +33,9 @@ and your authorization path satisfies the new issuer rules. `resultType: "input_required"` plus the requests that need answers; the client retries the original call with the answers attached in `inputResponses`. - **Per-request version and routing headers (SEP-2243).** `MCP-Protocol-Version` - travels with every request (`2026-07-28`), and Streamable HTTP requests must include - `Mcp-Method` and `Mcp-Name` so infrastructure can route without parsing JSON bodies. + travels with every request (`2026-07-28`). Streamable HTTP requests must include + `Mcp-Method`; `Mcp-Name` is required only for `tools/call`, `resources/read`, and + `prompts/get`, matching the named parameter in each request. - **Authorization hardening.** Authorization servers must return the `iss` parameter per RFC 9207 (SEP-2468), clients must set `application_type` during dynamic registration (SEP-837), and client credentials are issuer-bound — never reused across authorization @@ -64,8 +65,9 @@ and your authorization path satisfies the new issuer rules. 5. **Upgrade the official Python SDK.** The TypeScript, Python, Go, and C# SDKs shipped with the specification; the RC-to-final window was roughly ten weeks, so older SDK versions predate the breaking changes. -6. **Update transports.** Drop the legacy HTTP+SSE transport on its one-year offramp and - emit the required `Mcp-Method` and `Mcp-Name` headers on Streamable HTTP. +6. **Update transports.** Drop the legacy HTTP+SSE transport on its one-year offramp. On + Streamable HTTP, send `Mcp-Method` on every POST and `Mcp-Name` only on + `tools/call`, `resources/read`, and `prompts/get`. 7. **Check the authorization path.** Validate `iss` per RFC 9207, set `application_type` during registration, and keep one credential per issuer. 8. **Adopt caching metadata.** Annotate list responses with `ttlMs` and `cacheScope` so diff --git a/guides/mcp/migrate-2026-07-28_cn.md b/guides/mcp/migrate-2026-07-28_cn.md index 0eed52e..d862161 100644 --- a/guides/mcp/migrate-2026-07-28_cn.md +++ b/guides/mcp/migrate-2026-07-28_cn.md @@ -4,9 +4,9 @@ type: guide title: 将 Python MCP 服务端迁移到 2026-07-28 规范 summary: 面向 2026-07-28 无状态规范更新 Python MCP 服务端,移除 initialize 握手、采用 input_required 多轮交互、放弃废弃特性并强化授权。 lang: zh-CN -content_version: 1 +content_version: 2 status: reviewed -reviewed_on: 2026-09-06 +reviewed_on: 2026-10-31 --- # 将 Python MCP 服务端迁移到 2026-07-28 规范 @@ -30,8 +30,9 @@ Foundation 管理,Python SDK 已随规范同步发布。 返回带 `resultType: "input_required"` 的结果以及待回答的请求;客户端携带 `inputResponses` 重试原始调用。 - **按请求传递版本与路由头(SEP-2243)。** `MCP-Protocol-Version` 随每个请求传递 - (值为 `2026-07-28`),Streamable HTTP 请求必须携带 `Mcp-Method` 和 `Mcp-Name`, - 让基础设施无需解析 JSON 请求体即可路由。 + (值为 `2026-07-28`)。Streamable HTTP 请求必须携带 `Mcp-Method`;仅 + `tools/call`、`resources/read` 和 `prompts/get` 需要 `Mcp-Name`,其值对应 + 请求体中的名称或 URI。 - **授权强化。** 授权服务器必须按 RFC 9207 返回 `iss` 参数(SEP-2468),客户端在 动态注册时必须设置 `application_type`(SEP-837),客户端凭据与发行方绑定——绝不 能跨授权服务器复用(SEP-2352)。 @@ -59,8 +60,9 @@ Foundation 管理,Python SDK 已随规范同步发布。 用,但新代码不应再依赖它们。 5. **升级官方 Python SDK。** TypeScript、Python、Go 和 C# SDK 已随规范发布;从 RC 到正式版大约有十周窗口,更早的 SDK 版本早于这些破坏性变更。 -6. **更新传输层。** 在一年过渡期内下线传统 HTTP+SSE 传输,并在 Streamable HTTP 上 - 输出必需的 `Mcp-Method` 与 `Mcp-Name` 头。 +6. **更新传输层。** 在一年过渡期内下线传统 HTTP+SSE 传输;Streamable HTTP 的每个 + POST 都需携带 `Mcp-Method`,且 `tools/call`、`resources/read` 和 `prompts/get` + 请求还需携带 `Mcp-Name`。 7. **检查授权链路。** 按 RFC 9207 校验 `iss`,注册时设置 `application_type`,每个 发行方使用独立凭据。 8. **采用缓存元数据。** 为列表响应标注 `ttlMs` 与 `cacheScope`,让无状态基础设施