For AI agents: the complete documentation index is available at /apps-plugin/docs/llms.txt, the full documentation bundle is available at /apps-plugin/docs/llms-full.txt, and this page is available as Markdown at /apps-plugin/docs/skill-development/mcp-server.md.

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 安装和登录。首次创建项目时,先进入准备存放项目的文件夹,再用一个还没有创建的目录名运行下面的命令:

dbx init my-app
cd my-app

初始化完成后,项目通常包含 manifest.yaml、skill/SKILL.md,以及位于同一根目录的前端工程。是否开发卡片或全页能力取决于业务场景。MCP Server 可以与项目同仓库,也可以独立维护和部署;无论代码放在哪里,都需要在 Manifest 中配置可访问的 MCP endpoint。

project/
├── manifest.yaml        # 项目配置和 MCP endpoint
├── package.json         # 前端依赖与构建脚本
├── src/                 # 前端源码;卡片和全页能力按业务需要开发
├── skill/
│   └── SKILL.md         # 与 MCP 工具配套的 Skill
└── mcp-server/          # MCP Server,可同仓库,也可独立维护

确认身份和权限。根据业务场景确认工具代表谁执行、需要哪些业务权限以及权限不足时如何反馈。身份与权限模型参见 用户身份与权限模型;本文只要求工具定义、Skill 描述和实际权限效果保持一致。

产物要求说明
MCP Server必须提供真实可调用的工具能力;发布前部署到可访问地址。
配套 Skill必须描述工具适用场景、参数组织、调用策略和结果处理方式。
Manifest必须配置 MCP endpoint、工具输出和项目交付信息;具体字段参见 13.2。
卡片与全页能力可选只有需要结构化展示、交互或全页体验时才开发。

2. 最小开发流程

一个最小可交付的 MCP Server 可以按以下顺序完成。每一步都应产生可验证的结果,再进入下一步。

步骤工作目标阶段产物
1确认能力边界把稳定业务能力拆成语义清晰的工具工具清单
2初始化项目准备 Manifest、Skill 和开发目录项目骨架
3创建 MCP Server服务能够启动、连接并公开工具可运行服务
4实现工具输入参数能稳定映射到已有业务接口工具定义与处理逻辑
5适配返回按 13.1 返回实体、执行结果或业务错误协议化 ToolResult
6编写 Skill模型知道何时以及如何使用这些工具SKILL.md
7配置项目完成 Manifest;按需开发卡片或全页项目配置与可选前端
8验证和部署正常、空结果和错误场景均可用可联调 endpoint

建议先跑通一个最小工具,再扩展更多工具。第一个工具应优先选择依赖少、输入明确、能够快速验证完整链路的能力。

3. 创建并运行 MCP Server

MCP Server 的具体语言和 SDK 可以根据业务技术栈选择,但必须使用当前接入方式支持的能力。本文不绑定某个 SDK 的函数名;下面的结构用于说明一个最小服务应包含哪些职责。

组成职责
服务入口初始化 MCP Server,加载运行配置并启动服务。
工具注册向客户端公开工具名称、描述和输入 Schema。
工具处理器接收参数、调用业务能力并返回协议化结果。
业务客户端连接已有业务接口或领域服务,不在 MCP 层复制业务规则。
配置与凭证提供 endpoint、环境和访问业务系统所需的配置;敏感信息不写入工具返回或代码示例。
创建 MCP Server

注册工具 search_routes:
  定义 name、description、inputSchema
  收到调用后:
    1. 读取并校验参数
    2. 调用已有路线查询服务
    3. 把业务结果转换为 13.1 约定的工具返回
    4. 返回 content、structuredContent 和 isError

启动服务并对外提供 endpoint

服务入口。启动过程应能明确区分配置错误、依赖不可用和服务启动成功。MCP Server 与业务项目同仓库时,也应保持独立入口,避免只能依赖整个业务系统的开发环境才能运行。

工具注册。所有计划交付的工具都必须在服务启动后可被发现。工具名称不得因环境不同而变化;测试环境和生产环境可以使用不同 endpoint,但同一版本中的工具契约应保持一致。

基本可达性。本地启动后,先确认服务进程正常、endpoint 可访问、工具列表非空,再验证具体业务调用。发布前还必须把服务部署到可从外部访问的地址;本地地址和仅局域网可达的地址不能作为最终交付 endpoint。

4. 定义和实现 MCP 工具

