MCP Server 开发
本文面向 MCP Server 开发和联调人员,介绍从准备业务能力、创建服务、实现工具、适配返回,到配套 Skill 和完成验证的开发主线。工具设计原则参见 MCP Server 概念与设计原则,工具定义和返回结构参见 MCP Server 协议规范。
交付约束:MCP Server 与配套 Skill 必须共同交付;Manifest 是项目接入和打包所需的配置产物;卡片按业务展示和交互需要选配。MCP Server 不会被打进版本包,发布前必须部署到可访问的服务地址。
本文不重复业务服务自身的编码、鉴权、稳定性和运维规范,也不展开 Skill、Manifest、卡片、调试工具和发布流程的专项细节。业务逻辑、业务鉴权、参数校验、超时重试、幂等、日志和敏感信息保护等继续遵循业务团队自身研发规范。
1. 开发前准备
开始开发前,先判断当前任务属于“新建 MCP Server”还是“接入已有 MCP Server”。新建服务需要从能力拆分开始;已有服务接入则重点检查工具语义、返回结构、身份权限和外部可访问性。两条路径最终都需要满足相同的协议、Skill 和交付要求。
准备业务能力。先确认要开放的业务能力已经有稳定的业务接口或领域服务,并明确输入、输出、错误和权限边界。MCP 工具是对已有业务能力的清晰封装,不应在工具层重新发明一套互相矛盾的业务规则。
准备开发环境。按照 CLI 安装与配置 完成环境检查、CLI 安装和登录。首次创建项目时,先进入准备存放项目的文件夹,再用一个还没有创建的目录名运行下面的命令:
初始化完成后,项目通常包含 manifest.yaml、skill/SKILL.md,以及位于同一根目录的前端工程。是否开发卡片或全页能力取决于业务场景。MCP Server 可以与项目同仓库,也可以独立维护和部署;无论代码放在哪里,都需要在 Manifest 中配置可访问的 MCP endpoint。
确认身份和权限。根据业务场景确认工具代表谁执行、需要哪些业务权限以及权限不足时如何反馈。身份与权限模型参见 用户身份与权限模型;本文只要求工具定义、Skill 描述和实际权限效果保持一致。
2. 最小开发流程
一个最小可交付的 MCP Server 可以按以下顺序完成。每一步都应产生可验证的结果,再进入下一步。
建议先跑通一个最小工具,再扩展更多工具。第一个工具应优先选择依赖少、输入明确、能够快速验证完整链路的能力。
3. 创建并运行 MCP Server
MCP Server 的具体语言和 SDK 可以根据业务技术栈选择,但必须使用当前接入方式支持的能力。本文不绑定某个 SDK 的函数名;下面的结构用于说明一个最小服务应包含哪些职责。
服务入口。启动过程应能明确区分配置错误、依赖不可用和服务启动成功。MCP Server 与业务项目同仓库时,也应保持独立入口,避免只能依赖整个业务系统的开发环境才能运行。
工具注册。所有计划交付的工具都必须在服务启动后可被发现。工具名称不得因环境不同而变化;测试环境和生产环境可以使用不同 endpoint,但同一版本中的工具契约应保持一致。
基本可达性。本地启动后,先确认服务进程正常、endpoint 可访问、工具列表非空,再验证具体业务调用。发布前还必须把服务部署到可从外部访问的地址;本地地址和仅局域网可达的地址不能作为最终交付 endpoint。
4. 定义和实现 MCP 工具
工具设计从业务意图开始,而不是从已有接口数量开始。一个工具应对应一个稳定、可描述的用户目标。多个接口共同完成一个目标时,可以由一个工具在服务端编排;同一接口承担多个差异明显的目标时,应评估拆成不同工具。
工具边界。工具名称和描述应让模型能够区分“查询”和“执行”、“预览”和“提交”等不同效果。不要依靠一个模糊的 mode 参数承载大量不相关能力,也不要把纯技术接口原样暴露成模型难以理解的工具集合。
工具定义。按照 MCP Server 协议规范 定义 name、description 和 inputSchema。描述应说明适用条件和关键业务效果;输入 Schema 必须与实际处理逻辑一致。
工具处理。处理器通常完成四件事:把模型提供的参数转换为业务请求;根据用户身份和上下文完成业务鉴权;调用已有业务接口;把业务返回转换为 MCP 工具返回。MCP 层可以做协议适配和必要编排,但不应改变业务系统已经定义的事实和权限结果。
具有外部影响的工具,应在描述和 Skill 中清楚表达其效果及调用前提。业务侧对写入、提交、发送、支付等操作的确认、幂等和审计要求,继续遵循业务团队自身规范。
5. 适配工具返回
工具处理器拿到业务结果后,先按业务语义判断本次结果属于实体集合、执行结果还是业务错误,再按照 MCP Server 协议规范 构造返回。不要根据是否需要卡片来选择返回类型;卡片只是可选展示能力。
保持配置一致。实体类型、稳定业务 ID、字段类型和输出类别必须与 Manifest 配置规范 中的声明一致。工具返回只表达业务事实,不携带输出类型或卡片配置。
保持结果一致。content 与 structuredContent 应表达同一业务事实。即使没有卡片,模型也应能理解结果并继续任务。
本节只说明开发过程中的分类与适配方法,不维护协议字段、数据类型和完整 JSON 示例;这些精确要求统一以 13.1 为准。
6. 接入已有 MCP Server
已有 MCP Server 不需要为了接入而重写全部业务逻辑。推荐先评估现有工具契约,再在服务边界增加必要的定义和返回适配。原服务已经满足要求的部分可以直接复用,不满足的部分通过适配层收敛。
最小接入路径。选择一个现有工具,确认工具定义,增加返回适配,配置 Manifest endpoint,编写配套 Skill,然后完成直接调用和 Skill 联调。没有卡片需求时,到这里即可形成完整能力,不需要为了接入额外开发卡片。
需要卡片时。先保证实体返回在无卡片场景下可用,再按照 Manifest 配置规范 关联实体和卡片,并进入卡片专项开发和预览流程。
已有服务仍被其他客户端使用时,不应直接修改旧契约造成破坏。可以保留原入口,在新的接入工具或适配层中完成参数和返回转换,并为后续迁移保留清晰边界。
7. 配套 Skill 与可选卡片
配套 Skill 是必选交付物。Skill 负责告诉模型何时使用 MCP Server,以及如何组织工具调用;MCP Server 负责提供真实能力。Skill 不能引用不存在的工具,也不能虚构工具没有返回的字段和效果。
Skill 的设计和写法参见 Skill 规范 和 Skill 开发。
卡片按场景选配。需要结构化展示、可视化信息或端上交互时,再开发卡片并完成 Manifest 关联。实体返回本身不等于一定出卡;没有卡片时,MCP Server 和 Skill 仍应完成完整任务。
卡片设计与开发参见 卡片设计规范、卡片(Widget)开发 和 Manifest 配置规范。本文不重复卡片模板、字段映射和交互生命周期。
8. 本地验证与联调检查
验证分为两层:先直接验证 MCP Server 的工具契约,再验证 MCP Server、Skill、Manifest 和可选卡片组成的完整任务链路。直接调用未通过时,不应先在 Skill 或卡片层绕过问题。
MCP Server 验证顺序。启动本地服务后,依次检查 endpoint 可达、工具列表可发现、工具定义正确、正常调用成功、空结果可解释、错误场景可恢复。对每个工具至少准备一组正常输入和一组错误输入。
完整链路联调。直接调用通过后,再使用配套 Skill 发起真实任务,确认模型选择正确工具、生成正确参数并理解返回。如果配置了卡片,再按照 本地调试与预览 验证卡片或页面展示;没有卡片时,不需要执行前端预览步骤。
进入打包和提审前,MCP Server 必须已经部署到可访问地址,并完成 Manifest、Skill 和按需前端的本地验证。后续操作参见 打包与提审。
9. 常见问题与下一步
排查时先判断问题属于工具定义、业务调用、返回协议、Skill 使用策略、Manifest 配置还是卡片展示,再进入对应专项文档。不要通过增加模糊描述、隐藏错误或依赖卡片补数据来掩盖协议问题。
下一步:完成本文的开发与联调检查后,按照 打包与提审 校验 Manifest、打包 Skill 和按需前端,并确认已部署的 MCP endpoint 在目标环境可访问。
相关文档: