SEP-2243: 用于可流式 HTTP 传输的 HTTP 头标准化

​

摘要

​

动机

• 负载均衡器 必须终止 TLS 并解析整个 JSON 正文才能提取路由信息（例如区域、工具名称）
• 代理和网关 无法在不进行深度包检测的情况下做出路由决策
• 可观测性工具 对 MCP 流量模式的可见性有限
• 限流器和 WAF 无法基于 MCP 特定字段应用策略

​

规范

​

标准头

理由：该要求可防止当网络中的不同组件依赖不同事实来源时可能出现的安全漏洞和错误条件。例如，负载均衡器或网关可能使用头值做路由决策，而 MCP 服务器使用正文值执行操作。该要求适用于任何处理消息正文的网络中介，以及 MCP 服务器本身。

实施说明：在验证整数参数值时，服务器 SHOULD 按数值而不是按字符串比较头值和正文值（例如，42.0 和 42 被视为相等）。

​

示例：tools/call 请求

POST /mcp HTTP/1.1
Content-Type: application/json
Mcp-Session-Id: 1f3a4b5c-6d7e-8f9a-0b1c-2d3e4f5a6b7c
Mcp-Method: tools/call
Mcp-Name: get_weather

{
  "jsonrpc": "2.0",
  "id": 1,
  "method": "tools/call",
  "params": {
    "name": "get_weather",
    "arguments": {
      "location": "Seattle, WA"
    }
  }
}

​

示例：resources/read 请求

POST /mcp HTTP/1.1
Content-Type: application/json
Mcp-Session-Id: 1f3a4b5c-6d7e-8f9a-0b1c-2d3e4f5a6b7c
Mcp-Method: resources/read
Mcp-Name: file:///projects/myapp/config.json

{
  "jsonrpc": "2.0",
  "id": 2,
  "method": "resources/read",
  "params": {
    "uri": "file:///projects/myapp/config.json"
  }
}

​

示例：prompts/get 请求

POST /mcp HTTP/1.1
Content-Type: application/json
Mcp-Session-Id: 1f3a4b5c-6d7e-8f9a-0b1c-2d3e4f5a6b7c
Mcp-Method: prompts/get
Mcp-Name: code_review

{
  "jsonrpc": "2.0",
  "id": 3,
  "method": "prompts/get",
  "params": {
    "name": "code_review",
    "arguments": {
      "language": "python"
    }
  }
}

​

示例：其他请求方法

POST /mcp HTTP/1.1
Content-Type: application/json
Mcp-Method: initialize

{
  "jsonrpc": "2.0",
  "id": 4,
  "method": "initialize",
  "params": {
    "protocolVersion": "2025-06-18",
    "capabilities": {},
    "clientInfo": {
      "name": "ExampleClient",
      "version": "1.0.0"
    }
  }
}

​

示例：通知

POST /mcp HTTP/1.1
Content-Type: application/json
Mcp-Session-Id: 1f3a4b5c-6d7e-8f9a-0b1c-2d3e4f5a6b7c
Mcp-Method: notifications/initialized

{
  "jsonrpc": "2.0",
  "method": "notifications/initialized"
}

​

来自工具参数的自定义头

​

Schema 扩展

• MUST NOT be empty
• MUST match HTTP field-name token syntax (1*tchar, RFC 9110 Section 5.1)
• MUST NOT contain control characters, including carriage return (CR, \r) or line feed (LF, \n)
• MUST be case-insensitively unique among all x-mcp-header values in the inputSchema
• MUST only be applied to parameters with primitive types (integer, string, boolean). Parameters with type number are not permitted. Integer values MUST be within the safe range for JavaScript (−2^53+1 to 2^53−1)
• MAY be applied to properties at any nesting depth within the inputSchema, not only top-level properties

{
  "name": "execute_sql",
  "description": "在 Google Cloud Spanner 上执行 SQL",
  "inputSchema": {
    "type": "object",
    "properties": {
      "region": {
        "type": "string",
        "description": "执行查询的区域",
        "x-mcp-header": "Region"
      },
      "query": {
        "type": "string",
        "description": "要执行的 SQL 查询"
      }
    },
    "required": ["region", "query"]
  }
}

​

示例：地理分布式数据库

{
  "name": "execute_sql",
  "description": "在 Google Cloud Spanner 上执行 SQL",
  "inputSchema": {
    "type": "object",
    "properties": {
      "region": {
        "type": "string",
        "description": "执行查询的区域",
        "x-mcp-header": "Region"
      },
      "query": {
        "type": "string",
        "description": "要执行的 SQL 查询"
      }
    },
    "required": ["region", "query"]
  }
}

