mcp-server-offering

MCP 服务方案

你是一名 MCP 产品界面设计师。设计 SaaS 产品通过 MCP 服务向 AI Agent 暴露的内容——包括提供哪些工具、设置哪些安全限制、采用何种身份验证、如何进行版本管理和效果衡量——让 Agent 可靠地操作产品，同时让供应商了解这项投入是否值得。

这是设计层。skills.sh 上流行的 MCP“构建器”技能和针对各语言的生成器低一个层级：它们会在你确定要暴露什么之后，搭建服务代码。是否提供 MCP，则由高一个层级的 samber/developer-platform-skills@api-integration-surface-strategy 决定——这项技能从 MCP 已列入路线图时开始发挥作用。

记忆（建议）： 如果记忆保存在文件中，可考虑使用 developer-platform-context.md；如果正在使用其他记忆系统，则以该系统为准。此文件仅供参考，并非强制要求。将不同任务的信息放在不同章节中。完成的任务应予以移除。任务应注明日期；一般项目背景无需注明日期。部分访谈回答可能会因任务不同而有所差异。

澄清问题

在开始任何设计之前，先询问以下问题；每个答案都会影响后续步骤。将问题合并提问——这是战术设计任务，不是战略访谈。

1. 需求证据：买方的 RFP 或安全问卷中是否出现过 MCP？客户或社区构建的服务是否已经填补了这一空白？（社区服务的存在既是需求信号，也意味着存在被取代的可能——见步骤 6）
2. 工具集可以基于哪些现有 API？稳定的公开 REST/GraphQL 契约、仅供内部使用的 API，还是完全没有机器可读接口？（最后一种情况会改变 ROI 的考量——见步骤 1）
3. 写入方面的接受程度：首发时只读是否可以接受？Agent 真正需要哪些写入操作？其中哪些不可逆、会造成财务影响，或会向人发送消息？
4. 托管方式：是由远程端点服务多个并发客户端，还是在开发者自己的工具旁运行本地进程？现有的多租户边缘基础设施有哪些？
5. 身份验证基础设施：产品是否已经运行兼容 OAuth 2.1 的授权服务器，还是 MCP 会成为首个 OAuth 消费方？（授权服务器相关工作属于 samber/developer-platform-skills@oauth2-provider-design 的范畴；这项技能只负责 MCP 资源服务器的部署方式）
6. 服务必须上线的日期、它是采购流程中的勾选项还是可持续增值的产品界面，以及投入上限（工程工时、持续维护意愿、可逆性）。这些答案会重新调整下方两个选项的优先级——严格的 RFP 截止日期会优先考虑托管服务和只读首发；持续增值目标则会优先考虑资源不足的选项。

受众划分：Agent 消费者类型

设计会因 Agent 的类型及其受监督程度而异：

• 终端用户助手客户端（聊天应用、桌面助手）——有人类用户关注对话。客户端审批提示有效，Markdown 响应很重要，MCP Apps UI（步骤 8）也适用于此类场景。写入风险在于人类用户困惑时过快地批准操作，而非无人值守的循环。
• 企业 Agent 集群——后台运行的 Agent，通常位于客户自己的网关之后，有时处于无人值守状态。只有服务端强制执行的限制才真正有效（操作人员可以替换客户端）；归属追踪和审计最为重要；企业管理的授权和私有注册表镜像会影响分发方式。
• 开发者工具客户端（IDE 和 CLI Agent）——调用方技术能力强，能够接受本地 stdio 传输，通过注册表和文档发现工具，而非通过销售渠道。

应针对其中要求最高的类型进行设计。足以保障无人值守企业 Agent 集群安全的界面，也能免费满足受监督助手的需求；反过来则不成立。

工作流

1. 评估构建投入。
2. 精简工具范围。
3. 应用写入工具安全模式。
4. 选择托管方式和身份验证。
5. 对工具范围进行版本管理。
6. 发布以便用户发现。
7. 衡量 Agent 的采用情况。
8. 分阶段推出。

下文按顺序介绍每个步骤。

如果你的运行环境支持持久化记忆，请记录此工作流的决策：

• 精简后的工具列表，以及每个工具的风险等级。
• 托管方式和身份验证策略。
• 服务当前所处的推出阶段。
• 根据你自己的遥测数据重新校准的所有阈值。

这样后续运行就能在已知范围的基础上扩展，而不必重新推导，用户也无需每次会话都重新解释设计。

1. 评估构建投入

坦诚地说，对于大多数 B2B SaaS 供应商而言，MCP 服务是日益成为采购门槛的防御性布局——竞争问题已从“是否支持 MCP”转变为“是否能很好地支持 MCP”。

• 只有少数供应商公布了可靠的一手影响数据。Atlassian 的披露是现有最有力的数据集：每个工作日有 500 万次以上工具调用，其中约三分之一为写入调用；使用的 token 减少了 48%，答案准确率提高了 44%。

• 可引用的生产环境采用基线来自 2025 年 12 月的一项调查，该调查覆盖 300 名技术负责人，结果显示约 41% 的软件组织已在有限范围到广泛范围内将 MCP 用于生产环境。

• 只有 11% 到 14% 的企业 Agent 试点项目能进入生产环境；它们停滞的原因正是步骤 3 至 4 所解决的身份、审计和访问控制方面的缺口。

• 有一种情况确实不属于防御性布局：供应商完全没有公开 API。发布 MCP 服务的公司中，约有一半没有公开的 REST API——对它们而言，MCP 是首次发布的机器可读接口，确实开辟了新的获客渠道，而非重复提供防御性功能。

• 预算要切合实际：演示级服务只需数小时即可完成；生产级服务则需要数周，大部分工作用于安全审查和测试，此外还需要持续维护（仅简单的手工构建 API 集成服务，预计就需要 150 到 250 小时）。步骤 4 中的托管方案会反映这类投入差异。

• 凌驾于其他因素之上的决策规则：如果 MCP 已成为实际买家 RFP 中的硬性要求，就应跳过分阶段时间表（步骤 8），直接推进到写入工具或 UI。反之，如果经过整整两个季度后，工具调用量仍持平且没有出现 RFP 需求，就应将该服务视为低维护成本的采购门槛，并明确推迟生产级构建，直到需求得到验证。

所有商业论证都应以 references/evidence-and-do-not-cite.md 为依据——该文件按证据强度对证据进行排序，并列出广泛流传但已被证伪或无法核实的数据。引用其中任何一项，都会损害整个论证的可信度。

2. 精心设计工具界面

关于全面覆盖还是精心筛选的争论已有定论：精心筛选胜出。不要将其描述为尚待权衡的选项。

• 对 1,412 个已分析服务的统计显示，现实中的工具数量中位数为 5 个。

• 在任何工作开始之前，仅工具元数据就可能占用 Agent 上下文窗口的 40-50%。

• 知名厂商的指导意见趋于一致：从用户工作流自顶向下设计，绝不要从 API 端点自底向上设计；“一个服务，一个任务”；5-15 个工具。

• 基于现有且稳定的 API 契约衍生工具，而不是手工构建一套平行的界面——每个发布了托管服务的主要平台，都是基于现有的 REST 或 GraphQL API 生成该服务。如果 API 契约尚未稳定，那是总览文档同级章节需要解决的排序问题，不是手工构建的理由。

• 将细粒度端点合并为工作流级工具（使用一个 upload_file(path, owner)，而不是 get_user() + upload_file()）。Agent 想知道的是“我能完成什么任务”，而不是“有哪些端点”。

• 只有在确实需要广泛覆盖且经过验证时，才采用广度模式——例如通用的执行任意端点的逃生通道、由客户端选择性启用的工具集分组、动态工具加载；绝不要将其作为默认结构。

• 工具描述是衡量下来最具杠杆效应的单一设计因素：仅调整描述，在不更改代码的情况下就能显著降低 Agent 错误率。为每个工具撰写描述时，要把它的使用场景、必需与可选参数、预期输出，以及它与相近工具的区别都写清楚，让不了解背景的协作者也能看懂。为此安排充足的工程时间。

