从 REST 到 MCP：设计思维的转变

Sentry、Notion、GitHub、Stripe 的实践案例表明，MCP 的消费者（AI 代理）与 REST 的消费者（人类或预编译客户端）截然不同，因此接口设计也必须适配代理在运行时选择操作的特点。本文提炼了 9 条设计原则，对比同一公司在两种接口上的实现差异。

1. 围绕意图设计：MCP 工具应代表一个连贯的用户意图，将编排逻辑推入服务端。例如 Sentry 的 create_project 工具，一次调用即可完成项目创建、仓库关联、密钥获取等原本需要多个 REST 端点的操作。
2. 批量重复操作：代理常需一次创建大量资源，批量工具可减少上下文消耗并降低遗漏风险。Notion 的 notion-create-pages 直接接受数组，而非每次调用创建单页。
3. 合并紧密相关操作：增/改接口常共享参数与语义，合并为单一工具（如 GitHub 的 issue_write 通过 method 参数区分）可节省上下文并提升选择准确性。
4. 明确语义：MCP 工具应将 HTTP 状态码隐含的信号转化为显式的输入/结果，提供错误码、变化状态、恢复路径等结构化信息。
5. 文档即控制流：MCP 工具的描述直接影响代理的选择与参数构建，文档变更可能引发生产行为变化，需像代码一样测试。
6. 建议下一步动作：效仿 HATEOAS，在响应中返回 suggestedActions，引导代理执行合理的下一步。Sentry 的 get_trace_details 即提供了这一结构。
7. 支持字段过滤：MCP 工具应允许代理只请求当前决策所需字段，避免无效字段占用上下文。
8. 保护危险操作：工具描述可要求代理先警告用户并获取确认，结果中提供备份/恢复路径。
9. 渐进暴露工具：对大型 API，使用搜索类元工具先定位方法，再加载具体参数，避免一次性加载所有定义耗费上下文。

这一对比并非穷举，安全、缓存等维度需另行讨论。REST 客户端运行预编译逻辑，代理运行时选择操作，直接包裹每个 REST 端点会保留为不同消费者设计的界面，MCP 接口必须承载更多原由代码提供的知识。

#开发者 #工具 #MCP #REST #Sentry #Notion #GitHub #Stripe #架构设计
@DevToolboxHub