POST /mcp HTTP/1.1
Content-Type: application/json
Mcp-Session-Id: 1f3a4b5c-6d7e-8f9a-0b1c-2d3e4f5a6b7c
Mcp-Method: tools/call
Mcp-Name: execute_sql
Mcp-Param-Region: us-west1

{
  "jsonrpc": "2.0",
  "id": 1,
  "method": "tools/call",
  "params": {
    "name": "execute_sql",
    "arguments": {
      "region": "us-west1",
      "query": "SELECT * FROM users"
    }
  }
}

​

示例：多租户 SaaS 应用

{
  "name": "query_analytics",
  "description": "查询某个租户的分析数据",
  "inputSchema": {
    "type": "object",
    "properties": {
      "tenant_id": {
        "type": "string",
        "description": "租户标识符",
        "x-mcp-header": "TenantId"
      },
      "metric": {
        "type": "string",
        "description": "要查询的指标"
      },
      "start_date": {
        "type": "string",
        "description": "查询范围的开始日期"
      },
      "end_date": {
        "type": "string",
        "description": "查询范围的结束日期"
      }
    },
    "required": ["tenant_id", "metric", "start_date", "end_date"]
  }
}

POST /mcp HTTP/1.1
Content-Type: application/json
Mcp-Session-Id: 1f3a4b5c-6d7e-8f9a-0b1c-2d3e4f5a6b7c
Mcp-Method: tools/call
Mcp-Name: query_analytics
Mcp-Param-TenantId: acme-corp

{
  "jsonrpc": "2.0",
  "id": 5,
  "method": "tools/call",
  "params": {
    "name": "query_analytics",
    "arguments": {
      "tenant_id": "acme-corp",
      "metric": "page_views",
      "start_date": "2026-01-01",
      "end_date": "2026-01-31"
    }
  }
}

​

示例：基于优先级的请求处理

{
  "name": "generate_report",
  "description": "生成复杂报告",
  "inputSchema": {
    "type": "object",
    "properties": {
      "report_type": {
        "type": "string",
        "description": "要生成的报告类型"
      },
      "priority": {
        "type": "string",
        "description": "请求优先级：low、normal 或 high",
        "x-mcp-header": "Priority"
      }
    },
    "required": ["report_type"]
  }
}

POST /mcp HTTP/1.1
Content-Type: application/json
Mcp-Session-Id: 1f3a4b5c-6d7e-8f9a-0b1c-2d3e4f5a6b7c
Mcp-Method: tools/call
Mcp-Name: generate_report
Mcp-Param-Priority: high

{
  "jsonrpc": "2.0",
  "id": 6,
  "method": "tools/call",
  "params": {
    "name": "generate_report",
    "arguments": {
      "report_type": "quarterly_summary",
      "priority": "high"
    }
  }
}

​

头处理

​

值编码

• 回车符（\r，0x0D）
• 换行符（\n，0x0A）
• 空字符（\0，0x00）
• ASCII 范围之外的任何字符（> 0x7F）

• 以空格（0x20）或水平制表符（0x09）开头
• 以空格（0x20）或水平制表符（0x09）结尾

1. Type conversion: Convert the parameter value to its string representation:
   • string: Use the value as-is
   • integer: Convert to decimal string representation (e.g., 42, -7)
   • boolean: Convert to lowercase "true" or "false"
2. 空白检查：如果字符串以空白字符（空格或制表符）开头或结尾：
   • 应用 Base64 编码（见下文）
3. ASCII 校验：检查字符串是否仅包含有效 ASCII 字符（0x20-0x7E）：
   • 如果有效，继续执行第 4 步
   • 如果无效（包含非 ASCII 字符），应用 Base64 编码（见下文）
4. 控制字符检查：如果字符串包含任何控制字符（0x00-0x1F 或 0x7F）：
   • 应用 Base64 编码（见下文）

Mcp-Param-{Name}: =?base64?{Base64EncodedValue}?=

​

客户端行为

1. 从请求体中提取任何标准头的值（例如，method、params.name、params.uri）
2. 将 Mcp-Method 头以及（如适用）Mcp-Name 头追加到请求中
3. 检查工具的 inputSchema 中标记有 x-mcp-header 的属性，并提取每个参数的值
4. 按照 值编码 中的规则对这些值进行编码
5. 将 Mcp-Param-{Name}: {Value} 头追加到请求中：

实现说明：如果客户端没有工具的 inputSchema（例如尚未调用 tools/list）或者缓存的 schema 已过期（例如 TTL 已到期），客户端 SHOULD 在不带自定义 Mcp-Param-* 头的情况下发送请求。如果服务器因为缺少必需的自定义头而拒绝该请求，客户端 SHOULD 调用 tools/list 以获取当前的 inputSchema，然后使用适当的头重试原始请求。客户端 MAY 通过其他方式预加载工具定义（例如来自先前会话或配置），以便在未先调用 tools/list 的情况下也能发送头。

​

Server Behavior

{
  "jsonrpc": "2.0",
  "id": 1,
  "error": {
    "code": -32001,
    "message": "头不匹配：Mcp-Name 头值 'foo' 与正文值 'bar' 不匹配"
  }
}

• 缺少必需的标准头（Mcp-Method、Mcp-Name 等）
• 头值与请求体值不匹配
• Base64 编码的值无法解码
• 头值包含无效字符

注意：中介 MUST 在验证失败时返回适当的 HTTP 错误状态（例如 400 Bad Request），但不要求返回 JSON-RPC 错误响应。

注意：基于镜像头执行策略的中介（例如按租户进行路由或限流）SHOULD 验证 MCP-Protocol-Version 头是否指示了一个需要头-正文验证的版本。如果版本较旧或该头缺失，中介 SHOULD 拒绝该请求，而不是信任未验证的头值。

​

理由

​

Header 与 Path

1. 简单性：所有广泛使用的网络负载均衡器都支持基于 HTTP header 的路由
2. 多版本支持：在客户端和服务器中更容易支持多个 MCP 版本
3. 兼容性：Header 可与现有的 Streamable HTTP 传输设计配合使用，而无需更改 endpoint 结构
4. 值无限制：Header 值可以包含在 URL 中需要编码的字符（例如 /、?、#）
5. 无 URL 长度限制：很长的值也可以传输，而不会触及 URL 长度限制

1. 框架简单性：许多 Web 框架（Flask、Express、Django、Rails）都内置支持基于 path 的路由，配置极少
2. 日志记录：URL path 通常默认会被记录，便于调试

# Flask 示例：基于 Header 的路由需要手动分发
@app.route('/mcp', methods=['POST'])
def mcp_handler():
    method = request.headers.get('Mcp-Method')
    if method == 'tools/call':
        return handle_tools_call(request)
    elif method == 'resources/read':
        return handle_resources_read(request)
    # ... 等等

1. 向后兼容：引入基于 path 的路由将要求所有现有 MCP Server 进行重大更新，并且可能需要同时支持两套 endpoint 来支持多个版本。即使 SDK 可以在一定程度上掩盖这些问题，测试、指标等额外运维关注点仍然需要处理。基于 header 的路由只需极少的客户端改动。未选择 opt in 的客户端也仍可正常工作。
2. 基础设施收益大于框架复杂度：主要目标是让网络基础设施（负载均衡器、代理、WAF）无需解析 body 就能路由和处理请求。这一收益与服务器所使用的框架无关。

​

基础设施支持

• 负载均衡器：所有主流负载均衡器（HAProxy、NGINX、Cloudflare、F5、Envoy/Istio）
• 限流：11 个流行限流方案中的 9 个
• 授权：Kong、Tyk、AWS API Gateway、Google Cloud Apigee、Azure API Gateway、NGINX、Apache APISIX、Istio/Envoy
• Web 应用防火墙：Cloudflare WAF、AWS WAF、Azure WAF、F5 Advanced WAF、FortiWeb、Imperva WAF、Barracuda WAF、ModSecurity、Akamai、Wallarm
• 可观测性：大多数可观测性方案都可以从 HTTP header 中提取数据

​

x-mcp-header 中显式 Header 名称

1. 大小写敏感性不匹配：Header 名称不区分大小写，但 JSON Schema 属性名区分大小写
2. 字符集限制：Header 名称仅限 ASCII 字符，而工具参数名可能包含任意 Unicode
3. 简单性：无需用复杂方案从嵌套属性构造 header 名称

​

在 JSON Schema 中的位置

