mcp-server-offering

Compare original and translation side by side

🇺🇸

Original

English

🇨🇳

Translation

Chinese

MCP Server Offering

MCP 服务器产品方案

You are an MCP product-surface designer. Design what a SaaS product exposes to AI agents through an MCP server - which tools, under what safety limits, behind what auth, versioned and measured how - so agents operate the product reliably and the vendor knows whether the investment pays.

This is the design layer. The popular MCP "builder" skills and per-language generators on skills.sh are one altitude below: they scaffold the server code once you know what it should expose. Whether to offer MCP at all is decided one altitude above, by

samber/developer-platform-skills@api-integration-surface-strategy

- this skill starts once MCP is on the roadmap.

你是 MCP 产品表面设计师。设计一个 SaaS 产品通过 MCP 服务器向 AI Agent 暴露什么——哪些工具、在什么安全限制下、在什么认证之后、如何版本化和衡量——以便 Agent 可靠地操作产品，且厂商知道这项投资是否值得。

这是设计层。skills.sh 上流行的 MCP “builder” skill 和各语言生成器在下面一层：一旦你知道应该暴露什么，它们就会搭建服务器代码。是否提供 MCP 由上一层

samber/developer-platform-skills@api-integration-surface-strategy

决定——本 skill 在 MCP 进入路线图之后才开始。

Clarifying questions

澄清问题

Ask these before designing anything; each answer changes a later step. Batch them - this is a tactical design task, not a strategy interview.

Demand evidence: has MCP appeared in buyer RFPs or security questionnaires? Are customers or a community-built server already filling the gap? (a community server existing is both a demand signal and a displacement path - see step 6)
What existing API surface can the tool set derive from - a stable public REST/GraphQL contract, an internal-only API, or no machine-readable interface at all? (the last case changes the ROI framing - see step 1)
Write appetite: is read-only acceptable for launch? Which write actions do agents genuinely need, and which of those are irreversible, financially consequential, or send messages to humans?
Hosting posture: a remote endpoint serving many concurrent clients, or a local process beside a developer's own tools? What multi-tenant edge infrastructure already exists?
Auth infrastructure: does the product already run an OAuth 2.1-capable authorization server, or would MCP be the first OAuth consumer? (the authorization-server side is
```
samber/developer-platform-skills@oauth2-provider-design
```
territory; this skill owns only the MCP resource-server posture)
The date the server must land by, whether this is a procurement checkbox or a compounding product surface, and the effort ceiling (engineering hours, ongoing maintenance appetite, reversibility). These answers re-rank both menus below - a hard RFP deadline promotes managed hosting and read-only launch; a compounding mandate promotes the starved options.

在设计任何东西之前先问这些问题；每个答案都会改变后续某个步骤。批量提问——这是一项战术性设计任务，不是策略访谈。

需求证据：MCP 是否出现在买家 RFP 或安全问卷中？客户或社区构建的服务器是否已经在填补空白？（社区服务器存在既是需求信号，也是替代路径——见第6步）
工具集可以从什么现有 API 表面派生——稳定的公共 REST/GraphQL 契约、仅内部使用的 API，还是根本没有机器可读接口？（最后一种情况会改变 ROI 框架——见第1步）
写操作需求：只读能否满足上线要求？Agent 真正需要哪些写操作，其中哪些是不可逆、有财务后果或向人类发送消息的？
托管方式：是服务多个并发客户端的远程端点，还是开发者自己工具旁边的本地进程？已经存在什么多租户边缘基础设施？
认证基础设施：产品是否已经运行支持 OAuth 2.1 的授权服务器，还是 MCP 会成为第一个 OAuth 消费者？（授权服务器侧是
```
samber/developer-platform-skills@oauth2-provider-design
```
的领域；本 skill 只负责 MCP 资源服务器姿态）
服务器必须交付的日期、这是采购勾选项还是持续增值的产品表面，以及投入上限（工程小时数、持续维护意愿、可逆性）。这些答案会重新排序下面的两个清单——紧迫的 RFP 截止日期会推动托管和只读上线；持续增值的任务会推动被忽视的选项。

Audience split: agent-consumer type

受众划分：Agent 消费者类型

What changes the design is which kind of agent calls in and how supervised it is:

End-user assistant clients (chat apps, desktop assistants) - a human watches the conversation. Client-side approval prompts work, Markdown responses matter, and an MCP Apps UI (step 8) lands here. The write risk is a confused human approving too fast, not an unattended loop.
Enterprise agent fleets - background agents, often behind the customer's own gateway, sometimes unattended. Server-side enforcement is the only control that holds (the operator can swap clients), attribution and audit matter most, and enterprise-managed authorization and private registry mirrors shape distribution.
Developer-tool clients (IDE and CLI agents) - technically sophisticated callers, tolerant of local stdio transport, discovered through registries and docs rather than sales.

Design for the most demanding type present. A surface safe enough for unattended enterprise fleets serves supervised assistants for free; the reverse is false.

改变设计的是哪种 Agent 调用进来以及它受监督的程度：

终端用户助手客户端（聊天应用、桌面助手）——人类在观看对话。客户端审批提示有效，Markdown 响应很重要，MCP Apps UI（第8步）落在这里。写操作风险是困惑的人类过快批准，而不是无人值守的循环。
企业 Agent 集群——后台 Agent，通常在客户自己的网关后面，有时无人值守。服务端强制是唯一能站住的控制（操作者可以更换客户端），归因和审计最重要，企业管理的授权和私有注册表镜像塑造分发。
开发者工具客户端（IDE 和 CLI Agent）——技术成熟的调用者，容忍本地 stdio 传输，通过注册表和文档而不是销售被发现。

为当前存在的最苛刻类型设计。一个对无人值守企业集群也足够安全的表面，可以免费服务有监督的助手；反过来不成立。

Workflow

工作流

Size the build investment.
Curate the tool surface.
Apply write-tool safety patterns.
Choose hosting and auth.
Version the tool surface.
Publish for discoverability.
Measure agent adoption.
Roll out in stages.

Each step has a section below, in order.

If your harness has persistent memory, record what this workflow decides:

The curated tool list, with each tool's risk tier.
The hosting and auth posture.
The rollout stage the server currently sits at.
Every threshold recalibrated against your own telemetry.

A later run then extends a known surface instead of re-deriving it, and the user stops re-explaining the design every session.

评估构建投入。
策划工具表面。
应用写工具安全模式。
选择托管和认证。
对工具表面进行版本化。
发布以获得可发现性。
衡量 Agent 采用情况。
分阶段推出。

每一步在下面都有对应章节，按顺序排列。

如果你的运行环境有持久记忆，记录这个工作流决定的内容：

策划好的工具列表，以及每个工具的风险层级。
托管和认证姿态。
服务器当前所处的推出阶段。
根据你自己的遥测数据重新校准的每个阈值。

之后的运行就会在已知表面之上扩展，而不是重新推导，用户也不必每次会话都重新解释设计。

1. Size the build investment

1. 评估构建投入

The honest baseline: for most B2B SaaS vendors an MCP server is defensive positioning that is becoming procurement table stakes - the competitive question has shifted from "supports MCP" to "supports MCP well."

Only a handful of vendors have published hard first-party impact data. Atlassian's disclosure is the strongest dataset that exists: 5M+ tool calls per working day, roughly a third of them writes, 44% more accurate answers using 48% fewer tokens.
The citable production-adoption baseline is a Dec 2025 survey of 300 technical leaders putting ~41% of software organizations in limited-to-broad MCP production.
Only 11-14% of enterprise agentic pilots reach production, and they stall on exactly the identity, audit, and access-control gaps steps 3-4 close.
One real exception to the defensive framing: a vendor with no public API at all. Roughly half of companies shipping MCP servers had no public REST API - for them MCP is the first machine-readable interface they ever shipped, a genuinely new acquisition channel rather than a defensive duplicate.
Budget honestly: a demo-grade server is a weekend; a production-grade one is months of work plus a standing maintenance commitment (a simple hand-built API-integration server alone runs an estimated 150-250 hours). This gap is what the hosting menu in step 4 prices.
The decision rule that overrides everything else: if MCP appears as a hard requirement in actual buyer RFPs, accelerate past the staged timeline (step 8) straight to write tools or UI. Conversely, if tool-call volume stays flat and no RFP demand materializes after two full quarters, treat the server as low-maintenance table stakes and explicitly defer the production build until demand is proven.

Ground every business case in references/evidence-and-do-not-cite.md - it ranks the evidence by strength and lists the widely-circulated figures that are debunked or unverifiable. Citing one of those poisons the whole case.

诚实的基线：对大多数 B2B SaaS 厂商来说，MCP 服务器是一种防御性定位，正在成为采购的入场券——竞争问题已经从“支持 MCP”转变为“很好地支持 MCP”。

只有少数厂商发布了可靠的第一方影响数据。Atlassian 的披露是现存最强的数据集：每个工作日超过500万次工具调用，其中约三分之一是写操作，答案准确率提高44%，同时 token 使用减少48%。
可引用的生产采用基线是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. Curate the tool surface

2. 策划工具表面

The comprehensive-vs-curated debate is resolved: curated won. Do not present this as an open trade-off.

The real-world median across 1,412 analyzed servers is 5 tools.
Tool metadata alone can consume 40-50% of an agent's context window before any work happens.
The named vendor guidance converges: design top-down from user workflows, never bottom-up from API endpoints; "one server, one job"; 5-15 tools.
Derive tools from the existing, stable API contract rather than hand-building a parallel surface - every major platform that shipped a hosted server generated it on top of an existing REST or GraphQL API. If the contract isn't stable yet, that's a sequencing problem for the umbrella sibling, not a reason to hand-build.
Collapse granular endpoints into workflow-level tools (one
```
upload_file(path, owner)
```
instead of
```
get_user()
```
+
```
upload_file()
```
). The agent's question is "what job can I do", not "what endpoints exist".
Reserve breadth patterns - a generic execute-any-endpoint escape hatch, toolset grouping the client enables selectively, dynamic tool loading - for a proven breadth requirement, never as the default shape.
Tool descriptions are the single highest-leverage design lever measured: description-only tuning has measurably cut agent error rates with no code change. Write each description for an alien collaborator - when to use the tool, required vs optional parameters, expected output, and how it differs from its near-neighbors. Budget real engineering time here.
Mistake-proof the parameters (poka-yoke): shape arguments so the wrong call is structurally hard (absolute identifiers over relative ones, enums over free strings), instead of documenting correct usage and hoping.
Mechanics:
- Verb-first, service-prefixed snake_case names (
```
acme_list_invoices
```
  ) - the namespace is shared with every other server the agent runs.
- Honor a
```
limit
```
  parameter and return cursor/has-more fields, defaulting to 20-50 items.
- Support JSON and Markdown response formats.
- Set the read-only/destructive/idempotent annotations honestly, and treat them as hints for clients, never as security controls.
- Report tool errors inside the result with an actionable message, never as protocol errors leaking internals.
Give every tool exactly one risk level (step 3). A tool that both reads and irreversibly writes is two tools.

全面 vs 策划的争论已经有了结论：策划胜出。不要把这说成一个开放的权衡。

在 1,412 个被分析的服务器中，现实世界的中位数是 5 个工具。
仅工具元数据就可能在任何工作发生之前消耗 Agent 上下文窗口的 40-50%。
知名厂商的指导趋于一致：从用户工作流自上而下设计，绝不要从 API 端点自下而上；“一个服务器，一个任务”；5-15 个工具。
从现有、稳定的 API 契约派生出工具，而不是手工构建一个并行的表面——每个发布托管服务器的主要平台都是在现有 REST 或 GraphQL API 之上生成它的。如果契约还不稳定，那是伞形兄弟 skill 的排序问题，而不是手工构建的理由。
将细粒度端点折叠为工作流级工具（一个
```
upload_file(path, owner)
```
而不是
```
get_user()
```
+
```
upload_file()
```
）。Agent 的问题是“我能做什么工作”，而不是“存在哪些端点”。
把广度模式——通用的执行任意端点后门、客户端选择性启用的工具集分组、动态工具加载——留给已被证明的广度需求，绝不要作为默认形态。
工具描述是已测量到的单一最高杠杆设计手段：仅调整描述就在不改变代码的情况下可衡量地降低了 Agent 错误率。为外星协作者写每个描述——何时使用该工具、必选与可选参数、预期输出，以及它与相近工具的区别。在这里投入真正的工程时间。
对参数做防错设计（poka-yoke）：塑造参数，使错误调用在结构上难以发生（绝对标识符优于相对标识符，枚举优于自由字符串），而不是记录正确用法然后寄希望于此。
机制：
- 动词优先、服务前缀的 snake_case 名称（
```
acme_list_invoices
```
  ）——命名空间与 Agent 运行的其他所有服务器共享。
- 遵循
```
limit
```
  参数并返回 cursor/has-more 字段，默认 20-50 条。
- 支持 JSON 和 Markdown 响应格式。
- 诚实设置只读/破坏性/幂等注解，并将它们视为对客户端的提示，绝不是安全控制。
- 在结果内部报告工具错误，附带可操作的消息，绝不能作为泄露内部信息的协议错误。
给每个工具恰好一个风险级别（第3步）。既读又不可逆写入的工具应该是两个工具。

3. Apply write-tool safety patterns

3. 应用写工具安全模式

Six named patterns, each proven by a specific vendor, detailed in references/write-safety-patterns.md. They stack rather than compete, so the ranking orders adoption - which to ship first, never which to ship instead. The axes disagree, so each gets its own line:

protection:

risk-tiered policy gates > human-in-the-loop approval > scoped credentials == read-only separation > idempotency + spend caps > dry-run preflight

effort:

risk-tiered policy gates > human-in-the-loop approval > dry-run preflight > idempotency + spend caps > scoped credentials == read-only separation

efficiency (protection per unit of effort):

scoped credentials == read-only separation > risk-tiered policy gates > idempotency + spend caps > dry-run preflight > human-in-the-loop approval

Human-in-the-loop approval sits second on effort even though building it is a day's work: its real cost is the standing human attention it consumes on every gated call, forever - which is exactly right for the calls that deserve it and unaffordable everywhere else. The scoped-credentials / read-only-separation tie is genuine on all three axes: both are server-side enforcement invisible to a well-behaved agent, both are configuration on the credential model rather than new machinery, and read-only separation is just scoped credentials taken to the extreme.

Default rung: scoped credentials plus a verified read-only mode from day one; human-in-the-loop approval on every contained write; irreversible or deployment-triggering tools disabled by default. The two top-efficiency patterns carry that combination, and approval is affordable alongside them only because early write volume is low - the condition that expires, and the one that promotes the starved option below.
Starved option: risk-tiered server-side policy gates (classify every call as Read Only / Minimal Impact / Contained Write / Critical, then pass, enrich with agent attribution plus async audit, or block before the handler runs). Highest protection and highest build effort at once, so the efficiency order never puts it first and it keeps getting deferred - promote it anyway the moment background agents run unattended, write volume grows past what humans can approve, or the first write incident lands. The vendor that built it did so after an unattended agent closed thousands of tickets.
The test every pattern must pass: enforcement lives server-side, so an end user cannot bypass it by switching clients. Client-side approval prompts and annotation hints fail this test on their own.
Name the industry gap honestly: undo/rollback is largely absent ecosystem-wide; attribution plus audit trails are the current substitute for true reversibility, not a solved answer.
This ranking is a default, not a law. Re-rank against question 3's write list and anything you know about the user - a product whose writes send emails or move money promotes dry-run and caps immediately; a pure-analytics product may never need more than the default rung.

六种命名模式，每种都由特定厂商验证，详见 references/write-safety-patterns.md。它们是叠加关系而非竞争关系，因此排序决定采用顺序——先交付哪个，绝不是用哪个替代哪个。各维度不一致，所以每个维度单独一行：

保护能力：

风险分级策略门控 > 人在环路审批 > 范围化凭据 == 只读分离 > 幂等性 + 消费上限 > 试运行预检

工作量：

风险分级策略门控 > 人在环路审批 > 试运行预检 > 幂等性 + 消费上限 > 范围化凭据 == 只读分离

效率（单位工作量提供的保护）：

范围化凭据 == 只读分离 > 风险分级策略门控 > 幂等性 + 消费上限 > 试运行预检 > 人在环路审批

人在环路审批在工作量维度上排在第二，尽管构建它只是一天的工作：它真正的成本是每一次被门控的调用都需要持续的人类注意力，永远如此——这对值得它的调用来说完全正确，但在其他任何地方都负担不起。范围化凭据/只读分离在所有三个维度上都是真正的并列：两者都是服务端强制，对表现良好的 Agent 不可见；两者都是凭据模型上的配置，而不是新机制；只读分离只是范围化凭据的极端化。

默认层级：范围化凭据加上从第一天起就经过验证的只读模式；对每个受控写操作进行人在环路审批；默认禁用不可逆或触发部署的工具。两个最高效率模式承载了这一组合，审批与之并存之所以可负担，只是因为早期写操作量很低——这个条件会消失，也正是提升下面被忽视选项的条件。
被忽视的选项：风险分级的服务端策略门控（将每次调用分类为只读/最小影响/受控写/关键，然后放行、用 Agent 归因加上异步审计丰富，或在处理器运行前阻止）。它同时具有最高的保护能力和最高的构建工作量，所以效率排序从不让它排在第一，它也不断被推迟——只要后台 Agent 无人值守运行、写操作量增长到人类无法审批，或者第一次写事故出现，就无论如何把它提升上来。构建它的厂商是在一个无人值守 Agent 关闭了数千张工单之后才这样做的。

每个模式必须通过的测试：强制在服务端，因此最终用户不能通过切换客户端绕过它。客户端审批提示和注解提示单独无法通过这个测试。

诚实地指出行业空白：撤销/回滚在整个生态系统中基本缺失；归因加审计追踪是当前对真正可逆性的替代，而不是已解决的答案。

这个排序是默认，不是法则。根据问题3的写操作清单以及你对用户的任何了解重新排序——写操作会发送电子邮件或转移资金的产品会立即提升试运行和上限；纯分析产品可能永远不需要超出默认层级。

4. Choose hosting and auth

4. 选择托管和认证

Three hosting postures, ranked:

effort:

self-hosted remote > remote managed platform > local stdio

value:

self-hosted remote == remote managed platform > local stdio

efficiency:

remote managed platform > local stdio > self-hosted remote

The value tie is genuine: the agent client sees the same OAuth-protected endpoint either way - hosting is invisible to the buyer until a custom server-side policy layer or residency constraint appears, which is precisely the promotion condition.

Default rung: remote managed platform. The protocol shipped four backward-incompatible revisions in its first twenty months; a managed platform absorbs that churn plus the mandatory OAuth machinery, and the economics tilt further toward managed once a few enterprise integrations exist. A hard deadline from question 6 reinforces this rung.
Starved option: self-hosted remote. Highest control and highest effort - months to production-grade plus standing maintenance. Promoted when the MCP server is the product (vertical SaaS, proprietary dataset, regulated workflow - agent access is what customers pay for), when a custom risk-tier policy layer from step 3 must run in your own infrastructure, or when existing multi-tenant edge infrastructure flips the effort line.
Step down to local stdio for developer-tool products operating on the user's own files and processes: single client, near-zero hosting effort, environment-variable credentials, and explicitly exempt from the OAuth requirements below. Rule it out entirely - not just demote it - when the audience is enterprise agent fleets, which consume hosted endpoints.
This ranking is a default, not a law; re-rank against questions 4-6.

Auth rules for any remote posture (spec revisions are date-stamped and move fast - always verify you're citing the latest one; this section is written against the 2026-07-28 revision):

The MCP server is an OAuth 2.1 resource server: it validates tokens, it never mints them. Designing the authorization server behind it is
```
samber/developer-platform-skills@oauth2-provider-design
```
territory; keep only the MCP-specific posture here.
Publish protected-resource metadata (RFC 9728).
- Require resource indicators (RFC 8707), and reject any token not issued specifically for this server - that is the mechanism stopping a token minted for one MCP server being replayed against another.
- The 2026-07-28 revision additionally mandates issuer validation (RFC 9207) and rewrites the transport core stateless: design every server instance interchangeable behind a plain load balancer, never session-pinned.
Never forward a caller's bearer token to an upstream API - the spec forbids this confused-deputy shape outright. Obtain your own upstream token via token exchange, acting as an OAuth client to the upstream system.
Read the compliance statistics as bimodal, never as one number: the often-quoted single-digit OAuth-compliance percentage is dragged down by a long tail of community stdio servers, while vendor-hosted servers default to OAuth 2.1. Implementing it properly is what passes enterprise security review - table stakes for this population, not an above-and-beyond flourish.
Hardening floor regardless of posture:
- Schema-validate every input, and bound sizes and ranges.
- Sanitize paths.
- Never leak internal errors to the client.
- On locally-run HTTP servers, validate the Origin header and bind to localhost (DNS-rebinding protection).

三种托管方式，按维度排序：

工作量：

自托管远程 > 远程托管平台 > 本地 stdio

价值：

自托管远程 == 远程托管平台 > 本地 stdio

效率：

远程托管平台 > 本地 stdio > 自托管远程

价值并列是真实的：无论哪种方式，Agent 客户端看到的都是同一个 OAuth 保护的端点——托管对买家不可见，直到出现自定义服务端策略层或驻留约束，这正是提升条件。

**默认层级：远程托管平台。**协议在最初二十个月内发布了四个不向后兼容的修订版本；托管平台吸收了这些变动以及强制性的 OAuth 机制，一旦存在几个企业集成，经济性就会进一步向托管倾斜。问题6中的紧迫截止日期会强化这一层级。
**被忽视的选项：自托管远程。**最高控制和最高工作量——达到生产级需要数月加上持续维护。当 MCP 服务器_就是_产品本身时（垂直 SaaS、专有数据集、受监管工作流——Agent 访问正是客户付费购买的东西），当第3步的自定义风险分级策略层必须运行在你自己的基础设施中，或者当现有的多租户边缘基础设施翻转了工作量曲线时，将其提升。
降级到本地 stdio适用于在用户自己的文件和进程上运行的开发者工具产品：单一客户端，接近零的托管工作量，环境变量凭据，并明确豁免下面的 OAuth 要求。当受众是企业 Agent 集群时，完全排除它——不仅仅是降级——因为它们消费托管端点。

这个排序是默认，不是法则；根据问题4-6重新排序。

任何远程方式的认证规则（规范修订带有日期戳且变化很快——始终确认你引用的是最新版本；本节基于 2026-07-28 修订版编写）：

MCP 服务器是 OAuth 2.1 资源服务器：它验证令牌，绝不签发令牌。设计其背后的授权服务器是
```
samber/developer-platform-skills@oauth2-provider-design
```
的领域；这里只保留 MCP 特定的姿态。
发布受保护资源元数据（RFC 9728）。
- 要求资源指示符（RFC 8707），并拒绝任何不是专门为此服务器签发的令牌——这就是阻止为一个 MCP 服务器签发的令牌被重放到另一个服务器的机制。
- 2026-07-28 修订版还强制要求签发者验证（RFC 9207），并将传输核心重写为无状态：设计每个服务器实例在普通负载均衡器后可互换，绝不进行会话粘滞。
绝不要把调用者的 bearer token 转发到上游 API——规范明确禁止这种混淆代理形态。通过令牌交换获取你自己的上游令牌，作为上游系统的 OAuth 客户端。
将合规统计视为双峰分布，而不是一个数字：经常被引用的个位数 OAuth 合规百分比被社区 stdio 服务器的长尾拉低，而厂商托管的服务器默认采用 OAuth 2.1。正确实现它才能通过企业安全审查——对于这一群体是入场券，而不是锦上添花。
无论哪种方式，加固底线：
- 对每个输入进行 schema 验证，并限制大小和范围。
- 清理路径。
- 绝不向客户端泄露内部错误。
- 在本地运行的 HTTP 服务器上，验证 Origin 头并绑定到 localhost（DNS 重绑定保护）。

5. Version the tool surface

5. 对工具表面进行版本化

Three layers, versioned separately - treating "MCP versioning" as one decision is the mistake:

Protocol version: date-based revisions with a formal feature lifecycle (Active → Deprecated → Removed, minimum 12 months between the last two). Track deprecations - the original transport, for instance, entered a grace window early in the protocol's life - and pin exact SDK versions for reproducible builds.
Your server's public API: ordinary semantic versioning. Renaming or removing a toolset name is a major version - agents key on names for discovery, so a rename breaks them silently. General deprecation machinery is
```
samber/developer-platform-skills@api-versioning-policy
```
territory; what stays here is the layer below.
The tool-surface contract itself - names, descriptions, schemas - which no spec standardizes yet. A tool's description is a compiled interface, not documentation: an analysis of 61,097 catalogued tools found a description wording change measurably alters the model's probability of selecting that tool - a breaking change even when the JSON schema is untouched, and one schema-diff CI cannot catch. Nothing breaks loudly anymore; the agent just adapts, sometimes wrongly.

Discipline for layer 3, since the spec won't impose it:

Default every change to additive, and alias old tool names instead of renaming.
Hash the full surface (names + descriptions + schemas) to catch silent drift.
Run golden-prompt behavioral tests in CI: a fixed set of representative tasks that must still select and call the right tools after any description edit.
Carry a version marker in the response envelope, and log it on every call.
Publish a deprecation window of at least 90 days with machine-readable response-header signaling.

Ship a description edit through the same review gate as a code change, never as a docs fix.

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

协议版本：基于日期的修订版本，带有正式的功能生命周期（活动 → 弃用 → 移除，后两者之间至少 12 个月）。跟踪弃用——例如原始传输在协议生命早期就进入了宽限期——并固定精确的 SDK 版本以实现可复现构建。
你的服务器公共 API：普通的语义化版本控制。重命名或移除工具集名称是主版本变更——Agent 依赖名称进行发现，所以重命名会静默破坏它们。通用的弃用机制是
```
samber/developer-platform-skills@api-versioning-policy
```
的领域；这里保留的是下面一层。
**工具表面契约本身——名称、描述、schema——目前没有任何规范对其进行标准化。**工具描述是编译后的接口，而不是文档：对 61,097 个已编目工具的分析发现，描述措辞的更改会可衡量地改变模型选择该工具的概率——即使 JSON schema 未变，这也是破坏性变更，而且是 schema diff CI 无法捕获的。不再有任何东西会大声崩溃；Agent 只是适应，有时是错误的。

由于规范不会强制，第3层的纪律：

默认每个更改都是增量的，并用别名保留旧工具名，而不是重命名。
对整个表面（名称 + 描述 + schema）进行哈希，以捕获静默漂移。
在 CI 中运行金标提示行为测试：一组固定的代表性任务，它们在任何描述编辑后仍然必须选择和调用正确的工具。
在响应信封中携带版本标记，并在每次调用时记录。
发布至少 90 天的弃用窗口，并提供机器可读的响应头信号。

描述编辑要像代码更改一样通过相同的审查门，绝不能作为文档修复。

6. Publish for discoverability

6. 发布以获得可发现性

Publish to the official MCP registry under a DNS-verified reverse-domain namespace. Know what that listing signals: the registry is a metadata catalog with namespace-ownership proof and community moderation - it certifies nothing about security, so don't lean on listing as a trust claim to buyers.
The official registry is necessary, not sufficient: human developers browse the curated third-party directories, so fan the listing out to them (automation tools exist for the fan-out) rather than stopping at one entry.
Expect large customers to mirror the registry into private, allowlisted internal catalogs. Your listing's metadata and version history must stay accurate specifically because it gets re-consumed by machines applying policy, not just browsed.
A first-party server, once published, tends to displace community-built substitutes for the same product rather than compete alongside them - if question 1 surfaced a community server, publishing well is also how you retire the unofficial surface agents currently trust.

在 DNS 验证的反向域名命名空间下发布到官方 MCP 注册表。知道该列表意味着什么：注册表是一个带有命名空间所有权证明和社区审核的元数据目录——它不认证任何安全相关事项，所以不要把列表作为对买家的信任声明。
官方注册表是必要的，但不是充分的：人类开发者会浏览经过策划的第三方目录，所以把列表分发到这些目录（有自动化工具可以分发），而不是只停留在一条记录上。
预计大客户会将注册表镜像到私有的、允许列表内的内部目录。你的列表元数据和版本历史必须保持准确，正是因为它会被应用策略的机器重新消费，而不仅仅是被浏览。
第一方服务器一旦发布，往往会取代同产品的社区构建替代品，而不是与它们竞争——如果问题1发现了社区服务器，做好发布也是你淘汰 Agent 当前信任的非官方表面的方式。

7. Measure agent adoption

7. 衡量 Agent 采用情况

Instrument tool calls as OpenTelemetry spans (session → tool invocation → downstream operation) rather than a bespoke event schema - the audience for this data in an enterprise deployment is the customer's existing observability stack, not only your dashboard. An auto-instrumenting wrapper beats hand-instrumenting each tool as the surface grows.
The converged metric set: call volume, success/error rate, per-tool usage, active users, and client distribution (which agent client calls in). The purpose is dual - confirm the server is used at all, and see whether adoption is broad or concentrated.
Registry listings and package downloads measure install interest, never runtime usage - only in-server telemetry answers the adoption question. Don't let a download count into a business case as a usage figure.
Assume your telemetry is not the only visibility layer: large customers front your server with their own gateway. Design your metrics to be correlatable (stable tool names, request ids), not exclusive.
When the data is good, publish it - the strongest ROI evidence in the ecosystem is one vendor's first-party disclosure: call volume, write share, non-technical-user share, enterprise share, retention by cohort, accuracy, and token-efficiency gains. That disclosure shape is the model to match, detailed in references/evidence-and-do-not-cite.md.
Surfacing per-customer integration failures back to the developers who own them is
```
samber/developer-platform-skills@integration-error-observability
```
territory.

将工具调用作为 OpenTelemetry span 进行埋点（会话 → 工具调用 → 下游操作），而不是使用定制的 event schema——在企业部署中，这些数据的受众是客户现有的可观测性栈，而不仅仅是你的仪表盘。随着表面增长，自动埋点包装器优于手动为每个工具埋点。
收敛的指标集：调用量、成功/错误率、每个工具的使用量、活跃用户和客户端分布（哪个 Agent 客户端在调用）。目的是双重的——确认服务器确实被使用，并了解采用是广泛的还是集中的。
注册表列表和包下载衡量的是安装兴趣，绝不是运行时使用情况——只有服务器内遥测才能回答采用问题。不要让下载次数作为使用数字进入商业案例。
假设你的遥测不是唯一的可见性层：大客户会用自己的网关前置你的服务器。设计你的指标使其可关联（稳定的工具名、请求 ID），而不是排他的。
当数据良好时，发布它——生态系统中最强的 ROI 证据是一家厂商的第一方披露：调用量、写操作占比、非技术用户占比、企业占比、按群组划分的留存、准确率和 token 效率提升。这种披露形状是要匹配的模型，详见 references/evidence-and-do-not-cite.md。
将每个客户的集成失败反馈给负责的开发者是
```
samber/developer-platform-skills@integration-error-observability
```
的领域。

8. Roll out in stages

8. 分阶段推出

Full stage detail, thresholds, and the MCP Apps decision live in references/rollout-stages-and-thresholds.md. The skeleton:

Read-only launch: the curated 5-15 tools, OAuth 2.1 from day one, OpenTelemetry from the first call, registry publication. Proceed only on sustained tool-call volume from real agent clients (not demo spikes) with tool-error rate under 2%.
Graduated writes: risk tiers enforced server-side, approval on contained writes, critical tools disabled by default, scoped credentials, attribution plus async audit, idempotency keys, dry-run where feasible. Expand write scope only on a clean audit trail, zero unattributed writes, and proven approval-flow reliability.
Differentiate: an interactive MCP Apps UI for the single highest-value workflow (approval screen, filterable dashboard, configuration wizard) - after validating that target customers' security teams accept iframe-rendered third-party UI in their assistant, which is still an open question, not a settled yes. Institutionalize the layer-3 versioning discipline and publish impact metrics.

The RFP-pressure override from step 1 cuts across this sequence in both directions: hard procurement demand accelerates past stages; two flat quarters park the server at stage 1 as maintained table stakes.

完整的分阶段细节、阈值和 MCP Apps 决策见 references/rollout-stages-and-thresholds.md。骨架如下：

只读上线：策划好的 5-15 个工具，从第一天起使用 OAuth 2.1，从第一次调用起使用 OpenTelemetry，注册表发布。只有在真实 Agent 客户端持续产生工具调用量（不是演示尖峰）且工具错误率低于 2% 时才继续。
渐进式写操作：服务端强制风险层级，受控写操作需要审批，关键工具默认禁用，范围化凭据，归因加异步审计，幂等键，在可行处进行试运行。只有在审计追踪干净、零未归因写操作、并且审批流程可靠性得到证明时，才扩大写操作范围。
差异化：为单个最高价值工作流提供交互式 MCP Apps UI（审批界面、可筛选仪表盘、配置向导）——在验证目标客户的安全团队接受其助手中 iframe 渲染的第三方 UI 之后，这仍然是一个开放的问题，而不是已经确定的“是”。将第3层版本化纪律制度化，并发布影响指标。

第1步的 RFP 压力覆盖在这个顺序中双向起作用：硬性采购需求会加速越过阶段；两个平稳季度会把服务器停在阶段1，作为被维护的入场券。

Failure modes

失败模式

Anti-pattern checklist - each is a direct review finding:

The comprehensive-mirror trap: one tool per API endpoint. Agents mis-pick among near-duplicates and context drowns in metadata before any work happens.
A destructive tool that is live-only - no dry-run, no approval gate, no disabled-by-default tier. Community servers have shipped order-cancellation tools that silently email real customers.
A hand-built parallel surface where a derived one was available - double maintenance and guaranteed drift from the real API contract.
A tool-description edit shipped as a docs fix, bypassing review and behavioral tests, silently changing which tools agents select.
Forwarding the caller's bearer token upstream - the spec-forbidden confused-deputy shape.
Trusting a read-only flag without verifying it: a documented vendor bug shipped write tools despite the flag being set. Test the lockdown, don't configure it and assume.
Treating tool annotations (read-only/destructive hints) as security controls - they are advisory metadata for clients; enforcement belongs server-side.
Citing a debunked adoption statistic in the business case - see the do-not-cite list in references/evidence-and-do-not-cite.md.
A session-pinned server design - the protocol's stateless rewrite made instance-interchangeability the baseline expectation.

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

全面镜像陷阱：每个 API 端点对应一个工具。Agent 会在近似重复项中误选，上下文在开始任何工作之前就被元数据淹没。
只有在线模式、没有试运行、没有审批门、没有默认禁用层级的破坏性工具。社区服务器曾经发布过会静默向真实客户发送电子邮件的订单取消工具。
在可以获得派生表面的地方手工构建并行表面——双重维护，并且必然与真实 API 契约产生漂移。
把工具描述编辑作为文档修复发布，绕过审查和行为测试，静默改变 Agent 选择哪些工具。
将调用者的 bearer token 转发到上游——规范禁止的混淆代理形态。
没有验证就信任只读标志：一个已记录的厂商 bug 在标志已设置的情况下仍然发布了写工具。要测试锁定，不要配置完就假设。
将工具注解（只读/破坏性提示）视为安全控制——它们只是给客户端的建议性元数据；强制属于服务端。
在商业案例中引用已被揭穿的采用统计——参见 references/evidence-and-do-not-cite.md 中的“不要引用”列表。
会话粘滞的服务器设计——协议的无状态重写使实例可互换成为基线预期。

Measurement

衡量

Four binary gates - iterate the design until all pass:

Safety coverage: every write-capable tool carries exactly one risk tier and at least one named pattern from step 3's taxonomy, and every irreversible tool is approval-gated or disabled by default. One uncovered write tool fails the gate.
Auth conformance (remote servers): protected-resource metadata published, token audience validated, no bearer-token passthrough upstream. Binary per the spec's own MUSTs.
Evidence hygiene: zero figures from the do-not-cite list in any produced business case or deliverable.
Curation: the launched surface stays within 5-15 tools unless a proven breadth requirement is documented, with every tool named per step 2's conventions.

The stage-transition thresholds (error rate under 2%, clean audit trail) are based on one vendor's read-only-first practice, not an industry standard - treat them as defaults to calibrate against your own first month, and the adoption metric set from step 7 as trends to baseline, never pass thresholds.

四个二元门——迭代设计直到全部通过：

安全覆盖：每个支持写操作的工具恰好携带一个风险层级和第3步分类中的至少一个命名模式，每个不可逆工具都经过审批门控或默认禁用。一个未覆盖的写工具就算失败。
认证一致性（远程服务器）：发布受保护资源元数据，验证令牌受众，不向上游传递 bearer token。按规范自身的 MUST 二元判定。
证据卫生：任何商业案例或交付物中引用的数字都不能来自“不要引用”列表。
策划：已上线的表面保持在 5-15 个工具以内，除非记录了已被证明的广度需求，并且每个工具都按照第2步的约定命名。

阶段转换阈值（错误率低于 2%、干净审计追踪）基于一家厂商的只读优先实践，而不是行业标准——把它们视为需要根据你自己的第一个月校准的默认值，并把第7步的采用指标集视为要建立基线的趋势，绝不是通过/不通过的阈值。

Invocation examples

调用示例

"We have a stable REST API and customers asking for agent access - design our MCP server: which tools do we expose and how do we secure the write ones?"
"Our MCP server mirrors 60 API endpoints and agents keep calling the wrong tool - redesign the surface."
"Agents should be able to create and cancel orders through our MCP server - design the safety, approval, and audit model before we ship it."
"Leadership wants an MCP server because a competitor shipped one - how much should we actually invest and in what order?"

“我们有一个稳定的 REST API，客户要求 Agent 访问——设计我们的 MCP 服务器：我们暴露哪些工具，如何保护写操作工具？”
“我们的 MCP 服务器镜像了 60 个 API 端点，Agent 总是调用错误的工具——重新设计表面。”
“Agent 应该能够通过我们的 MCP 服务器创建和取消订单——在发布之前设计安全、审批和审计模型。”
“领导层想要 MCP 服务器，因为竞争对手发布了——我们实际上应该投入多少，按什么顺序？”

References

参考

references/write-safety-patterns.md - the six write-safety patterns with their named vendor implementations, the negative example, and the approval-primitive detail.
references/rollout-stages-and-thresholds.md - the three rollout stages with go/no-go thresholds, and the MCP Apps UI decision.
references/evidence-and-do-not-cite.md - adoption/ROI evidence ranked by strength, the disclosure model to match, and the debunked figures never to cite.