工具设计从业务意图开始,而不是从已有接口数量开始。一个工具应对应一个稳定、可描述的用户目标。多个接口共同完成一个目标时,可以由一个工具在服务端编排;同一接口承担多个差异明显的目标时,应评估拆成不同工具。

工具边界。工具名称和描述应让模型能够区分“查询”和“执行”、“预览”和“提交”等不同效果。不要依靠一个模糊的 mode 参数承载大量不相关能力,也不要把纯技术接口原样暴露成模型难以理解的工具集合。

工具定义。按照 MCP Server 协议规范 定义 name、description 和 inputSchema。描述应说明适用条件和关键业务效果;输入 Schema 必须与实际处理逻辑一致。

{
  "name": "search_routes",
  "description": "根据起点和终点查询可用路线,不发起导航。",
  "inputSchema": {
    "type": "object",
    "properties": {
      "origin": { "type": "string", "description": "出发地" },
      "destination": { "type": "string", "description": "目的地" }
    },
    "required": ["origin", "destination"]
  }
}

工具处理。处理器通常完成四件事:把模型提供的参数转换为业务请求;根据用户身份和上下文完成业务鉴权;调用已有业务接口;把业务返回转换为 MCP 工具返回。MCP 层可以做协议适配和必要编排,但不应改变业务系统已经定义的事实和权限结果。

工具参数
  → 输入校验与业务请求转换
  → 身份和权限处理
  → 调用业务服务
  → 业务结果分类
  → 实体返回 / 执行结果 / 业务错误

具有外部影响的工具,应在描述和 Skill 中清楚表达其效果及调用前提。业务侧对写入、提交、发送、支付等操作的确认、幂等和审计要求,继续遵循业务团队自身规范。

5. 适配工具返回

工具处理器拿到业务结果后,先按业务语义判断本次结果属于实体集合、执行结果还是业务错误,再按照 MCP Server 协议规范 构造返回。不要根据是否需要卡片来选择返回类型;卡片只是可选展示能力。

返回类型适用场景判断重点
实体集合查询、搜索、推荐或读取可被后续理解和引用的业务对象返回实体集合;无匹配结果通常仍属于成功查询
执行结果创建、修改、提交、发送、启动等操作完成后的业务结果直接表达本次操作的结果,不使用实体集合包装
业务错误参数、权限、依赖或业务条件导致本次调用失败显式进入错误分支,并给出可理解、可恢复的说明

保持配置一致。实体类型、稳定业务 ID、字段类型和输出类别必须与 Manifest 配置规范 中的声明一致。工具返回只表达业务事实,不携带输出类型或卡片配置。

保持结果一致。content 与 structuredContent 应表达同一业务事实。即使没有卡片,模型也应能理解结果并继续任务。

本节只说明开发过程中的分类与适配方法,不维护协议字段、数据类型和完整 JSON 示例;这些精确要求统一以 13.1 为准。

6. 接入已有 MCP Server

已有 MCP Server 不需要为了接入而重写全部业务逻辑。推荐先评估现有工具契约,再在服务边界增加必要的定义和返回适配。原服务已经满足要求的部分可以直接复用,不满足的部分通过适配层收敛。

检查项需要确认不一致时
工具边界工具是否对应清晰、稳定的业务意图调整拆分或新增接入工具
名称和描述模型能否区分适用场景和业务效果在不破坏旧调用方的前提下提供新契约
输入参数Schema 与实际参数和必填性是否一致增加参数转换和校验
成功返回能否映射为实体集合或执行结果增加 ToolResult 适配
错误返回能否稳定返回错误码和错误说明统一转换为 13.1 的错误结构
身份与权限调用身份、权限效果与工具描述是否一致补齐接入配置和错误反馈
可访问性endpoint 是否能在目标环境访问完成部署、网络和配置调整

最小接入路径。选择一个现有工具,确认工具定义,增加返回适配,配置 Manifest endpoint,编写配套 Skill,然后完成直接调用和 Skill 联调。没有卡片需求时,到这里即可形成完整能力,不需要为了接入额外开发卡片。

需要卡片时。先保证实体返回在无卡片场景下可用,再按照 Manifest 配置规范 关联实体和卡片,并进入卡片专项开发和预览流程。

已有服务仍被其他客户端使用时,不应直接修改旧契约造成破坏。可以保留原入口,在新的接入工具或适配层中完成参数和返回转换,并为后续迁移保留清晰边界。

7. 配套 Skill 与可选卡片

