MCP 工具定制开发前,怎样把业务接口写成工具契约
MCP 工具定制开发前,应把一个业务动作写成输入、输出、权限、错误和验收约定,而不是只说“做个 MCP 接 ERP”。协议让模型发现和调用工具,业务安全仍由工具服务承担。本文以合成订单状态查询为例,提供可交给开发方估算的 JSON 契约,既不开放任意 SQL,也不执行真实业务操作。
一个工具先做一件可验收的事
工具名采用明确动作,例如 query_order_status_demo,描述说明只查询获准组织内指定订单的状态与交期。不要把查询、创建、修改和发送消息塞进同一个万能工具,模型难以判断副作用,供应商也难以估算失败处理。输入只允许订单号,组织与请求人从服务端已验证上下文获得,模型不能通过参数指定管理员或切换租户。
MCP 2025-06-18 工具规范定义工具名称、说明、inputSchema 和可选 outputSchema 等结构。本文选择该明确规范版本作为讨论基线;客户端与服务端实际支持版本要另行协商。协议支持工具发现不表示目标客户端自动具备你的 ERP 查询能力,业务适配、授权和部署都仍属于实现范围。
输入Schema要能挡住歧义
下载查询工具契约及三条样例。输入限定为一个有长度与格式约束的订单号,拒绝多余字段,避免调用者混入 tenant_id 或 execute_sql。格式规则属于合成业务约定,真实订单编码需要从客户系统核实。缺少订单号时,模型应补问;多个候选号时逐一确认,不把整段聊天原样传入一个名叫查询的自由文本参数。
结构校验只能证明输入形状符合规则,不证明用户有权查该订单。JSON Schema 校验规范说明类型、必填项与长度等断言,可据此定义契约,但业务授权必须在代码中执行。契约还要规定大小写、前导零和空白如何处理,不能各层自己归一化后查到不同对象。
输出既要适合模型也要便于核对
成功结果包含订单号、业务状态、预期交期、数据更新时间与受控来源引用。不要返回目标数据库整行,尤其是与当前问题无关的成本、联系人和内部备注。字段值为未知时使用明确空值或业务状态,不让模型自行补日期。客户端支持结构化结果时按约定输出并校验;不支持时也应保留一致的可解析结构,不能每次换一种自然语言格式。
错误至少区分输入无效、权限拒绝、订单不可用、来源超时与结果结构不符。对无权对象是否隐藏存在性,由客户安全策略决定,避免通过“存在但无权”泄露业务信息。可重试错误给出明确建议,授权错误不重试。输出里不要包含连接信息、堆栈和真实令牌;调试详情留在受控记录,用请求追踪号关联。
权限与人工确认写进执行边界
查询工具运行时验证调用者会话、租户和订单范围,服务账户只获得所需查询能力。协议中的工具描述或只读提示不能替代授权,也不能因为工具来自内网就默认可信。把工具清单限制在当前角色需要的范围,并在每次调用时复查权限,防止工具发现时有权、执行时已撤权的旧会话继续访问。
将来若增加修改交期,应作为独立写工具,要求预览旧值、新值、对象版本和影响,再由具备权限的人确认特定参数。不能沿用查询授权,也不能由模型声称“用户已经同意”作为批准。MCP 官方规范建议人在调用中拥有拒绝能力,具体审批界面与确认记录需要应用实现。本文附件只定义只读工具,未赋予任何写入能力。
三条样例加两个失败测试
合成样例包括获准订单、其他组织订单和格式错误订单号。实现方用固定模拟源验证:第一条返回限定字段,第二条拒绝且不暴露详情,第三条在访问来源前被校验拒绝。随后模拟来源超时与结构漂移,检查错误是否可理解且不编造结果。工具调用账本应能关联输入摘要、请求人别名、授权决定和来源回执。
询价时分开列协议接入、业务适配、身份传播、结果校验、审计、部署与验收,不用“一个工具”掩盖不同工作。目标客户端是否支持所选版本、如何呈现错误、是否缓存工具清单,也要有验证任务。通过模拟契约不等于真实 ERP 已联调,正式接口、权限与峰值请求需按授权再测。
需求契约还应规定性能与资源边界,例如允许的查询时间窗、返回上限、并发控制与日志保留。这些值由业务要求和目标接口约束确定,不能从协议名称推导。工具升级新增输出字段时,验证旧客户端是否仍能处理;改变字段含义则应明确版本与迁移。开发报价也列出模拟源、真实接口联调和客户端展示三个阶段,避免模拟结果通过后被误认为全部完成。验收人员应能用三条输入独立重放契约,并逐项解释返回或拒绝的依据,而不依赖开发者口头补充规则。
相关背景见流程自动化专题与能力边界,企业接口协作可查看集成服务。如需 MCP 定制评估,可通过定制咨询提供一个明确业务动作、脱敏接口样例、客户端类型与身份规则,把需求收敛为能够实现和核对的工具契约。