1. 共置性：header 映射与其影响的属性定义在一起，使其立即清楚哪个参数会被镜像。开发者无需在 schema 与单独的元数据结构之间来回查找。
2. 成熟模式：JSON Schema 明确支持扩展关键字（以 x- 开头的属性），这一模式在 OpenAPI 等生态中被广泛使用。工具作者和 SDK 开发者对此方式已经很熟悉。
3. Schema 可组合性：当 schema 被组合、扩展或通过 $ref 引用时，x-mcp-header 注释会随属性定义一起传递。单独的元数据结构则需要复杂的同步逻辑来保持一致性。
4. 工具兼容性：现有 JSON Schema 校验器默认会忽略未知关键字，因此添加 x-mcp-header 不会破坏现有 schema 校验。不理解此扩展的工具会直接跳过它。
5. 降低复杂度：单独的元数据结构需要定义一种映射机制（例如 JSON Pointer 或属性路径）来将 headers 与属性关联起来，这会增加实现复杂度并带来出错风险。

​

范围：仅适用于 Tools

​

不定义规范层面的 Header 大小限制

1. 任意阈值：无论选择什么数值，对某些部署来说都太低，对另一些则无关紧要。合适的“正确”限制因基础设施而异。
2. 适得其反的省略：如果客户端因为某个 header 超过规范定义的限制而省略它，那么依赖该 header 进行路由的服务器和中间件就必须解析 body 或拒绝请求——这会削弱将值暴露在 header 中的核心目的。
3. 不必要的 SDK 负担：SDK 维护者需要为一个在实践中很少适用的约束实现并测试限制检查逻辑。
4. 与 HTTP 重复：服务器和中间件已经会使用标准 HTTP 状态码拒绝过大的 header（413 Request Entity Too Large、431 Request Header Fields Too Large），客户端无论如何都必须处理这些响应。

给实现者的注记：服务器、中间件和客户端可以根据各自的部署环境独立对单个 header 大小、MCP header 总大小或自定义 header 数量施加限制。服务器应记录其施加的任何限制。客户端应优雅地处理 413 Request Entity Too Large 或 431 Request Header Fields Too Large 响应。工具作者应将 x-mcp-header 注释限制在那些能带来明确基础设施收益的参数上。

​

不安全值的编码方式

1. Sentinel 包裹（所选方案）：在同一个 Mcp-Param-{Name} header 内使用 =?base64?{value}?= 前缀/后缀来标识 Base64 编码值。
2. 单独的 header 名称：为编码值使用不同的 header 名称，例如 Mcp-ParamEncoded-{Name}，通过 header 名称而不是值格式来表示编码。
3. 隐式编码：让解析器根据工具 schema 推断编码，例如在工具定义中使用 "x-mcp-header-encoding": "base64" 注释。
4. 始终编码：对每个 Mcp-Param-{Name} 值都无条件进行 Base64 编码。

​

向后兼容性

​

标准头

​

来自工具参数的自定义头

​

安全影响

​

头注入

• 控制字符绝不会包含在头值中
• 非 ASCII 值会使用 Base64 安全编码
• 超过安全长度限制的值会被省略

​

头伪造

• 在执行面向高安全区域的操作时，将请求路由到安全性较低的区域
• 通过伪造租户标识来绕过速率限制
• 通过虚报正在执行的操作来规避安全策略

​

信息泄露

• SHOULD NOT 将敏感参数（密码、API 密钥、令牌、PII）标记为 x-mcp-header
• SHOULD 记录哪些参数会作为头暴露
• SHOULD 考虑到 Base64 编码不提供机密性——它只是编码，不是加密

​

信任头值

• 暗示可访问特定资源的头值（例如租户 ID、区域名称）在授予对这些资源的访问权限之前，MUST 先由身份验证用户的权限进行独立验证。
• 头值 MUST NOT 作为授予提升权限的唯一依据；必须由服务器端强制执行速率限制和配额。
• 部署 SHOULD 尽早在流水线中拒绝带有过大或过多头的请求——在执行 Base64 解码或正文解析之前——以缓解精心构造的载荷带来的拒绝服务风险。

​

一致性测试用例

​

标准头边界情况

​

大小写敏感性

​

头/正文不匹配

​

值中的特殊字符

​

自定义头边界情况

​

x-mcp-header 名称冲突

​

无效的 x-mcp-header 值

​

值编码边界情况

​

类型限制违规

​

服务器验证边界情况

​

Base64 解码

​

空值与缺失值

​

当正文中存在值但缺少自定义头时

​

参考实现

• 服务器 SDK：提供一种机制（属性/装饰器）来标记带有 x-mcp-header 的参数
• 客户端 SDK：实现提取和编码头部值的客户端行为
• 验证：双方都必须验证头部/正文一致性