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。

请求生命周期

当前请求流程如下:

text
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 应:

  1. 拒绝不支持的 Protocol Version;
  2. 校验必需元数据与 Header/Body 一致性;
  3. 认证 HTTP Request;
  4. 对命名的 MCP Operation 与业务资源鉴权;
  5. 在有界 Context 下执行;
  6. 返回符合协议的 Result。

应固定 Server 接受的 Protocol Version。宽泛兼容会增加状态空间,必须是有意识的产品决策。

没有 Protocol Session,业务仍有状态

Stateless Transport 表示任意 Instance 都能处理下一请求。持久工作流仍需状态:

text
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 控制。

go
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。

安装并运行:

text
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。

各层职责应保持独立:

text
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:

  1. 暴露独立兼容 Endpoint 或 Service;
  2. 固定旧 Protocol Version;
  3. 将 Server 生成的 Session ID 绑定到已认证 Principal;
  4. 校验 Origin,并保护本地 Endpoint 免受 DNS Rebinding;
  5. 限制 Queue、Heartbeat、Idle Session 与重连速率;
  6. 发布移除指标与迁移期限。

不能复制一段不完整的 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 指南。

一手资料