• 通过参数设计防止错误（防错）：让错误调用在结构上难以发生（使用绝对标识符而非相对标识符，使用枚举而非自由文本字符串），而不是只记录正确用法并寄希望于调用者遵守。

• 具体规范：

  • 使用动词开头、带服务前缀的 snake_case 名称（acme_list_invoices）——命名空间由 Agent 运行的所有其他服务共享。
  • 遵循 limit 参数，并返回游标和是否有更多结果的字段；默认返回 20-50 个条目。
  • 支持 JSON 和 Markdown 响应格式。
  • 如实设置只读、破坏性和幂等性注解，并将其视为给客户端的提示，绝不能当作安全控制。
  • 在结果中报告工具错误，并提供可采取行动的消息；绝不要将泄露内部信息的错误作为协议错误返回。

• 为每个工具指定且只指定一个风险级别（第 3 步）。同时执行读取和不可逆写入的工具应拆分为两个工具。

MCP Apps：工具返回交互式界面的情形

MCP Apps 是官方 MCP 扩展（标识符 io.modelcontextprotocol/ui，规范修订版 2026-01-26）。它允许工具以交互式 HTML 界面作答——例如图表、表单、查看器或仪表板——并在对话中渲染，而不是返回一块文本。应将其视为上述精心设计工具界面之上的可选层，绝不能用它取代该界面。

MCP Apps 与服务其他部分有何不同：

• 面向不同的读者。 这个界面中的其他工具都是回答 Agent 的：模型读取结果，对其进行推理，然后为用户总结。应用则面向人类作答。用户直接点击、筛选和审批，而模型只会看到应用选择推送回其上下文的内容。
• 不同于普通工具结果。 文本或结构化结果是一次性回答；每次跟进都需要再进行一轮模型调用。应用会保留状态，让用户无需每一步都输入提示词即可探索，还可以自行调用服务端的工具。
• 不同于通过链接访问的独立 Web 应用。 应用位于对话内部，紧邻生成它的讨论，因此无需切换标签页，也不会丢失上下文。它通过服务端已公开的 MCP 工具访问数据，因此无需单独的 API、登录或会话管理。它还可以将结果交给宿主，由宿主在征得用户同意后，通过用户连接的其他能力进行处理。
• 不同于嵌入自有产品中的小组件。 自有页面是你控制的一个宿主。MCP App 会在你无法控制的多个宿主中运行，置于默认拒绝的内容安全策略沙箱内，而且每个宿主都会决定应用可以使用哪些能力。

工作方式，按宿主运行的顺序：

1. 声明。 工具的描述中包含 _meta.ui.resourceUri，指向同一服务上的 ui:// 资源。宿主甚至可以在调用工具之前预加载该资源，从而将工具输入流式传入应用。
2. 获取。 宿主读取 ui:// 资源：一个 HTML 页面，通常与其 JavaScript 和 CSS 一同打包。外部脚本和资源只会从 _meta.ui.csp 中列出的来源加载。
3. 渲染。 Web 宿主会在沙箱化的 iframe 中渲染页面。应用无法访问父页面的 DOM、Cookie 或本地存储，也无法对父页面进行导航。额外能力（摄像头、麦克风）需通过 _meta.ui.permissions 请求。
4. 通信。 应用与宿主通过 postMessage 交换 JSON-RPC 消息，这是一种 MCP 方言：部分方法与核心协议共用（tools/call），大多数方法带有 ui/ 前缀（ui/initialize）。应用可以调用服务端的工具、接收宿主推送的最新结果、发送消息，并更新模型的上下文。

按工具决定，而非按服务决定：

• 仅在任务需要文本无法承载的交互时，才提供应用：
  • 探索复杂数据（深入查看某个区域、悬停查看详情、切换指标）；
  • 一次配置多个相互依赖的选项，并提供验证和默认值，而不是来回问十个问题；
  • 查看富媒体（PDF、3D 模型、生成的图像），并进行平移和缩放；
  • 实时监控，无需用户再次提出请求即可更新；
  • 逐项处理队列中的条目（审批费用、分流问题、审查更改）。
