业务接口如何封装成 MCP 工具，入参出参和兼容性如何设计？

核心回答

业务接口封装成MCP工具，我会先定义一个模型能理解、业务能校验的稳定契约，再在Server里适配原接口：

1. 明确工具用途：名称、适用场景、前置条件和副作用，避免一个工具承接所有业务操作。
2. 设计入参：用 inputSchema 描述字段、类型、必填、枚举和单位；身份、凭证及内部地址由可信程序处理。
3. 设计出参：保留业务结果、状态、时间和来源等必要信息。需要结构化校验时提供 outputSchema，返回相应的 structuredContent。
4. 实现执行适配：校验参数和资源权限，转换为原接口请求，再规范化结果、错误、超时及重试行为。
5. 分层处理兼容：分别管理工具业务版本、底层API版本、SDK版本和MCP协议revision，用实际Client验证发现、调用及异常路径。

Host通过Client发现工具并适配给模型，模型提出调用后，Server才执行实际业务。MCP统一连接方式，不会自动解决字段语义、授权和业务副作用。

展开说明

1. 先封装业务能力，再决定怎样暴露

工具应围绕任务命名，例如查询某项指标、查订单或取得文档，而不是只暴露一个缺少边界的“执行任意接口”。描述要让模型知道何时使用、缺少什么信息时不能调用，以及结果能支持什么判断。

Server可以复用原有服务层或HTTP客户端，不必复制一套业务规则。它负责MCP请求到业务接口的转换；Host负责把发现的工具定义适配到所用模型的工具格式。接入框架后，也要知道工具定义来自哪里、调用最终路由到哪个Server。

2. 入参要保留业务含义，不能只写几个string

日期要说明格式和时区，数量要说明单位，编号要说明类型与来源，枚举要描述含义。缺参时应反馈缺什么，含糊的自然语言不能直接当作已确认业务值。可选字段和默认值也要写清，尤其不能用默认值悄悄扩大查询范围。

Schema约束数据形状，Server仍要检查跨字段条件、资源归属和当前业务状态。用户身份和访问凭证来自可信调用环境，不让模型填一个 user_id 就决定查谁的数据；若业务确需目标用户字段，也要另行校验调用者是否有权访问。

上游字段变化可在适配层转换，但不能改变公开字段的既定含义。例如同名金额字段从元改成分，或状态码含义变化，都属于语义兼容问题。新增可选字段也需检查旧客户端能否容忍，不能仅凭“没删字段”就判断完全兼容。

3. 结果要区分成功、空数据、部分结果和失败

业务返回宜保留关键字段、单位、数据时间、范围和必要来源。列表结果较大时提供分页、总量及是否完整，避免模型把前一页误当成全部。

当前规范的 outputSchema 是可选项；提供后，Server返回的结构化结果须符合它，Client也应校验。structuredContent 是Server产生的数据，与模型的结构化生成是不同机制。为兼容使用文本结果的Client，可以同时返回序列化JSON文本或必要说明，具体按目标Client验证。

协议级错误与工具执行错误也要分开。未知工具或畸形请求通过JSON-RPC错误表达；业务API失败、参数语义不合法等执行错误，可用 isError: true 给出可处理的反馈。合法空列表不必一律视为异常。HTTP成功也不等于业务已成功，要检查业务回执；错误信息应保留可定位标识，去掉凭证和内部堆栈。

4. 兼容性不能只靠固定一个工具名

工具契约可以按版本演进，破坏性修改通过新版本或新工具名发布，并保留必要迁移期。缓存工具定义时关联版本和访问范围，避免模型按旧Schema生成参数，Server却按新语义执行。

协议版本与SDK版本分别确认。2026-07-28规范采用每个请求声明协议版本和客户端能力的方式，HTTP还涉及相应协议头；2025-11-25及更早版本使用初始化握手。当前Server须支持 server/discover，Client可以先发现，也可以按规范处理不支持版本的响应。兼容旧Client需要实现相应旧流程，不能只把请求里的版本字符串改成新日期。

教程固定依赖是官方Python SDK mcp>=1.26,<2，天气示例使用1.x的FastMCP和兼容SSE写法。理解它时按该版本看；新实现则对照选定SDK与目标revision，不能把旧代码的启动、握手和返回格式拼成当前实现。

业务执行还要独立处理超时、取消和幂等。查询可有限重试；写操作超时且结果未知时，应先查回执，不能因更换协议或重连就重复提交。

5. 用教程天气工具说明具体映射

教程中的参考实现是 get_weather(city)：用城市调用天气HTTP接口，把摄氏单位和语言参数放在Server端，再把返回数据序列化成字符串。这展示了业务API被包装成MCP工具的基本位置。

若把它进一步做成稳定业务工具，可以明确城市标识及歧义处理，把结果整理成城市、温度、单位、天气描述和观测时间，检查上游HTTP状态及业务错误，再按约定结果结构返回。原API增加无关字段时，上层契约不必跟着变化；含义变更时则更新映射和版本。

验证时先用固定的上游成功、无数据、参数错误、超时及异常结构回放，再用目标Client检查工具发现、调用关联和结果解析。涉及写操作的工具还需覆盖重复请求与断线后的状态核对。只有Server能启动，不代表契约和兼容性已经成立。

常见追问

是不是把原HTTP接口原样转成Tool就行？

简单接口可以薄封装，但仍需补清用途、参数语义、权限和错误处理。原接口的内部参数、冗余字段或不稳定状态码未必适合直接交给模型，应在适配层保持稳定业务契约。

MCP返回JSON，模型就一定会正确理解吗？

不会。结构化结果提高可解析性，字段说明、单位、时间和范围仍要清楚；Host也要把必要内容实际提供给模型。关键计算、状态判断和授权不要只交给模型从一段JSON中猜。

不同版本的Client都要支持吗？

按实际服务对象确定兼容范围，明确支持哪些revision、传输和结果类型，做对应组合测试。无共同支持版本时应给出可诊断错误，不能默默换成不兼容语义继续执行。

对应教程

参考资料