配套 Skill 是必选交付物。Skill 负责告诉模型何时使用 MCP Server,以及如何组织工具调用;MCP Server 负责提供真实能力。Skill 不能引用不存在的工具,也不能虚构工具没有返回的字段和效果。

一致性检查要求
工具名称Skill 中的名称与 MCP Server 实际公开的名称完全一致。
适用场景Skill 的触发和路由规则与工具真实能力边界一致。
输入参数字段名称、必填性和业务含义与 inputSchema 一致。
调用顺序需要多个工具协作时,Skill 明确必要的前后依赖和追问条件。
结果处理Skill 按实体、执行结果和错误的真实语义继续任务,不编造结果。
变更同步MCP Server 契约变化时,同步更新并重新验证 Skill。

Skill 的设计和写法参见 Skill 规范 和 Skill 开发。

卡片按场景选配。需要结构化展示、可视化信息或端上交互时,再开发卡片并完成 Manifest 关联。实体返回本身不等于一定出卡;没有卡片时,MCP Server 和 Skill 仍应完成完整任务。

卡片设计与开发参见 卡片设计规范、卡片(Widget)开发 和 Manifest 配置规范。本文不重复卡片模板、字段映射和交互生命周期。

8. 本地验证与联调检查

验证分为两层:先直接验证 MCP Server 的工具契约,再验证 MCP Server、Skill、Manifest 和可选卡片组成的完整任务链路。直接调用未通过时,不应先在 Skill 或卡片层绕过问题。

MCP Server 验证顺序。启动本地服务后,依次检查 endpoint 可达、工具列表可发现、工具定义正确、正常调用成功、空结果可解释、错误场景可恢复。对每个工具至少准备一组正常输入和一组错误输入。

完整链路联调。直接调用通过后,再使用配套 Skill 发起真实任务,确认模型选择正确工具、生成正确参数并理解返回。如果配置了卡片,再按照 本地调试与预览 验证卡片或页面展示;没有卡片时,不需要执行前端预览步骤。

验证场景预期结果重点检查
服务启动和连接endpoint 可访问,工具列表非空启动配置、工具注册
正常实体返回实体类型、稳定 ID 和字段完整13.1 与 Manifest
空结果返回空数组并给出可理解说明不得误报为错误
执行结果操作状态和业务结果明确不得错误包装为实体
业务错误isError=true,错误码和说明完整可恢复信息、敏感信息
Skill 调用选择正确工具并生成正确参数名称、边界、参数语义
无卡片场景模型仅凭返回也能完成任务文本与结构化结果一致
有卡片场景实体和卡片关联正确,展示数据与返回一致Manifest 和卡片实现
部署后联调目标环境能访问 MCP endpoint公网访问、环境配置、权限

进入打包和提审前,MCP Server 必须已经部署到可访问地址,并完成 Manifest、Skill 和按需前端的本地验证。后续操作参见 打包与提审。

9. 常见问题与下一步

问题优先检查处理建议
服务无法连接进程、endpoint、环境配置和网络可达性先恢复直接连接,再进行 Skill 联调。
工具列表为空工具是否注册、注册过程是否报错确认服务启动后实际公开了计划交付的工具。
模型没有选择工具工具描述和 Skill 触发条件明确适用场景和能力边界,避免描述过于宽泛。
模型选择了错误工具工具之间是否重叠,Skill 路由是否清晰区分查询与执行、预览与提交等业务效果。
参数生成不符合预期inputSchema、描述和 Skill 参数说明统一字段名称、必填性和业务含义。
返回结构校验失败structuredContent、isError 和返回类型按 13.1 修正,不在 Skill 中猜测或补全。
实体无法识别entity_type、稳定业务 ID 和 Manifest schema保证实际返回与 Manifest 完全一致。
返回实体但没有卡片是否确实需要卡片、是否配置卡片关联先确认无卡片结果可用,再排查 Manifest 和卡片。
本地通过但联调失败公网访问、环境差异、身份权限和部署配置使用部署后的 endpoint 重新执行完整验证。
服务变更后调用异常Skill 和 Manifest 是否同步把服务、Skill 和配置作为同一版本重新验证。

排查时先判断问题属于工具定义、业务调用、返回协议、Skill 使用策略、Manifest 配置还是卡片展示,再进入对应专项文档。不要通过增加模糊描述、隐藏错误或依赖卡片补数据来掩盖协议问题。

下一步:完成本文的开发与联调检查后,按照 打包与提审 校验 Manifest、打包 Skill 和按需前端,并确认已部署的 MCP endpoint 在目标环境可访问。

相关文档: