SEP-2127：MCP Server Card——HTTP 服务器发现

社区译文；来源： MCP b491e568

摘要

本 SEP 提议增加一种标准化、自包含的格式，用于在连接前发现阶段描述 MCP 服务器。这样，客户端便能在建立连接前自动发现可用传输方式、协议版本和连接指引。

作为一项 Extensions Track SEP（依据 SEP-2133），本文确立 Server Card 扩展，并指定其工作组和维护者。详细的规范性线协议格式——Server Card schema、字段定义、发现机制和完整安全分析——不在本文中展开，而是维护在 experimental-ext-server-card 仓库中，遵循 SEP-1865（MCP Apps）所建立的先例。

动机

MCP 客户端需要一种带外方式，在选择或打开传输连接之前发现远程服务器。server/discover 等运行时机制只有在客户端已经知道连接位置后才可用。这给发现、集成和优化场景带来了阻力。

当前痛点

• 手动配置端点：用户必须为每台服务器手动配置传输 URL，没有标准化的发现机制。
• 无法进行域级发现：客户端无法自动发现某个域名上可用的 MCP 服务器。这阻碍了注册表抓取或服务自动检测等自动化集成场景。
• 缺少带外元数据：运行时发现仍然需要已配置的传输和实时连接，因此无法支持域名抓取、索引或连接前配置。

建议方案

本 SEP 引入 MCP Server Card：服务器通过标准化机制公开的结构化元数据文档。对于域级发现，AI Catalog 可以链接或嵌入相关 Server Card。Card 本身可以托管在任何未保留的 URI 上，其中 <streamable-http-url>/server-card 被保留为推荐位置。这些文档无需建立连接即可提供静态服务器信息。

可支持的用例

• 自动配置：IDE 扩展在指向某个域名后可自动完成配置，无需手动设置。
• 自动发现：客户端和注册表可以抓取域名以发现可用的 MCP 服务器，从而建立覆盖整个生态系统的服务器索引。
• 降低延迟： 无需打开每个已公布的端点，即可显示服务器信息和元数据。

与 server/discover 的关系

Server Card 提供面向 HTTP 的带外发现：公开、可缓存且可索引的元数据，可以告诉客户端应连接到何处。server/discover RPC 则在端点已知且可达后，通过各种传输方式一致地提供实时协议内发现。两种机制在身份、端点和协议版本元数据上存在重叠，并且应该（SHOULD）保持一致。如果两者不一致，客户端应该（SHOULD）优先采用实时的 server/discover 值。

发现

与 AI Catalog 的关系

AI Catalog 提供一种去中心化、与协议无关的 AI 制品识别机制。AI Catalog 条目可以链接或嵌入 MCP Server Card，由 Catalog 负责域级发现，Server Card 负责 MCP 特有的身份和连接细节。

MCP 连接细节

MCP Server Card 提供更丰富、更贴合 MCP 的定义，MCP 客户端可以据此实际连接并开始执行 MCP 操作。规范发现路径以及它与更广泛的 AI Catalog 之间的关系，在扩展仓库的 docs/discovery.md 中定义。

示例：

• “餐厅 A”与“餐厅预订 SaaS”平台合作，为该餐厅提供由 MCP 驱动的预订服务
• 餐厅 A 还与“招聘 SaaS”平台合作，向潜在求职者提供由 MCP 驱动的职位列表
• 餐厅 A 会在 restaurant-a.com/.well-known/ai-catalog.json 的 AI Catalog 中公布两张相关 Server Card
• 餐厅预订 SaaS 会为它托管的每家餐厅公开一张 Server Card（餐厅 A 一张、餐厅 B 一张，以此类推）
• 招聘 SaaS 会为它托管的每个实体公开一张 Server Card（餐厅 A 一张、咖啡店 B 一张，以此类推）

只要 Catalog 条目能够识别在其他位置托管和维护的 Server Card，我们就可以独立于 AI Catalog 开发和迭代 MCP Server Card。

与 MCP Registry 的 server.json 的关系

MCP Server Card 只描述 远程 MCP 连接。MCP Registry 的 server.json 则另行描述注册表条目，包括可在本地安装的软件包及其运行时配置。该 schema 归 Registry 所有；Server Card 扩展不定义 Server 超集，也不定义软件包安装类型。

当两种格式覆盖身份、文档和远程端点等相同概念时，它们会在实际可行的范围内使用兼容的元数据。Registry 条目可以引用或嵌入 Card 的远程信息；需要直接在 Card 上附加安装提示的供应商，则可以使用带命名空间的 _meta。

规范

完整规范维护在 experimental-ext-server-card 仓库中。TypeScript 文件 schema.ts 是唯一真相源；生成的 schema.json 以及 docs/discovery.md 中的发现机制均由其派生。

就 SEP 评审而言，扩展仓库快照 526201bb 固化了本提案评审时考虑的合同。提案接受后，实现者应遵循扩展当前的版本化规范，而非这一历史快照。按照 SEP-2133 的定义，扩展维护者可以在保持向后兼容的前提下独立演进规范；破坏性变更需要新的扩展标识符。

从高层看，Server Card 扩展引入：

• Server Card 文档：描述 远程 MCP 服务器的静态元数据文档，包括其身份（name、version、description，以及可选的 title / icons / repository / websiteUrl）、远程传输端点（URL、header、变量模板、支持的协议版本），以及可选的带命名空间 _meta 数据。_meta 不用于公布 MCP capability 或协商后的扩展支持。精确字段集合由扩展仓库中的 schema.ts 定义。
• 发现：AI Catalog 可以链接或嵌入多张 Card。Card 可以托管在任何未保留的 URI 上，其中 <streamable-http-url>/server-card 被保留为推荐位置。媒体类型、Catalog 格式以及面向浏览器的 CORS 与缓存指引，都在 docs/discovery.md 中定义。

作为扩展，MCP Server Card 是可选且增量附加的：不发布 Card 的服务器仍可通过标准 MCP 连接和运行时发现正常工作（参见向后兼容性）。

理由

为什么对 AI Catalog 使用 .well-known？

为实现自动化的域级发现，AI Catalog 可以发布在 /.well-known/ai-catalog.json。.well-known URI 模式是成熟的 IETF 标准（RFC 8615），许多协议都用它进行服务发现，包括 OAuth 2.0 Authorization Server Metadata（RFC 8414）。这种方式：

• 为发现提供可预测的标准位置
• 不需要事先了解服务器配置
• 适用于标准 HTTP 基础设施（缓存、CDN、负载均衡器）
• 使用 Web 服务的开发者已经熟悉这种方式

为什么与 Registry 元数据对齐？

MCP Server Card 旨在静态表示服务器身份和连接细节，使客户端无需事先知道服务器存在即可发现并连接它们。

MCP Registry 与 Server Card 面向不同的使用方，但共享服务器身份和远程端点等概念。对这些重叠概念复用兼容的字段名，可以减少不必要的转换，同时让各自的所有者独立演进 schema。

为什么排除原语？

本规范有意从 Server Card 中省略原语定义（工具、资源和提示）。MCP 服务器本质上是动态的：服务器公开的原语可能因已认证用户、会话、配置、功能开关、部署状态等因素而变化。静态文档无法可靠表示这一表面，而且目前无法替代使用已登录用户身份，通过协议标准操作（tools/list、resources/list、prompts/list）在运行时进行列举。过早加入原语，可能让动态服务器处于不利地位，并鼓励客户端依赖可能不正确的信息。在加入原语公布能力前，后续 SEP 应先解决必要前提，例如变体列举和清晰的使用方合同。

出于相同原因，初始 Server Card 格式不公布 MCP capability 或扩展支持。supportedProtocolVersions 让客户端能够判断是否可以尝试连接；capability 和扩展描述的是协商后的运行时行为，可能取决于客户端、身份、配置和部署状态。它们仍通过实时协议协商提供。带命名空间的 _meta 用于非标准元数据，不能替代标准化的 capability 或扩展字段。未来修订可以在定义静态声明与运行时变体的关系后加入这些字段。

为什么不等待原语？

有关原语的讨论不应延误 Server Card 的采用。发现——知道服务器存在、连接位置以及它支持的传输方式和协议版本——本身就极具价值。这既是最终用户或 IDE 安装、配置服务器所需的信息，也是注册表索引服务器所需的信息；两者都不依赖事先了解服务器工具列表。