• 其他情况都保留普通工具结果。 每个应用都是第二套前端，需要单独构建、测试并进行无障碍和安全审查，而且只要工具存在，就需要持续维护。查询、状态检查或单次写入都不会因 UI 而获益。
• 如果任务无需留在对话中，则优先采用独立 Web 应用并提供链接——无需周边上下文、不需要回调服务端的工具调用，也不需要使用宿主的其他连接能力。

设计规则：

• 确保每个由应用支持的工具在没有 UI 时也完整可用。 此扩展为可选项：客户端和服务端必须在能力协商期间都声明支持此扩展，因此不支持扩展的宿主、无头客户端和后台 Agent 集群只会收到纯结果。每次调用都返回完整的结构化结果和文本结果，并让 UI 以更丰富的方式呈现同一份数据。
• 将由 UI 发起的调用纳入与步骤 3 相同的风险等级。 在应用内点击不等于批准。应用请求的写入操作仍须通过其对应等级的关卡：试运行、确认、支出上限或人工批准，与模型直接调用工具时完全相同。
• 将宿主委派视为须经同意的操作。 应用可以请求宿主借助用户连接的其他能力来达成目标（例如“安排这场会议”），但须征得用户同意。设计流程时，绝不要让成功取决于用户是否同意。
• 只声明最低限度的内容。 在 _meta.ui.csp 中仅列出应用实际加载的外部源，并且只为任务所需的功能申请权限。每增加一个外部源，就会扩大遭入侵的依赖项可访问的范围。尽可能将资源打包到资源文件中。
• 将模型和用户提供的数据作为数据来呈现。 像 Web 应用转义不可信输入那样，在 UI 中对其进行转义；沙盒保护的是宿主，而不是你自己的应用完整性。
• 让 ui:// 资源与工具同步进行版本控制（步骤 5）。 工具的结果结构一旦变化，其应用就会静默失效；请在同一版本中发布两者，并在弃用期内保持旧结构仍可读取。
• 使用官方工具包进行构建。 references/mcp-apps-build.md 介绍了如何创建应用：使用 create-mcp-app Agent 技能或手动设置，在服务端使用 registerAppTool / registerAppResource，在 UI 中使用 App 类，进行单文件打包，以及本地测试。
• 不绑定特定框架。 @modelcontextprotocol/ext-apps 中的 App 类是一个便利封装，并非必需；官方示例提供了 React、Vue、Svelte、Preact、Solid 和原生 JavaScript 模板。选择团队已经在维护的框架。

宿主支持和测试：

• 各宿主的支持情况不一，MCP 扩展客户端矩阵由社区维护。截至 2026-09，矩阵列出了 Claude（Web 和 Desktop）、ChatGPT、Cursor、VS Code GitHub Copilot、Microsoft 365 Copilot、Goose、Postman、MCPJam、Archestra.AI 和 PostHog Code。向客户承诺支持某个宿主前，请重新核对该矩阵。
• 至少在两个宿主和一个不支持此扩展的客户端中进行测试，以验证纯结果回退。ext-apps 仓库中的 basic-host 示例无需生产宿主即可在本地渲染应用。

按照步骤 7 衡量各客户端中应用渲染调用与纯文本调用的数量，以及交互任务的完成情况（使用的深入查看功能、提交的表单、清空的队列项）。渲染出来却从未被使用的应用只会带来维护成本而没有回报：将其退役，保留工具即可。

3. 应用写入工具安全模式

六种命名模式，各自都由特定供应商验证过，详见 references/write-safety-patterns.md。它们是叠加使用而非相互竞争，因此排序决定采用顺序——先部署哪种，而不是部署哪种来取代其他模式。各项指标的排序并不一致，因此分别列出：

• 防护能力：risk-tiered policy gates > human-in-the-loop approval > scoped credentials == read-only separation > idempotency + spend caps > dry-run preflight
• 实施成本：risk-tiered policy gates > human-in-the-loop approval > dry-run preflight > idempotency + spend caps > scoped credentials == read-only separation
• 效率（单位实施成本所带来的防护能力）：scoped credentials == read-only separation > risk-tiered policy gates > idempotency + spend caps > dry-run preflight > human-in-the-loop approval

人类参与审批在实施成本排序中位居第二，尽管构建它只需几个小时：它的真正成本，是每次受控调用都要持续消耗人工注意力，而且会一直如此——对于值得这样做的调用，这恰到好处；但在其他所有场景中都难以承担。受限凭证与只读隔离在三项指标上的并列确实成立：两者都是服务端强制执行的措施，表现良好的 Agent 不会察觉；两者都是对凭证模型进行配置，而非引入新机制；而只读隔离不过是将受限凭证做到极致。

• 默认级别：从第一天起就使用受限凭证和经过验证的只读模式；所有受控写入都采用人类参与审批；默认禁用不可逆工具或会触发部署的工具。效率最高的两种模式构成了这一组合，而只有在写入量较低的早期阶段，审批才能与它们一同承担——但这一条件终将消失，也正是下方被搁置的选项应当升级的原因。
• 被搁置的选项：服务端按风险分级的策略门控（将每次调用分类为只读、影响极小、受控写入或关键操作，然后放行、补充 Agent 归属信息并进行异步审计，或在处理程序运行前拦截）。它的防护能力最高，构建成本也最高，因此按效率排序时它永远不会排在首位，也总被一再推迟——但只要后台 Agent 开始无人值守运行、写入量增长到超出人工审批能力，或发生首次写入事故，就应该立即启用。构建这种机制的供应商，正是因为一个无人值守的 Agent 关闭了数千个工单，才开发了它。
• 每种模式都必须通过的测试：强制执行必须位于服务端，因此最终用户不能通过切换客户端来绕过它。仅靠客户端审批提示和注释提示无法通过此测试。
• 如实说明行业现状：整个生态系统基本缺乏撤销／回滚能力；归属信息加审计跟踪，是目前替代真正可逆性的做法，并非已经解决问题。
• 此排序是默认方案，不是硬性规定。应根据问题 3 的写入清单以及你对用户的了解重新排序——如果产品的写入操作会发送邮件或转移资金，就应立即提高试运行和支出上限控制的优先级；纯分析类产品可能永远不需要超出默认级别的措施。

4. 选择托管方式和认证

三种托管方式，按以下顺序排序：

• 工作量：self-hosted remote > remote managed platform > local stdio
• 价值：self-hosted remote == remote managed platform > local stdio
• 效率：remote managed platform > local stdio > self-hosted remote

价值并列是确实存在的：无论哪种方式，Agent 客户端看到的都是同一个受 OAuth 保护的端点；在出现自定义服务端策略层或数据驻留限制之前，托管方式对买家来说不可见，而这恰好就是升级托管方式的条件。

• 默认选择：远程托管平台。 该协议在最初 20 个月内经历了 4 次不向后兼容的修订；托管平台可以承担这些变化以及强制要求的 OAuth 机制。存在几项企业集成后，经济上的优势也会进一步倾向托管平台。问题 6 中的紧迫期限也会加强这一选择。
• 优先级较低的选项：自托管远程服务。 控制力最高，工作量也最大——达到生产级需要数周时间，之后还需要持续维护。当 MCP 服务_本身_就是产品时（垂直 SaaS、专有数据集、受监管的工作流——客户付费购买的正是 Agent 访问权限），当第 3 步中的自定义风险分层策略必须在自有基础设施上运行时，或者当现有的多租户边缘基础设施改变了工作量对比时，可提升此选项的优先级。
• 对于在用户自己的文件和进程上运行的开发者工具产品，可降级为本地 stdio：单个客户端、托管工作量几乎为零、使用环境变量凭据，并明确豁免于下述 OAuth 要求。若受众是使用托管端点的企业级 Agent 集群，则应彻底排除该选项，而不只是降低其优先级。
• 此排序是默认方案，而非铁律；应根据问题 4-6 重新排序。

任何远程托管方式的认证规则（规范修订带有日期标记且变化很快——务必核实引用的是最新版本；本节基于 2026-07-28 修订版撰写）：

1. MCP 服务是 OAuth 2.1 资源服务器：它验证令牌，但绝不签发令牌。其背后的授权服务器设计属于 samber/developer-platform-skills@oauth2-provider-design 的范畴；这里只讨论 MCP 特有的方案。
2. 发布受保护资源元数据（RFC 9728）。
   • 要求使用资源指示符（RFC 8707），并拒绝任何并非专门为此服务签发的令牌——这是防止为一个 MCP 服务签发的令牌被重放到另一个服务上的机制。
   • 2026-07-28 修订版还强制要求验证签发者（RFC 9207），并将传输核心改为无状态：设计时应确保所有服务实例都可在普通负载均衡器后互换使用，绝不绑定会话。
3. 绝不将调用方的 bearer 令牌转发给上游 API——规范明确禁止这种混淆代理模式。应通过令牌交换获取自己的上游令牌，以 OAuth 客户端身份访问上游系统。
4. 应将合规统计视为双峰分布，而不是单一数字：常被引用的个位数 OAuth 合规率，受到大量社区 stdio 服务的拉低；而厂商托管的服务默认使用 OAuth 2.1。正确实现认证机制是通过企业安全审查的必要条件——对这一群体而言，这是基本要求，而非额外加分项。
5. 无论采用哪种托管方式，安全加固的最低要求如下：
   • 对每项输入进行 Schema 验证，并限制大小和取值范围。
   • 清理路径。
   • 绝不向客户端泄露内部错误。
   • 对本地运行的 HTTP 服务，验证 Origin 标头并绑定到 localhost（防止 DNS 重绑定）。

5. 对工具界面进行版本管理

分三层，分别管理版本——把“MCP 版本管理”当作一个决策，是个错误：

1. 协议版本：基于日期的修订版本，并设有正式的功能生命周期（Active → Deprecated → Removed，最后两个阶段之间至少间隔 12 个月）。跟踪弃用情况——例如，原始传输方式在协议早期就进入了宽限期——并固定精确的 SDK 版本，以确保构建可复现。
2. 服务的公共 API：采用常规语义化版本管理。重命名或移除工具集名称属于重大版本变更——Agent 会依据名称进行发现，因此重命名会悄无声息地破坏它们。通用的弃用机制属于 samber/developer-platform-skills@api-versioning-policy 的范畴；这里要讨论的是下一层。
3. 工具界面契约本身——名称、描述、架构——目前还没有任何规范对其进行标准化。 工具描述是编译后的接口，而非文档：一项针对 61,097 个已编目工具的分析发现，描述措辞的变化会显著改变模型选择该工具的概率——即使 JSON 架构未变，这也属于破坏性变更，而架构差异 CI 无法捕获。现在不会再有任何显式报错；Agent 只会自行适应，有时还会适应错误。

由于规范不会强制要求，第三层应遵循以下原则：

• 默认将所有变更设为增量式变更，并为旧工具名称添加别名，而不是重命名。
• 对完整界面（名称 + 描述 + 架构）计算哈希，以发现静默漂移。
• 在 CI 中运行黄金提示词行为测试：使用一组固定的代表性任务，确保任何描述编辑后，工具仍能被正确选择和调用。
• 在响应封装中携带版本标记，并记录每次调用的版本。
• 发布至少 90 天的弃用期，并通过机器可读的响应头进行通知。

描述编辑应与代码变更一样经过同一审核流程，绝不能当作文档修复处理。

6. 发布以提升可发现性

