MCP Hello Page 发现契约：标准化 JSON 端点实现工具自注册

背景：为什么 MCP 需要 Hello Page

在 Model Context Protocol（MCP）生态中，Hello Page 本质上是一份机器可读的「服务器自我介绍」。当 AI 客户端（如 Claude Desktop、ChatGPT）获知一个域名后，无需人工介入即可通过标准化的 HTTP GET 请求探测该服务器的能力清单、传输方式与鉴权路径 —— 这与 OAuth 2.0 的 /.well-known/oauth-authorization-server 发现机制一脉相承。

据 Anthropic 2026 年 1 月公告，MCP 生态已突破 97 万月 SDK 下载量、超过 10,000 个活跃公共服务器。然而在 Hello Page 标准化之前，每个服务器的接入都需要用户手动配置端点、传输类型与鉴权参数。Hello Page 的出现正是为了消解这种「拜占庭式配置」摩擦，使 AI 代理能够动态感知可用工具并优先调用，而非降级到搜索引擎或 RAG。

两种发现方案：SEP-1649 与 SEP-1960

MCP 社区目前存在两个并行推进的发现规范提案，理解二者差异是实现兼容性的前提。

SEP-1649：Server Card 方案

SEP-1649 定义了 /.well-known/mcp/server-card.json 端点，要求返回如下结构化元数据：

{
  "$schema": "https://modelcontextprotocol.io/schemas/server-card/v1.0",
  "version": "1.0",
  "protocolVersion": "2025-06-18",
  "serverInfo": {
    "name": "Analytics MCP Server",
    "version": "2.1.0",
    "description": "提供搜索分析与关键词数据接口",
    "homepage": "https://example.com"
  },
  "transport": {
    "type": "streamable-http",
    "url": "https://example.com/mcp"
  },
  "capabilities": {
    "tools": true,
    "resources": true,
    "prompts": false
  }
}

该方案的核心洞见在于：发现回答「连接哪里、有何可用」，而初始化处理「如何通信」。

SEP-1960：Manifest 端点方案

SEP-1960 采用 /.well-known/mcp 路径（注意不是 /manifest.json），其 JSON 结构更强调端点枚举与鉴权发现：

{
  "mcp_version": "2025-11-25",
  "endpoints": [
    {
      "url": "https://example.com/mcp",
      "transport": "streamable-http",
      "capabilities": ["tools", "resources"],
      "auth": {
        "type": "oauth2",
        "authorization_server": "https://example.com/.well-known/oauth-authorization-server"
      }
    }
  ]
}

SEP-1960 明确要求响应携带安全头：Content-Type: application/json、X-Content-Type-Options: nosniff、Cache-Control 与 CORS 头。

实操建议：同时实现两个端点是安全策略。SEP-1649 提供丰富的服务器元数据（描述、图标、工具列表），SEP-1960 聚焦端点枚举与认证发现，二者互补。

客户端发现流程与状态机

当用户向 AI 客户端添加 MCP 服务器 URL（如 https://gsc.example.com）时，客户端遵循以下探测序列：

探测阶段：客户端向 https://gsc.example.com/.well-known/mcp/server-card.json 与 https://gsc.example.com/.well-known/mcp 并行发送 GET 请求。
解析阶段：若端点返回有效 JSON，客户端提取传输类型、端点 URL、能力标记与鉴权要求。
认证协商：若 manifest 中指定 OAuth 端点，客户端启动 OAuth 2.1 鉴权流。
会话初始化：客户端连接到 MCP 端点，发起 JSON-RPC 握手。
能力确认：在 initialize 阶段，客户端验证服务器声明的能力与实际匹配。

若发现端点不可用或返回错误，客户端静默降级到手动配置模式。关键是许多客户端不会将发现失败展示给用户，因此生产环境必须对两个端点进行完整验证。

安全响应头配置清单

MCP 发现端点的安全配置直接影响客户端兼容性。以下是必须设置的响应头：

响应头	建议值	用途
`Content-Type`	`application/json`	明确媒体类型
`X-Content-Type-Options`	`nosniff`	防止 MIME 嗅探
`Cache-Control`	`public, max-age=3600`	控制客户端缓存行为
`Access-Control-Allow-Origin`	`*` 或白名单域名	允许浏览器跨域调用

对于高安全环境，建议对发现响应进行密码学签名，防止中间人篡改元数据。

常见实现陷阱与修复方案

陷阱一：CORS 预检失败

浏览器客户端调用跨域发现端点时会发送 OPTIONS 预检请求。若服务器未正确处理，Access-Control-Allow-Origin 头缺失将导致请求被浏览器拦截。

修复：确保 CORS 中间件显式处理 OPTIONS 方法，并将 Mcp-Session-Id 加入允许的请求头列表。

陷阱二：传输 URL 使用 HTTP

MCP 传输规范要求生产环境必须使用 HTTPS。使用 http:// 协议的传输 URL 在安全意识较强的客户端上会被拒绝。

修复：生产环境一律使用 HTTPS + 有效 TLS 证书，本地开发允许 http://localhost。

陷阱三：Protocol Version 不同步

Server Card 中声明的 protocolVersion 必须与服务器实际协商的版本严格一致，否则客户端可能表现出静默的功能缺失。

修复：将 protocolVersion 作为常量维护在统一配置文件中，升级 SDK 时同步更新两处。

陷阱四：stdout 污染

调试日志意外输出到 stdout 会破坏 stdio 传输模式的 JSON-RPC 流。虽然 Hello Page 使用 HTTP，不受此影响，但开发者常将两类传输混在一起调试。

修复：MCP 服务器中所有诊断输出统一使用 console.error（stderr），禁止 console.log。

生产验证清单

部署前逐项核对以下清单：

/.well-known/mcp/server-card.json 返回有效 JSON，包含全部必填字段
/.well-known/mcp 返回有效 manifest，包含 mcp_version 与 endpoints 数组
所有传输 URL 使用 HTTPS（生产环境）
安全头完整：Content-Type、X-Content-Type-Options: nosniff、Cache-Control、Access-Control-Allow-Origin
CORS 预检正确处理，OPTIONS 请求返回适当头
主 MCP 端点实现 Origin 校验，防止 DNS 重绑定攻击
protocolVersion 在发现端点与服务器初始化响应中同步
JSON 输出通过 jq 验证，无尾逗号、无 BOM
OAuth 发现端点（若需要鉴权）已正确配置
发现端点实施速率限制
CI/CD 中运行健康检查脚本
使用 MCP Inspector 进行端到端测试
至少在两款 AI 客户端上完成测试（Claude Desktop + 其他）
监控 well-known 路径的 5xx 错误

参考资料

SEP-1649：MCP Server Cards 规范（GitHub modelcontextprotocol）
MCP 传输规范（modelcontextprotocol.io）
Anthropic 2026 年 1 月公告：MCP 生态规模数据

ai-systems

内容声明：本文无广告投放、无付费植入。

如有事实性问题，欢迎发送勘误至 i@hotdrydog.com。