> 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.

# MCP Server 开发

本文面向 MCP Server 开发和联调人员，介绍从准备业务能力、创建服务、实现工具、适配返回，到配套 Skill 和完成验证的开发主线。工具设计原则参见 [MCP Server 概念与设计原则](/apps-plugin/docs/core-concepts/mcp-server-guidelines.md)，工具定义和返回结构参见 [MCP Server 协议规范](/apps-plugin/docs/skill-development/mcp-server-protocol.md)。

:::info 提示

**交付约束：**&#x4D;CP Server 与配套 Skill 必须共同交付；Manifest 是项目接入和打包所需的配置产物；卡片按业务展示和交互需要选配。MCP Server 不会被打进版本包，发布前必须部署到可访问的服务地址。

<div hidden data-lark-callout-end></div>

:::

本文不重复业务服务自身的编码、鉴权、稳定性和运维规范，也不展开 Skill、Manifest、卡片、调试工具和发布流程的专项细节。业务逻辑、业务鉴权、参数校验、超时重试、幂等、日志和敏感信息保护等继续遵循业务团队自身研发规范。

## 1. 开发前准备

开始开发前，先判断当前任务属于“新建 MCP Server”还是“接入已有 MCP Server”。新建服务需要从能力拆分开始；已有服务接入则重点检查工具语义、返回结构、身份权限和外部可访问性。两条路径最终都需要满足相同的协议、Skill 和交付要求。

**准备业务能力。**&#x5148;确认要开放的业务能力已经有稳定的业务接口或领域服务，并明确输入、输出、错误和权限边界。MCP 工具是对已有业务能力的清晰封装，不应在工具层重新发明一套互相矛盾的业务规则。

**准备开发环境。**&#x6309;照 [CLI 安装与配置](/apps-plugin/docs/development-tools/installation.md) 完成环境检查、CLI 安装和登录。首次创建项目时，先进入准备存放项目的文件夹，再用一个还没有创建的目录名运行下面的命令：

```bash
dbx init my-app
cd my-app
```

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

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

**确认身份和权限。**&#x6839;据业务场景确认工具代表谁执行、需要哪些业务权限以及权限不足时如何反馈。身份与权限模型参见 [用户身份与权限模型](/apps-plugin/docs/core-concepts/identity-and-permissions.md)；本文只要求工具定义、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、环境和访问业务系统所需的配置；敏感信息不写入工具返回或代码示例。 |

```text
创建 MCP Server

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

启动服务并对外提供 endpoint
```

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

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

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

## 4. 定义和实现 MCP 工具

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

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

**工具定义。**&#x6309;照 [MCP Server 协议规范](/apps-plugin/docs/skill-development/mcp-server-protocol.md) 定义 `name`、`description` 和 `inputSchema`。描述应说明适用条件和关键业务效果；输入 Schema 必须与实际处理逻辑一致。

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

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

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

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

## 5. 适配工具返回

工具处理器拿到业务结果后，先按业务语义判断本次结果属于实体集合、执行结果还是业务错误，再按照 [MCP Server 协议规范](/apps-plugin/docs/skill-development/mcp-server-protocol.md) 构造返回。不要根据是否需要卡片来选择返回类型；卡片只是可选展示能力。

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

**保持配置一致。**&#x5B9E;体类型、稳定业务 ID、字段类型和输出类别必须与 [Manifest 配置规范](/apps-plugin/docs/core-concepts/manifest.md) 中的声明一致。工具返回只表达业务事实，不携带输出类型或卡片配置。

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

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

## 6. 接入已有 MCP Server

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

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

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

**需要卡片时。**&#x5148;保证实体返回在无卡片场景下可用，再按照 [Manifest 配置规范](/apps-plugin/docs/core-concepts/manifest.md) 关联实体和卡片，并进入卡片专项开发和预览流程。

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

## 7. 配套 Skill 与可选卡片

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

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

Skill 的设计和写法参见 [Skill 规范](/apps-plugin/docs/core-concepts/skill-guidelines.md) 和 [Skill 开发](/apps-plugin/docs/skill-development/overview.md)。

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

卡片设计与开发参见 [卡片设计规范](/apps-plugin/docs/design-principles/card-design.md)、[卡片（Widget）开发](/apps-plugin/docs/frontend-development/widget.md) 和 [Manifest 配置规范](/apps-plugin/docs/core-concepts/manifest.md)。本文不重复卡片模板、字段映射和交互生命周期。

## 8. 本地验证与联调检查

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

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

**完整链路联调。**&#x76F4;接调用通过后，再使用配套 Skill 发起真实任务，确认模型选择正确工具、生成正确参数并理解返回。如果配置了卡片，再按照 [本地调试与预览](/apps-plugin/docs/development-tools/local-debugging.md) 验证卡片或页面展示；没有卡片时，不需要执行前端预览步骤。

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

进入打包和提审前，MCP Server 必须已经部署到可访问地址，并完成 Manifest、Skill 和按需前端的本地验证。后续操作参见 [打包与提审](/apps-plugin/docs/release/package-and-submit.md)。

## 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 配置还是卡片展示，再进入对应专项文档。不要通过增加模糊描述、隐藏错误或依赖卡片补数据来掩盖协议问题。

**下一步：**&#x5B8C;成本文的开发与联调检查后，按照 [打包与提审](/apps-plugin/docs/release/package-and-submit.md) 校验 Manifest、打包 Skill 和按需前端，并确认已部署的 MCP endpoint 在目标环境可访问。

**相关文档：**

- [MCP Server 概念与设计原则](/apps-plugin/docs/core-concepts/mcp-server-guidelines.md)
- [MCP Server 协议规范](/apps-plugin/docs/skill-development/mcp-server-protocol.md)
- [Manifest 配置规范](/apps-plugin/docs/core-concepts/manifest.md)
- [Skill 规范](/apps-plugin/docs/core-concepts/skill-guidelines.md)、[Skill 开发](/apps-plugin/docs/skill-development/overview.md)
- [CLI 安装与配置](/apps-plugin/docs/development-tools/installation.md)、[本地调试与预览](/apps-plugin/docs/development-tools/local-debugging.md)
- [打包与提审](/apps-plugin/docs/release/package-and-submit.md)
