MCP、API、Webhook 选择与凭证边界

用户真实问题

想把 WorkBuddy 与外部系统连接起来时，常见问题不是“哪种技术最先进”，而是：已有官方连接器要不要重复开发？MCP、API 和 Webhook 的方向有什么不同？凭证由谁保管？测试时会不会误写、误发或重复执行？

本页把选择和安全边界放在一起。Connector、MCP、API、Webhook 不是一个统一实现，也不能因为都能“接外部系统”就互相替代。

产品事实与实施方法：连接器和 MCP 的产品入口、支持范围、认证方式以当前 WorkBuddy 版本与实际权限为准；外部 API 和 Webhook 的比较是通用接入方法。当前公开资料没有为所有租户确认一个统一的 Webhook 创建入口，因此本文不会把“有 Webhook 服务器”写成 WorkBuddy 的固定内置能力。

一、先理解四类方式

方式	更适合什么	谁主动发起	通常的交互形态	主要治理点
Connector	产品已经提供、经过组织批准的常用外部服务	WorkBuddy 任务调用外部服务	按当前连接器能力读或执行	账号授权、数据范围、动作权限和解绑
MCP	需要按标准工具、资源或提示原语接入的服务	Host / Client 按任务调用 Server	可暴露多个工具或资源，是否持续连接看实现	Server 来源、工具清单、运行位置和最小权限
API	需要定制请求、业务系统接口或明确数据契约	调用方向 Endpoint 发请求	一次请求一次响应或长任务状态	Endpoint、Token、配额、数据外发和错误处理
Webhook	需要在事件发生时通知另一个系统	事件发生方推送到接收端	事件驱动、异步、通常单向通知	接收地址、签名、重放、幂等、失败重试和撤销

这张表用于设计和排查，不暗示四种方式都由 WorkBuddy 在同一页面提供。Connector 是产品接入能力；MCP、API 和 Webhook 是否可用、由谁配置以及能做哪些动作，要回到当前官方文档、租户策略和实际测试。

二、用决策树减少重复接入

按下面顺序判断：

1. 已有官方 Connector？ 如果目标服务已经有组织批准的 Connector，先评估它是否覆盖任务所需的读取或操作范围。能用现有连接器完成，就不要为同一需求再维护一套 API 或 MCP。
2. 需要标准化工具或资源？ 如果服务以工具、资源或提示模板的形式提供，并且当前产品版本支持相应 MCP 接入，再核对 Server 来源、版本、权限和运行位置。不要因为出现“MCP”字样就默认所有 Server 都可信。
3. 需要定制业务请求？ 如果已有明确的 Endpoint、请求字段和返回契约，评估 API。先拆分读取、写入和外发权限，避免把一把高权限密钥交给整个任务链。
4. 需要事件到达时通知？ 如果业务是“系统发生事件后通知接收方”，再评估 Webhook。先确认组织有受控的接收端、签名校验、重放防护和幂等处理；如果没有，不要为了追求实时而临时暴露公网端点。
5. 没有稳定契约？ 先做人工导入或低频测试，不要同时引入四种接入方式。先把数据、责任和失败条件弄清楚。

最终选择可写成一行：目标系统 → 交互方向 → 数据范围 → 认证方式 → 允许动作 → 失败与撤销负责人。这比只记录“我们用了 MCP / API”更容易审计。

三、凭证边界：谁能用不等于谁能看

常见凭证包括 API Key、Token、OAuth 授权和 Webhook Secret。无论使用哪一种，都应把“保存位置、注入方式、有效期、轮换、撤销和日志”写进接入卡。

凭证问题	最小要求	明确禁止
权限	只授予任务所需资源和动作，读写分开	用生产管理员凭证做第一次测试
保存	使用当前产品或组织批准的安全配置、密钥管理或环境变量	写进 Prompt、Markdown、截图或仓库
传播	只让必要的任务、服务和负责人可用	把长期 Token 复制给所有协作者
生命周期	有创建人、到期时间、轮换和撤销负责人	测试结束后永久保留无 owner 凭证
日志	检查请求、错误和回调日志不含 Secret 或敏感字段	直接把完整请求和响应贴到公开排障页
事件入口	校验签名、来源、时间戳和重复事件	仅凭 URL 能被调用就视为可信

环境变量只是降低明文暴露的一种工程方法，不等于已经完成权限治理。仍要检查谁能读取运行环境、日志是否会打印值、备份是否包含密钥，以及撤销后是否还有任务在重试。

四、七步测试顺序

将接入拆成逐步放权的测试，不要一开始验证“完整自动化”：

1. Connectivity。 用测试地址或组织批准的环境确认网络、Endpoint、Server 或接收端可以到达。
2. Auth。 使用短期、低权限凭证验证认证成功和失败路径，记录错误但不记录完整 Secret。
3. Read。 先读取一条脱敏或公开测试资料，核对账号、组织、字段和数据范围。
4. Write。 若确实需要写入，使用测试对象，先预览请求和目标，再人工确认一次；不要直接测删除或群发。
5. Failure。 主动验证超时、限流、字段错误、服务不可用、权限不足和部分失败。
6. Revoke。 撤销或轮换凭证后再次调用，确认旧凭证不能继续工作，相关任务会停止或转人工。
7. Re-auth。 用新凭证重新授权，确认最小权限、日志和恢复步骤都可执行。

测试记录至少包含：时间、版本、环境、输入、动作、结果、错误、文件变化、外部副作用、审批人和下一步。没有测试证据时，状态应是“待验证”，而不是“接入完成”。

五、进入生产前补上运行边界

连接成功只是起点。进入真实任务前，还要把以下问题与自动化监控、重试、幂等与停用的状态和停用方法对齐：

• Rate limit。 达到配额时是排队、降级还是停止？谁收到告警？
• Timeout。 请求超时后是否可能已在外部系统成功？重试前如何查询状态？
• Retry。 只对可安全重试的错误重试，设置上限和退避，不无限重放。
• Idempotency。 写入或通知要有业务幂等键，避免网络重试造成重复创建或重复发送。
• Audit。 记录谁、何时、以什么版本、用什么凭证范围发起了什么动作，不把密钥写进审计日志。
• External dependency。 外部系统不可用时保留草稿或队列，明确人工接管和恢复顺序。
• Human approval。 删除、付款、外发、权限变更和跨组织读取必须单独确认。

如果这些问题还没有答案，先让接入只生成分析或草稿，不开放真实写入和自动通知。

验收清单

• [ ] 选择理由与四类方式的交互方向、数据范围和责任边界一致；
• [ ] Connector / MCP / API / Webhook 的当前可用性已经通过官方文档或租户实测核对；
• [ ] Endpoint、Server、接收端、数据路径和外部依赖有负责人；
• [ ] 凭证使用最小权限，有保存、轮换、撤销和到期方法；
• [ ] 完成连接、认证、读取、写入、失败、撤销和重新授权测试；
• [ ] 日志、截图、Prompt、仓库和公开产物没有 Secret、API Key 或长期 Token；
• [ ] 限流、超时、重试、幂等、审计和人工批准规则已写清；
• [ ] 生产任务有停用、回退和外部系统恢复路径。

相关内容

• 第 7 章：连接器与 MCP
• 第 9 章：外部 API、密钥与权限边界
• Connector / MCP 权限验证与回收
• 自动化监控、重试、幂等与停用
• 如何接入连接器或 MCP，并控制权限和数据范围
• 企业版连接器与 MCP 怎么使用？
• SaaS 中 Connector/MCP 的数据路径怎么核对？

来源引用

• SRC-UPSTREAM-CH07：连接器、MCP、授权和只读试跑的基础方法。
• SRC-UPSTREAM-CH09：外部 API、密钥、费用、日志、测试和撤销边界。
• SRC-TENCENT-WORKBUDDY-ENTERPRISE-DOCS-1831-202608：企业版连接器、组织权限和产品入口的官方核对入口。
• SRC-TENCENT-WORKBUDDY-ENTERPRISE-WP-202608-V1：企业数据路径、资产和治理边界的公开资料。

内容版本与核对日期

• 内容版本：0.1.0
• 最后核对日期：2026-09-26
• 适用版本状态：连接器、MCP、API、Webhook、认证字段和租户权限以当前产品版本与组织策略为准。
• 来源提交版本：6b5e2403f0f2ad5d3f7ab7a67e9c4d4113583ff3