# 模块 12：MCP 也必须沉淀为能力资产

<div class="mt-6 text-sm">

MCP 不是一条连接地址，也不是把所有外部系统工具都暴露给 Agent。

它是“可被 Agent 调用的外部能力”，因此同样需要清楚的输入输出、权限、审计、失败处理和验证边界。

</div>

<div class="grid grid-cols-5 gap-3 mt-8 text-sm">
<div class="p-3 rounded-xl bg-blue-500/10 border border-blue-500/30">能力说明</div>
<div class="p-3 rounded-xl bg-emerald-500/10 border border-emerald-500/30">工具契约</div>
<div class="p-3 rounded-xl bg-amber-500/10 border border-amber-500/30">权限范围</div>
<div class="p-3 rounded-xl bg-red-500/10 border border-red-500/30">失败降级</div>
<div class="p-3 rounded-xl bg-purple-500/10 border border-purple-500/30">验收夹具</div>
</div>

<!--
逐字稿：MCP 不是一条配置地址，也不是把外部工具全部暴露给 Agent。它把外部系统能力带入任务，因此必须像代码接口一样说明输入、输出、权限、副作用、错误和验证。能连通只说明技术上可访问，不能说明业务上可以安全调用。

当前课程已有 CLI / MCP / Skill 封装决策表，说明 MCP 适合跨系统取数、浏览器等交互式外部能力。但决策表只是入口，不足以保证某个 MCP Server 可安全复用。
-->

---

# MCP 资产包应包含什么？

<div class="mt-5 text-xs">

```text
mcp-assets/
├── README.md                       # 接入边界、适用场景与不适用场景
├── MCP能力契约.template.md          # 服务、工具、输入、输出、错误与审计
├── MCP工具权限与验收清单.md          # 最小授权、敏感数据与副作用验证
├── MCP故障降级清单.md                # 超时、鉴权、限流、不可用时的处理
└── fixtures/                        # 完整、拒绝、失败与脱敏结果样例
```

</div>

<div class="mt-6 p-3 rounded-xl bg-emerald-500/10 border border-emerald-500/30 text-sm">
连接配置只说明“连得上”；资产包还要说明“什么时候可以调用、调用后能相信到什么程度”。
</div>

<!--
逐字稿：一份 MCP 资产包至少要让使用者知道五件事：它适合什么场景，工具契约是什么，权限如何控制，故障如何降级，以及如何用夹具验收。这里不预置任何业务服务器、地址或密钥，因为这些必须由具体项目在合规范围内提供。配置能连上只是起点，调用后的可信范围才是重点。

本课件交付包已补充前三份真实模板文件。没有配置任何业务服务器、Token 或外部地址；这些必须由使用项目在合规范围内另行提供。
-->

---

# 每个 MCP 工具都需要输入输出契约

<div class="mt-5 text-xs">

| 契约字段 | 必须说明的问题 |
|---|---|
| 工具名称与用途 | 它解决哪一类外部事实或操作？ |
| 输入 | 必填字段、格式、数据范围和敏感参数处理方式是什么？ |
| 输出 | 返回哪些已确认字段，哪些字段可能为空或过期？ |
| 副作用 | 只读、可逆写入，还是不可逆操作？ |
| 错误 | 鉴权、限流、超时、无结果和服务错误如何区分？ |
| 审计 | 调用主体、目标对象、时间和结果如何留痕并脱敏？ |

</div>

<div class="mt-6 p-3 rounded-xl bg-amber-500/10 border border-amber-500/30 text-sm">
工具名叫“查询”不代表一定只读；是否有副作用必须由契约明确，而不是让 Agent 猜测。
</div>

<!--
逐字稿：每个 MCP 工具都必须有独立契约。名称叫“查询”并不代表一定只读，返回字段也不一定都新鲜可靠；因此要明确输入范围、输出可信度、副作用、错误类型和审计信息。Agent 不能根据工具名自行推断权限或风险。

在真实项目中，MCP 工具的名字可能不准确或随版本变化，因此不根据名字推断权限。契约必须单独说明每个工具的读写性质、输入范围、输出可信度和错误语义。
-->

---

# Agent 调用 MCP 时，权限要再收一层

<div class="mt-5 text-xs">

| 外部能力类型 | Agent 默认策略 | 必须补充的保护 |
|---|---|---|
| 读取公开或脱敏信息 | 可按职责开放 | 结果范围、来源时间与引用记录 |
| 读取受限业务信息 | 仅在明确授权后调用 | 数据范围、脱敏与审计 |
| 创建草稿或临时资源 | 需要用户确认 | 幂等键、撤销方式和可见结果 |
| 修改业务状态或数据 | 不作为默认工具权限 | 二次确认、最小范围和回滚路径 |
| 删除、发布、外发 | 不交给通用 Agent | 专用流程与人工最终确认 |

</div>

<div class="mt-6 p-3 rounded-xl bg-red-500/10 border border-red-500/30 text-sm">
自定义 Agent 的工具选择只是第一层；MCP 工具自身仍要定义调用级的权限与确认边界。
</div>

<!--
逐字稿：Agent 的工具选择只是第一层权限控制，MCP 调用本身还需要第二层边界。公开脱敏信息可以按职责读取，受限信息必须明确授权，创建临时资源需要确认，修改业务状态必须有更严格的最小范围和回滚条件，删除、发布和外发不应交给通用 Agent。角色权限和调用权限必须同时收敛。

这页与模块 9 的最小授权形成两层保护：第一层是 Agent 能否看到这个 MCP 工具，第二层是 MCP 服务是否允许本次调用的身份、数据范围和操作类型。
-->

---

# MCP 的验收不只检查“调用成功”

<div class="mt-5 text-xs">

| 验收夹具 | 预期行为 |
|---|---|
| 合法完整请求 | 返回结构符合契约，来源和时间可追溯 |
| 缺少必填参数 | 拒绝并说明字段缺口，不自动补造参数 |
| 越权请求 | 拒绝或要求确认，不泄露超范围数据 |
| 限流、超时或服务不可用 | 区分故障类型，输出降级结论，不伪装成无结果 |
| 敏感字段返回 | 按契约脱敏，日志不写入密钥、Token 或完整隐私数据 |
| 有副作用的重复调用 | 符合幂等或明确阻止重复执行 |

</div>

<div class="mt-6 p-3 rounded-xl bg-blue-500/10 border border-blue-500/30 text-sm">
MCP 失败时，Agent 应该报告“外部事实未取得”，而不是用已有代码或常识补出一个答案。
</div>

<!--
逐字稿：MCP 的验收不能只看调用是否返回成功。合法请求要验证返回结构和来源，缺参数要明确拒绝，越权请求不能泄露数据，超时和限流不能伪装成无结果，敏感字段必须脱敏，有副作用的调用还要验证幂等。外部事实没取到时，Agent 应直接说明缺口，而不是用常识补答案。

这里的夹具可用于人工试跑或自动化契约测试。重点是身份、范围、错误和副作用边界，不是仅看 HTTP 或工具调用是否返回成功。
-->

---

# MCP 能力资产的交付标准

<div class="mt-8 text-lg">
一份 MCP 资产的完成标准，不是 Agent 调用成功，而是能力、契约、权限、故障处置和验证边界均可被复核。
</div>

<div class="grid grid-cols-5 gap-3 mt-8 text-sm">
<div class="p-3 rounded-xl bg-blue-500/10 border border-blue-500/30">适用边界</div>
<div class="p-3 rounded-xl bg-emerald-500/10 border border-emerald-500/30">工具契约</div>
<div class="p-3 rounded-xl bg-amber-500/10 border border-amber-500/30">调用权限</div>
<div class="p-3 rounded-xl bg-red-500/10 border border-red-500/30">故障降级</div>
<div class="p-3 rounded-xl bg-purple-500/10 border border-purple-500/30">验收夹具</div>
</div>

<!--
逐字稿：MCP 模块到这里的结论是：一份 MCP 资产不能只交付连接配置或工具名称。它至少应写清适用边界、每个工具的输入输出契约、调用权限、超时和故障时的降级方式，以及可重复执行的验收夹具。

这五项信息让 Agent 对外部能力的使用可控、可审查。没有它们，即使调用成功，也无法判断是否取到了可信事实、是否越权，或是否产生了无法回退的副作用。
-->