MCP 工具调用设计：从接口定义到权限控制

AI 应用如果只负责生成文本，功能相对简单。但当它需要查询数据库、读取文件、创建工单或触发部署时，就必须和外部工具建立连接。

MCP（Model Context Protocol）提供了一种比较统一的方式，让模型通过 MCP Server 获取资源和调用工具。它解决的不只是“怎么调用接口”，还涉及工具描述、参数结构和执行结果如何返回给模型。

MCP 中的三类对象

MCP 常见的核心对象可以分成三类：

Resources：模型可以读取的资源，例如文档、文件和查询结果
Tools：模型可以请求执行的动作，例如搜索、创建记录和发送通知
Prompts：可以复用的提示模板

简单来说，资源更偏向“读什么”，工具更偏向“做什么”，提示模板则是“如何组织一次任务”。把这几类对象区分开后，应用的职责会更清晰。

工具描述为什么重要

模型是否能正确调用工具，很大程度上取决于工具描述是否清楚。一个工具至少需要明确：

工具名称和用途
参数名称和数据类型
必填参数
参数取值范围
可能返回的结果
失败时的错误信息

例如，一个查询订单的工具，不应该只暴露一个模糊的 query 字符串，而应该明确订单号、用户标识和时间范围分别是什么。参数越清晰，模型越不容易把自然语言中的内容填错位置。

{
  "name": "get_order",
  "description": "根据订单号查询订单状态",
  "inputSchema": {
    "type": "object",
    "properties": {
      "orderId": {
        "type": "string",
        "description": "用户提供的订单号"
      }
    },
    "required": ["orderId"]
  }
}

工具调用不是普通函数调用

普通函数调用通常由开发者决定什么时候执行，参数也由代码生成。而 Agent 工具调用中，模型会根据上下文判断是否需要使用工具，因此必须考虑误调用和重复调用。

比较安全的流程一般包括：

模型提出工具调用请求
应用校验工具名称和参数
根据权限判断是否允许执行
对有风险的操作请求用户确认
执行工具并记录结果
将结果返回给模型继续处理

模型请求工具
      ↓
参数校验
      ↓
权限检查
      ↓
用户确认（可选）
      ↓
执行并记录

尤其是发送邮件、修改数据、删除文件和触发发布这类有副作用的操作，不能因为模型生成了调用参数就直接执行。

资源和工具要分开考虑

如果只是让模型读取项目文档，可以把文档作为 Resource 暴露；如果需要让模型修改项目配置，则应该设计成 Tool，并增加权限和审计。

这种区分有助于控制风险：只读资源的影响范围通常比较小，而工具可能直接改变外部系统状态。应用需要知道哪些操作可以自动完成，哪些操作必须经过人工确认。

错误处理和日志

工具调用失败时，不要只返回一个“执行失败”。更好的错误信息应该包括失败原因、是否可以重试，以及是否需要用户补充信息。

同时，工具调用过程最好记录下来，包括调用者、参数摘要、执行时间、结果状态和错误信息。这样既方便排查问题，也能发现模型是否反复调用某个工具或频繁传入错误参数。

总结

MCP 的价值不只是给 Agent 增加几个工具，而是为模型和外部系统之间建立相对清晰的边界。工具描述决定模型能不能正确使用，参数校验决定调用是否安全，权限控制和日志则决定这个系统能不能真正放进业务环境。

在开发 AI 应用时，我会把工具当成正式的后端接口来设计，而不是把它看成 Prompt 的附属功能。模型可以帮助决定“什么时候调用”，但最终是否允许执行，仍然应该由应用本身负责。