MCP 2026-07-28 改变了远程 Transport 的心智模型。当前 Profile 不再是一条拥有永久 SSE Channel 的长生命周期协议 Session,而是一组发送到同一个 HTTP Endpoint 的独立 JSON-RPC 请求;每个请求都携带足够元数据,可以独立理解和处理。
SSE 仍然存在,但职责更窄:
一个 POST 可以收到单个 JSON 响应,也可以收到请求级 SSE 响应。GET 不再是通用 Event Channel,中断的响应 Stream 也不会续传。
这个区别会直接决定 Go Server 如何处理状态、认证、取消、重试、Proxy 和横向扩容。
核心结论
- 新的 2026-07-28 远程 Server 使用一个 POST Endpoint。
- 官方 Go SDK 的 Streamable HTTP Handler 必须运行在 Stateless Mode。
- 由 SDK 校验协议元数据,不要手写 JSON-RPC Frame。
- 把 SSE 当作当前请求的一种响应编码。
- 长生命周期更新使用
subscriptions/listen。 - 响应中断后使用新 JSON-RPC ID 重发,不能使用
Last-Event-ID。 - 写操作通过幂等与状态查询保证重试安全。
- 每个请求都独立认证与鉴权,不依赖 Connection。
- 业务状态存入持久系统,并交换不透明 Handle。
- 必须穿过真实 Proxy 与 Load Balancer 测试,不能只测 Localhost。
不要混用 Transport Profile
MCP 资料中会出现三种 HTTP 形态:
| Profile | 形态 | 新项目定位 |
|---|---|---|
| 旧式 SSE(2024-11-05) | GET /sse 加 Session 专用 POST /message |
仅兼容 |
| 较早的 Streamable HTTP | POST 加可选独立 GET、Protocol Session、可恢复 SSE | 旧协议版本 |
| 2026-07-28 Streamable HTTP | 单 POST Endpoint、无 Protocol Session、JSON 或请求 SSE | 当前 Profile |
路由名为 /sse 并不能说明它实现了哪个协议。兼容能力必须明确体现在配置、Supported Version、Endpoint 归属、Telemetry 与测试中。
不能接收 2026-07-28 请求后静默使用旧 Session 行为;也不能在缺少 Session 绑定、Origin、认证和生命周期控制时暴露 Legacy Route。
请求生命周期
当前请求流程如下:
Client
POST /mcp
Content-Type: application/json
Accept: application/json, text/event-stream
带必需 _meta 的 JSON-RPC Request
|
v
Server 校验 Transport + Protocol + Auth
|
+-> application/json Response
|
`-> 仅属于该 POST 的 text/event-stream
在 2026-07-28 中:
server/discover取代旧初始化握手;- 每个请求通过
_meta携带 Protocol Version、Client Info 与 Capabilities; - HTTP Header 镜像部分 Body 字段,不一致必须拒绝;
- Server Response 包含
resultType; - Response 结束即代表该请求结束。
应由 SDK 生成精确元数据与 Wire Error。协议字段是互操作契约,不是应用随意扩展的空间。
JSON 响应还是请求级 SSE
根据行为选择:
| 响应 | 适用情况 | 代价 |
|---|---|---|
application/json |
单个有界结果,不需要中间 Server Message | Proxy 与观测更简单 |
text/event-stream |
请求完成前会产生多条协议消息 | 要求完整链路支持 Streaming |
SSE 不会自动成为 Progress API。Progress、Notification 与 Server-to-Client Request 仍需协议和 Client Capability 支持。不要发送符合 MCP 的 Client 无法理解的自定义 Comment 或 Event Type。
对 SSE Response:
- Flush 完整 Event,不能 Flush 半段 JSON;
- Request Context 取消时停止工作;
- 限制 Event 数、总字节与墙钟时间;
- 禁止无界逐请求 Queue;
- 保留 JSON-RPC Correlation;
- HTTP Write Timeout 必须兼容允许的 Stream 时长。
Discovery 与逐请求元数据
server/discover 让 Client 在普通请求前获知支持的 Protocol Version。2026-07-28 的每个请求还通过保留 _meta Key 自描述。
这不是权限协商。Client Capability 只表示 Client 能处理什么,不能证明身份、用户同意或权限。Server 应:
- 拒绝不支持的 Protocol Version;
- 校验必需元数据与 Header/Body 一致性;
- 认证 HTTP Request;
- 对命名的 MCP Operation 与业务资源鉴权;
- 在有界 Context 下执行;
- 返回符合协议的 Result。
应固定 Server 接受的 Protocol Version。宽泛兼容会增加状态空间,必须是有意识的产品决策。
没有 Protocol Session,业务仍有状态
Stateless Transport 表示任意 Instance 都能处理下一请求。持久工作流仍需状态:
requestState 或 business handle
-> principal
-> tenant
-> operation
-> canonical arguments
-> resource version
-> expiry
可以将映射存入服务端,也可以使用认证加密 Token。每次使用都要校验 Scope 与 Expiry。
绝不能使用:
- Source IP 或 TCP Connection 作为身份;
- Client 自选 Session ID 作为授权;
- 进程内存作为唯一 Workflow Store;
- 模型生成的
approved: true字段; - 缺少对象级鉴权的原始数据库主键。
显式 Subscription
用于长生命周期更新的旧式独立 GET Stream,已经被显式 Subscription Method 取代。Client 先订阅支持的 Stream,再调用 subscriptions/listen 接收 Event。
这样生命周期拥有具名协议契约:
- 创建 Subscription 时执行鉴权;
- Subscription 有明确身份与 Scope;
- Listen 可以取消和重试;
- Server 变化不依赖无关 Connection;
- 可以按 Principal 与 Subscription 限流。
Subscription 数据仍要定义保留、Overflow、Redelivery 与 Ordering Policy。“使用 SSE”并没有定义这些语义。
重试、幂等与取消
2026-07-28 删除 SSE Event ID 与 Last-Event-ID 恢复。请求级 Stream 中断后,Client 创建新的 JSON-RPC Request。
重试前先分类:
| 操作 | 策略 |
|---|---|
| 纯读取 | 在 Deadline 内指数退避重试 |
| 高成本读取 | 预算仍充足才重试,并考虑缓存 Artifact |
| 幂等写入 | 复用业务 Idempotency Key,而不是 JSON-RPC ID |
| 结果未知写入 | 重试前查询 Operation Status |
| 非幂等写入 | 显式恢复或人工审核 |
JSON-RPC Request ID 只关联一次协议调用,不是持久业务幂等 Key。
只有 Handler 正确处理 context.Context 时,才应启用 Request Cancellation Propagation。取消不会回滚已提交事务;副作用应定义 Transaction Boundary,并在确认成功前将结果记录到 Idempotency Key。
可运行的 Go Server
官方 Go SDK v1.8.0 支持 MCP 2026-07-28,并要求 Go 1.25 或更高版本。下面示例把 Server 固定到该协议,只暴露一个 POST Endpoint,启用 Stateless Mode、Request Cancellation、Body 限制和优雅关闭。
示例只绑定 Loopback。暴露到互联网前必须增加 OAuth Resource Server Middleware、TLS、明确的 Audience 与 Scope 校验,以及部署相关的 Origin/Proxy 控制。
package main
import (
"context"
"log"
"net/http"
"os/signal"
"syscall"
"time"
"github.com/modelcontextprotocol/go-sdk/mcp"
)
type HealthInput struct{}
type HealthOutput struct {
Status string `json:"status"`
}
func health(
ctx context.Context,
request *mcp.CallToolRequest,
input HealthInput,
) (*mcp.CallToolResult, HealthOutput, error) {
if err := ctx.Err(); err != nil {
return nil, HealthOutput{}, err
}
return nil, HealthOutput{Status: "ok"}, nil
}
func newMCPServer() *mcp.Server {
server := mcp.NewServer(
&mcp.Implementation{
Name: "health-server",
Version: "v1.0.0",
},
&mcp.ServerOptions{
SupportedProtocolVersions: []string{"2026-07-28"},
},
)
mcp.AddTool(server, &mcp.Tool{
Name: "service_health_get",
Description: "Return this service's current health status. " +
"Use only for availability checks; it does not inspect dependencies.",
Annotations: &mcp.ToolAnnotations{
ReadOnlyHint: true,
},
}, health)
return server
}
func main() {
mcpHandler := mcp.NewStreamableHTTPHandler(
func(request *http.Request) *mcp.Server {
return newMCPServer()
},
&mcp.StreamableHTTPOptions{
Stateless: true,
MaxRequestBodyBytes: 1 << 20,
PropagateRequestCancellation: true,
},
)
mux := http.NewServeMux()
mux.Handle("/mcp", mcpHandler)
crossOriginProtection := http.NewCrossOriginProtection()
httpServer := &http.Server{
Addr: "127.0.0.1:8080",
Handler: crossOriginProtection.Handler(mux),
ReadHeaderTimeout: 5 * time.Second,
IdleTimeout: 90 * time.Second,
}
ctx, stop := signal.NotifyContext(
context.Background(),
syscall.SIGINT,
syscall.SIGTERM,
)
defer stop()
serverErrors := make(chan error, 1)
go func() {
serverErrors <- httpServer.ListenAndServe()
}()
select {
case <-ctx.Done():
case err := <-serverErrors:
if err != nil && err != http.ErrServerClosed {
log.Fatal(err)
}
}
shutdownContext, cancel := context.WithTimeout(
context.Background(),
10*time.Second,
)
defer cancel()
if err := httpServer.Shutdown(shutdownContext); err != nil {
log.Fatal(err)
}
}
逐请求创建 Server 与 Stateless Model 一致。当大型 Tool Catalog 的反射成本显著时,SDK 支持通过 Server Options 共享 Schema Cache;应先测量再优化。生产 getServer 函数也可以把 Request Scope 的已认证 Principal 注入服务依赖,但绝不能从模型参数构造 Policy。
安装并运行:
go mod init example.com/mcp-health
go get github.com/modelcontextprotocol/[email protected]
go run .
应使用 MCP Client 或 Inspector,而不是手写 curl,这样才能正确处理必需 _meta、镜像 Header、Discovery 与 JSON-RPC Frame。
认证与鉴权
远程 Server 应遵循 MCP Authorization 规范与 OAuth Resource Server 要求。Go SDK 提供 Bearer Token Middleware 基础能力,但部署仍要正确配置 Issuer、Audience、Expiry 与 Scope Policy。
各层职责应保持独立:
TLS -> HTTP Authentication -> MCP Protocol Validation
-> Tool Authorization -> Object Authorization -> Business Policy
每个 POST 都要重新校验。之前的请求、开放 Connection 或 Subscription 不能授权下一次操作。避免把用户 Bearer Token 原样转发给下游;条件允许时应交换为绑定 Audience 的 Credential。
认证缺失或无效时返回带规定 Challenge 的 401;Principal 已认证但无权限时返回 403,同时避免泄露资源是否存在。
Proxy 与 Server 配置
验证完整链路:
- Proxy Request Buffering 与 Streaming Response 兼容;
- 中间层 Idle Timeout 大于支持的请求时长;
- Compression 不会延迟小型 SSE Event;
- 启用 HTTP/2 或 HTTP/3 时验证行为;
- Body Limit 对 Chunked 与 HTTP/2 Upload 都生效;
- 只接受可信 Hop 设置的 Proxy Header;
- DNS Rebinding 与 Origin Policy 保护本地 Server;
- Shutdown 在有界时间内排空或取消正在执行的请求。
如果 Endpoint 会持续 Streaming,不要设置短于允许 Stream 时长的全局 WriteTimeout。应优先使用 Request Deadline 与逐 Operation Budget。
旧式兼容
如果旧 Client 仍需要 GET /sse 加 POST /message:
- 暴露独立兼容 Endpoint 或 Service;
- 固定旧 Protocol Version;
- 将 Server 生成的 Session ID 绑定到已认证 Principal;
- 校验 Origin,并保护本地 Endpoint 免受 DNS Rebinding;
- 限制 Queue、Heartbeat、Idle Session 与重连速率;
- 发布移除指标与迁移期限。
不能复制一段不完整的 http.Flusher 示例就称其为 MCP Server。Transport 还必须处理 JSON-RPC 校验、Correlation、取消、鉴权、背压与生命周期。
测试矩阵
协议
server/discover、支持与不支持版本;- 必需
_meta与 Header/Body 不一致; - JSON 与请求级 SSE Response;
- Tool Call 成功、Tool Error 与
input_required; - 取消与 Response 完成;
subscriptions/listen生命周期。
HTTP 与基础设施
- 错误 Method、Media Type 与超大 Body;
- 慢上传与慢消费者;
- Proxy Buffering 与 Idle Timeout;
- 副作用提交前后断连;
- 活跃请求下优雅关闭;
- 并发请求路由到不同 Instance。
安全
- 缺失、过期、错误 Audience 与 Scope 不足 Token;
- 跨 Tenant 标识符;
- 伪造 State Handle;
- DNS Rebinding 与不可信 Forwarded Header;
- Result Size 滥用与下游内容中的 Prompt Injection。
可靠性
- 重复 Idempotency Key;
- JSON 与 SSE Response 丢失后重试;
- 下游超时与 Rate Limit;
- Subscription Overflow;
- Workflow 步骤之间进程重启。
上线检查清单
- [ ] Protocol 与 SDK 版本已固定。
- [ ] 2026-07-28 Request 使用 Stateless Streamable HTTP。
- [ ] 当前 Endpoint 只暴露 POST。
- [ ] 必需 Metadata 与镜像 Header 由 SDK 校验。
- [ ] Request Body、Response Byte、Event、时长与并发均有上限。
- [ ] 每个请求都执行认证与对象级鉴权。
- [ ] Handler 传播取消。
- [ ] 写操作使用持久幂等与状态查询。
- [ ] 业务状态使用范围化、会过期的 Handle。
- [ ] Subscription 有鉴权、保留与 Overflow Policy。
- [ ] Proxy Streaming 行为经过负载验证。
- [ ] 旧式兼容已隔离并可度量。
总结
只要尊重边界,现代 MCP Transport 会更简单:一个 POST Endpoint、自描述请求、无状态路由,以及 JSON 或请求级 SSE Response。如果继续携带旧 Protocol Session、隐藏 Connection State 和不安全重试,这种简单性就会消失。
协议 Frame 应交给官方 SDK,工程精力则投入协议无法提供的控制:身份、鉴权、幂等、持久状态、限制、可观测性与失败恢复。
Endpoint 背后的 Tool Contract 可阅读 MCP Tool 设计,Host 侧执行 Policy 可阅读 LLM Tool Calling 指南。