Skip to content

docs: correct conditional MCP routing headers in bilingual migration guide #112

New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

Sign up for GitHub

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Open
kantorcodes wants to merge 3 commits into
base: master
Choose a base branch
from
Open

docs: correct conditional MCP routing headers in bilingual migration guide #112

Show file tree
Hide file tree
Changes from all commits
Commits
Show all changes
3 commits
Select commit Hold shift + click to select a range
f27cfee
docs: correct conditional MCP request headers
kantorcodes Oct 31, 2026
953bec6
docs: correct conditional MCP request headers
kantorcodes Oct 31, 2026
948897c
chore: regenerate bilingual content manifest
kantorcodes Oct 31, 2026
File filter

Filter by extension

Filter by extension
Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
8 changes: 4 additions & 4 deletions content-manifest.json
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -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"
}
]
},
Expand Down
14 changes: 8 additions & 6 deletions guides/mcp/migrate-2026-07-28.md
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -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
Expand All @@ -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
Expand Down Expand Up @@ -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
Expand Down
14 changes: 8 additions & 6 deletions guides/mcp/migrate-2026-07-28_cn.md
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -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 规范
Expand All @@ -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）。
Expand Down Expand Up @@ -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`，让无状态基础设施
Expand Down