不包含原语的 Server Card 已经可以实现本 SEP 的核心用例：自动配置、域级发现、低延迟元数据获取和注册表集成。待生态系统具备安全公布原语的适当机制后，可以在未来修订中加入它们。现在正确地交付发现能力，比交付一个范围更大但可能出错的表面更重要。

其他曾考虑的发现机制

基于 DNS 的发现：我们考虑过使用 DNS TXT 记录进行发现，类似 DKIM 或 SPF。但这种方式仅限域级发现，无法支持基于路径或端口的 MCP 服务器，因此限制过大。

基于 header 的发现：我们考虑过使用 HTTP header（类似 Link header）公布 Server Card 位置。虽然可行，但它要求先向主端点发起 HTTP 请求，从而丧失连接前发现的许多优势。

向后兼容性

本 SEP 与现有 MCP 实现完全向后兼容：

• Server Card 是可选的。不实现它们的服务器仍可通过标准 MCP 连接和运行时发现正常工作。
• 不支持 Server Card 的客户端可以忽略它们，并使用已配置的端点连接。
• 无需更改 MCP 核心协议消息或连接流程。

迁移路径

1. 阶段 1（可选）：服务器可以开始公开 Server Card，无需客户端支持
2. 阶段 2（推荐）：客户端可以实现 Server Card 获取，以增强发现和连接前验证
3. 阶段 3（未来）：生态系统可以围绕 Server Card 开发注册表、安全扫描和自动发现工具

安全影响

Server Card 是通过 HTTP 提供的、可公开访问的只读元数据文档，扩展的安全立场由此而来：

• 信息披露：Card 按设计就是公开的；服务器不得（MUST NOT）包含凭据、内部网络拓扑、专有逻辑或特定于用户/会话的数据。
• 排除原语是一项安全属性：Card 有意排除原语定义（工具、资源、提示），因此客户端不能把静态 manifest 用于访问控制或安全决策；原语始终通过标准列表操作在运行时验证。
• CORS：允许任意来源的 CORS（Access-Control-Allow-Origin: *）是可接受的，因为 Card 只包含公开、只读的元数据。
• 传输安全与 MITM：Card 应该（SHOULD）通过启用证书验证的 HTTPS 提供；由于 Card 只提供建议，且客户端会根据实时运行时元数据验证其声明，因此 Card 被攻破主要影响可发现性，而不是安全性。
• 拒绝服务：服务器应该（SHOULD）对发现端点实施速率限制，客户端应该（SHOULD）遵守缓存 header。

完整威胁模型以及规范性的 CORS、缓存和传输要求，维护在扩展仓库的 docs/discovery.md 中。

参考实现

Server Card 扩展在 experimental-ext-server-card 仓库中孵化；该仓库包含作为真相源的 TypeScript schema、生成的 JSON Schema、 发现文档，以及由验证脚本执行的有效和无效示例文档。

python-sdk#2951 是 @dsp-ant 为 Python SDK 提供的实验性 Server Card 实现：服务器端 Card 构造与提供、客户端获取与验证，以及 ServerCard 结构的 Pydantic model；测试会对一致性示例执行往返验证。

go-sdk#1024 提供用于构造和提供 Server Card 的实验性 Go SDK 服务器端参考实现。

tadasant/goose#1 演示 Goose CLI 和 Desktop 客户端中的 Server Card 发现与 安装。

工作组与维护者

• 工作组：Server Card 工作组（参见 Server Card WG discussion #2563）。
• 扩展维护者：David Soria Parra（@dsp-ant）、Sam Morrow（@SamMorrowDrums）、Tadas Antanavicius（@tadasant）。
• 扩展仓库：modelcontextprotocol/experimental-ext-server-card（接受后将升级为 ext-server-card）。

参考资料

• SEP-1865：MCP Apps（Extensions Track 先例）
• SEP-2133：扩展
• RFC 8414：OAuth 2.0 Authorization Server Metadata
• RFC 8615：Well-Known URI
• MCP 协议规范
• 原始 GitHub Issue #1649