• 在官方 MCP 注册表中发布，并使用经过 DNS 验证的反向域名命名空间。了解该列表所代表的含义：注册表是一个元数据目录，提供命名空间所有权证明和社区审核——它不对安全性作任何认证，因此不要向买家暗示上架即代表可信。
• 官方注册表是必要条件，但并非充分条件：开发者也会浏览经过筛选的第三方目录，因此应将列表同步到这些目录（已有自动化工具可用于同步），而不是只发布在一个地方。
• 预计大客户会将注册表镜像到仅允许内部白名单的私有目录中。列表中的元数据和版本历史必须保持准确，因为它们会被应用策略的机器重新读取，而不只是供人浏览。
• 官方服务器一经发布，往往会取代针对同一产品由社区构建的替代品，而非与之并存——如果问题 1 中发现了社区服务器，那么妥善发布也是淘汰当前受 Agent 信任的非官方界面的一种方式。

7. 衡量 Agent 采用情况

• 将工具调用记录为 OpenTelemetry spans（会话 → 工具调用 → 下游操作），而不是自定义事件架构——在企业部署中，这些数据的受众是客户现有的可观测性技术栈，而不只是你的仪表板。随着工具范围扩大，自动埋点的包装器胜过逐个手动埋点。
• 收敛后的指标集：调用量、成功率／错误率、各工具的使用情况、活跃用户，以及客户端分布（由哪个 Agent 客户端发起调用）。目的一举两得——确认服务确实有人使用，并了解采用情况是普遍还是集中。
• 注册表列表和软件包下载量衡量的是安装意向，而不是运行时使用情况——只有服务端遥测才能回答采用情况的问题。不要把下载量当作使用数据写进商业论证。
• 假设你的遥测并非唯一的可见性层：大型客户会在你的服务前部署自己的网关。设计指标时应确保可关联（稳定的工具名称、请求 ID），而不是独占。
• 数据可靠时，就公开发布——生态系统中最有力的 ROI 证据，来自某家供应商的一手披露：调用量、写入占比、非技术用户占比、企业占比、按群组划分的留存率、准确率，以及 Token 效率提升。这种披露形式值得借鉴，详见 references/evidence-and-do-not-cite.md。
• 将客户集成故障反馈给负责处理的开发者，属于 samber/developer-platform-skills@integration-error-observability 的范畴。

8. 分阶段推出

各阶段的详细内容、阈值和 MCP Apps 决策见 references/rollout-stages-and-thresholds.md。大纲如下：

1. 只读发布：精选 5-15 个工具，从第一天起采用 OAuth 2.1，从首次调用起启用 OpenTelemetry，并发布到注册表。只有在真实 Agent 客户端产生持续的工具调用量（而非演示带来的峰值），且工具错误率低于 2% 时，才继续推进。
2. 逐步开放写入：在服务端实施风险分级，对可控写入设置审批，默认禁用关键工具，使用限定范围的凭据，记录归属并进行异步审计，使用幂等键，并在可行时支持试运行。只有在审计轨迹完整、没有未归属的写入，且审批流程可靠性得到验证后，才扩大写入范围。
3. 形成差异化：为价值最高的单一工作流提供交互式 MCP Apps UI（审批界面、可筛选仪表板、配置向导）——前提是已确认目标客户的安全团队接受在其助手中嵌入以 iframe 呈现的第三方 UI；这仍是尚待明确的问题，不能视为已获认可。将第 3 层的版本管理纪律制度化，并发布影响指标。

第 1 步中因 RFP 压力而加速的例外情况，会从两个方向影响这一流程：强烈的采购需求会推动跳过阶段；连续两个季度没有增长，则将服务停留在第 1 阶段，作为持续维护的基础能力。

故障模式

反模式清单——每项都是一条直接的审查发现：

• 全面镜像陷阱：每个 API 端点对应一个工具。Agent 会在相似工具中选错，工作尚未开始，上下文就已被元数据淹没。
• 仅可在线使用的破坏性工具——没有试运行、没有审批关卡，也没有默认禁用层级。社区 MCP 服务曾发布过取消订单的工具，会悄悄向真实客户发送邮件。
• 明明可以使用派生接口，却手工构建了并行接口——导致重复维护，并必然偏离真实 API 合约。
• 将工具描述编辑作为文档修复发布，绕过审查和行为测试，悄然改变 Agent 选择的工具。
• 将调用方的 bearer 令牌转发到上游——这是规范禁止的混淆代理模式。
• 未经验证就信任只读标志：有记录的供应商缺陷曾导致即使设置了该标志，仍发布了写入工具。要测试锁定效果，不要只配置后就想当然。
• 将工具注释（只读／破坏性提示）视为安全控制——它们只是提供给客户端的建议性元数据；执行控制应由服务端负责。
• 在商业论证中引用已被证伪的采用率统计数据——参见 references/evidence-and-do-not-cite.md 中的禁引清单。
• 采用会话绑定的服务设计——协议的无状态重写使实例可互换成为基准预期。

衡量标准

四项二元关卡——迭代设计，直到全部通过：

• 安全覆盖：每个具备写入能力的工具都恰好标注一个风险等级，并至少包含步骤 3 分类体系中的一个命名模式；每个不可逆工具都必须设置审批关卡或默认禁用。只要有一个写入工具未覆盖，就无法通过关卡。
• 身份验证合规性（远程服务）：已发布受保护资源元数据、已验证令牌受众、未向上游透传 bearer 令牌。按照规范中的 MUST 要求进行二元判定。
• 证据卫生：任何已产出的商业论证或交付物中，禁引清单中的数据均为零。
• 精选：已发布的工具集保持在 5-15 个以内，除非已记录经证实的广度需求；每个工具的命名均遵循步骤 2 的约定。

阶段转换阈值（错误率低于 2％、审计跟踪完整）基于一家供应商的只读优先实践，并非行业标准——应将其视为默认值，结合自身首月情况进行校准；步骤 7 中的采用率指标集应用于建立趋势基线，而非用来判定是否通过阈值。

调用示例

• “我们有稳定的 REST API，客户也在要求 Agent 访问权限——请设计我们的 MCP 服务：应公开哪些工具，以及如何保护写入工具？”
• “我们的 MCP 服务镜像了 60 个 API 端点，Agent 总是调用错工具——请重新设计工具集。”
• “我们希望 Agent 能通过 MCP 服务创建和取消订单——请在发布前设计安全、审批和审计模型。”
• “领导层因为竞争对手发布了 MCP 服务，也要求我们做一个——我们实际应该投入多少资源，按什么顺序开展？”

参考资料

• references/write-safety-patterns.md - 六种写入安全模式及其命名的供应商实现、反面示例和审批原语细节。
• references/rollout-stages-and-thresholds.md - 三个上线阶段及其继续／停止阈值，以及 MCP Apps UI 的决策。
• references/evidence-and-do-not-cite.md - 按证据强度排序的采用率／投资回报证据、应匹配的披露模式，以及绝不可引用的已证伪数据。

另请参阅同一集合中的资料：

• samber/developer-platform-skills@api-rate-limit-policy - Agent 流量所遵循的配额和限流策略，包括每个工具和凭据的限制。
• samber/developer-platform-skills@developer-portal-design - MCP 服务的文档、连接指南和凭据在开发者门户中的存放位置。
• samber/developer-platform-skills@cli-interface-design - 使用 shell 的 Agent 通常最先接触到的 CLI 界面；采用相同的精选而非镜像逻辑，但契约不同。
• samber/developer-platform-skills@ide-extension-offering - 将服务打包以实现一键设置的编辑器扩展；扩展负责发布，服务设计仍在此处。
• samber/developer-platform-skills@agent-skill-offering - 与服务或 CLI 一同交付、随代码进行版本管理的 Agent Skill；涵盖使用 shell 的编码 Agent 应选择 Skill 还是 MCP。
• samber/developer-platform-skills@agent-integration-surfaces - 围绕服务制定的 Agent 类别方案：边缘访问策略、Agent 身份与委派、先配置后认领的注册流程，以及 Agent 在各界面中的使用方式。