> 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 协议规范

**文档定位：**&#x672C;文面向 MCP Server 开发者，是 MCP 工具对外定义、调用返回和兼容性要求的唯一规范来源。业务方需要实现标准 MCP 工具能力，以及本文约定的实体、执行结果和错误返回结构。Manifest 的配置字段由 [Manifest 配置规范](/apps-plugin/docs/core-concepts/manifest.md) 说明，具体开发步骤由 [MCP Server 开发](/apps-plugin/docs/skill-development/mcp-server.md) 说明。

:::info 提示

**核心约定：**&#x5BF9;外交付必须同时包含 MCP Server 和配套 Skill；卡片为可选产物。MCP 工具返回只表达业务事实与操作结果，不携带平台内部生成的运行时标识、内部路由字段或卡片模板配置。

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

:::

## 1. 规范范围与术语

本文定义当前平台接入所采用的 MCP 工具协议，重点说明业务 MCP Server 需要提供的工具定义，以及 `content`、`structuredContent` 和 `isError` 三段返回结构。本文进一步规定实体、执行结果和业务错误三类返回，以及这些返回如何与 Manifest、Skill 和可选卡片保持一致。

| 术语             | 说明                                                           |
| -------------- | ------------------------------------------------------------ |
| **MCP Server** | 实现 MCP 协议并向客户端提供一个或多个能力的服务。                                  |
| **MCP 工具**     | MCP Server 对外提供的可调用能力。工具具有稳定名称、功能描述、输入 Schema 和调用返回。         |
| **工具定义**       | 客户端通过工具发现获得的工具元数据，主要包括名称、描述和输入参数 Schema。                     |
| **工具返回**       | 一次工具调用的结果，由 `content`、`structuredContent` 和可选的 `isError` 组成。 |
| **平台约定**       | 本文定义的实体、执行结果和错误结构，是对通用 MCP ToolResult 的业务侧约束。                |
| **Manifest**   | 描述工具输出类型、实体 Schema 和可选卡片关联的配置文件，不属于业务工具返回。                   |

本文使用“必须”表示强制要求，使用“应当”表示无特殊原因应遵循的要求，使用“可以”表示可选能力。示例中的业务名称和字段仅用于说明结构，不构成统一业务模型。

本文不规定业务系统内部的服务拆分、接口实现、鉴权逻辑、重试、幂等、日志等工程细节；这些内容继续遵循业务团队自身研发规范。本文也不描述平台内部的转换、路由和渲染实现。

## 2. 协议基线与兼容性

本文的协议基线以当前已确认的工具返回设计为准：业务 MCP Server 直接实现 `content`、`structuredContent` 和 `isError`，并根据工具用途返回实体集合、执行结果或业务错误。业务方不在本规范中自行选择或扩展其他 MCP 版本能力；如平台后续调整接入协议，以更新后的平台文档和开发工具为准。

**协议边界。**&#x4E1A;务侧对工具定义、调用参数和工具返回负责；输出类型、字段用途和可选卡片关联由 Manifest 声明。未在本文或 Manifest 规范中声明的扩展字段，不能作为稳定接入能力依赖。

**兼容性原则。**&#x5DE5;具名称、输入字段和返回字段一旦对外发布，即构成稳定契约。新增可选字段通常属于兼容变更；删除或重命名字段、修改字段类型或语义、把可选输入改为必填输入，都属于不兼容变更。

| 变更                | 兼容性  | 处理要求                                     |
| ----------------- | ---- | ---------------------------------------- |
| 新增可选输入字段或可选返回字段   | 通常兼容 | 旧调用方忽略该字段时，原有行为仍应成立。                     |
| 新增必填输入字段          | 不兼容  | 使用新的工具名称或新的输出契约，并为迁移保留过渡期。               |
| 删除、重命名字段或修改字段类型   | 不兼容  | 不得直接覆盖已发布契约，应提供迁移方案。                     |
| 修改字段业务语义或稳定 ID 规则 | 不兼容  | 视为契约变更，同时更新 MCP Server、Manifest 和 Skill。 |
| 修改工具名称            | 不兼容  | 新旧工具在迁移期并存，配套 Skill 不得提前引用尚未可用的新名称。      |

兼容变更也必须同步评估配套 Skill 和 Manifest。开发者不得仅以“Schema 仍可解析”为由改变工具的业务效果、权限影响或错误语义。

## 3. 工具定义规范

MCP Server 对外提供工具定义并接收工具调用。当前接入基线要求工具明确提供名称、描述和输入 Schema，使模型能够判断何时调用、需要提供什么参数，以及调用可能产生什么业务效果。

| 字段            | 要求 | 说明                                       |
| ------------- | -- | ---------------------------------------- |
| `name`        | 必须 | 工具的稳定唯一标识。同一 MCP Server 内不得重名，发布后不得随意变更。 |
| `description` | 必须 | 准确说明工具能力、适用条件、关键限制和可能产生的业务效果，避免宣传性或含糊表述。 |
| `inputSchema` | 必须 | 描述工具输入参数。参数类型、必填性和实际处理逻辑必须一致。            |

**名称要求。**&#x5DE5;具名称应保持简洁、稳定且可区分，建议采用动作加对象的形式。同一 MCP Server 内不得重名；名称发布后如需调整，应按不兼容变更处理。具体业务命名继续遵循业务团队自身规范。

**描述要求。**&#x63CF;述应说明工具能做什么、何时适合调用以及重要前置条件。具有写入、提交、发送、支付等外部影响的工具，应在描述中明确其效果。描述不得用来绕过用户意图或诱导模型无条件调用。

**输入 Schema 要求。**`inputSchema` 的顶层必须是 object。参数类型、必填性、枚举和格式必须与实际处理逻辑一致；需要必填的字段同时写入 `required`。无参数工具应显式使用空 object Schema，避免客户端误传任意参数。业务参数校验仍由 MCP Server 负责，Schema 不能替代服务端校验。

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

## 4. 工具返回通用结构

业务工具返回采用 MCP ToolResult 风格。平台约定 `structuredContent` 承载可消费的业务结构化结果，`content` 承载与该结果一致的自然语言说明，`isError` 表达工具执行是否失败。

| 字段                  | 要求   | 说明                                                                   |
| ------------------- | ---- | -------------------------------------------------------------------- |
| `content`           | 建议返回 | MCP 内容数组。本文约定优先返回至少一个 `type=text` 的文本块，文本写在 `text` 字段中，简要说明调用结果或下一步。 |
| `structuredContent` | 必须   | JSON object，承载实体集合、执行结果或错误信息。不得直接返回顶层数组或基础类型。                        |
| `isError`           | 可选   | boolean。缺失或 `false` 表示成功；只有显式 `true` 表示工具执行错误。                       |

`content` 和 `structuredContent` 必须表达同一业务事实。自然语言说明可以概括结构化结果，但不得与结构化字段冲突，也不得把下游必须使用的关键业务数据只放在文本中。

业务返回只包含业务数据。输出类型、实体 Schema、模型可见性和卡片关联由 Manifest 声明；工具返回不得重复这些配置，也不得构造平台内部生成的运行时标识、内部路由字段或卡片模板配置。

```json
{
  "content": [
    {
      "type": "text",
      "text": "未找到可用路线。"
    }
  ],
  "structuredContent": {
    "entities": []
  },
  "isError": false
}
```

## 5. 实体返回规范

当工具用于查询、搜索、推荐或读取可被后续引用的业务对象时，应使用实体返回。对应工具在 Manifest 中声明为 `output.kind=entities`，业务工具在 `structuredContent.entities` 中返回实体数组。

| 字段                           | 要求 | 说明                                                         |
| ---------------------------- | -- | ---------------------------------------------------------- |
| `structuredContent.entities` | 必须 | 业务实体数组。无结果时返回空数组，不把“未找到结果”视为工具执行错误。                        |
| `entity_type`                | 必须 | 实体的业务类型，必须与 Manifest 中已声明的实体类型一致。                          |
| 稳定业务 ID 字段                   | 必须 | 唯一标识同一业务实体。字段名由业务定义，并在 Manifest 的 entity schema 中声明为实体 ID。 |
| 其他业务字段                       | 按需 | 字段名称、类型和语义必须与 Manifest 中对应的 entity schema 一致。              |

**稳定 ID。**&#x7A33;定业务 ID 应来自业务系统，不得为同一实体的每次查询随机生成新值，也不得复用给不同实体。示例使用 `entity_id`，但本规范不强制业务使用这一字段名。

**单实体与多实体。**&#x65E0;论返回一个还是多个实体，都使用 `entities` 数组，不因数量变化切换返回结构。数组中的每个实体都必须独立满足类型、稳定 ID 和 Schema 要求。

**实体与卡片。**&#x5B9E;体返回不等于一定生成卡片。没有配置卡片时，实体仍是合法业务结果，可供模型理解和后续调用使用；是否展示卡片由 Manifest 和卡片产物共同决定。

```json
{
  "content": [
    {
      "type": "text",
      "text": "找到 1 条可用路线。"
    }
  ],
  "structuredContent": {
    "entities": [
      {
        "entity_id": "route_001",
        "entity_type": "route",
        "title": "公司到机场的路线",
        "duration_minutes": 42,
        "price_yuan": 128,
        "summary": "预计 42 分钟到达"
      }
    ]
  },
  "isError": false
}
```

以下返回不符合规范：直接把实体数组作为 `structuredContent`；缺少 `entity_type`；缺少 Manifest 声明的稳定业务 ID；同一字段在不同调用中返回不同数据类型；在业务实体中混入卡片样式或平台运行时字段。

## 6. 执行结果规范

当工具用于创建、修改、提交、发送、启动或完成某项操作，且返回值主要表达本次操作是否完成及其业务结果时，应使用执行结果。对应工具在 Manifest 中声明为 `output.kind=execution_result`，业务工具直接把执行结果 object 放入 `structuredContent`，不增加 `entities` 包装。

执行结果字段由业务定义，但字段名称、类型和状态语义必须稳定。`content` 应给出简明结果说明；如果操作失败，应改用第 7 节定义的错误分支，而不是在成功分支中只返回一个表示失败的状态字符串。

| 选择维度           | 实体返回                         | 执行结果                             |
| -------------- | ---------------------------- | -------------------------------- |
| 主要目的           | 返回可被理解、选择或后续引用的业务对象          | 表达一次操作的完成情况和结果                   |
| 结构             | `structuredContent.entities` | `structuredContent` 直接为结果 object |
| 是否要求实体类型和稳定 ID | 要求                           | 不要求，除非业务结果本身需要                   |
| 卡片             | 可以配置                         | 不以实体卡片作为返回目标                     |

```json
{
  "content": [
    {
      "type": "text",
      "text": "导航已发起。"
    }
  ],
  "structuredContent": {
    "navigation_id": "nav_001",
    "status": "started",
    "destination_name": "机场",
    "navigation_mode": "driving"
  },
  "isError": false
}
```

## 7. 错误返回规范

业务工具执行失败时，必须返回 `isError=true` 的错误分支。本文只规范业务 MCP 服务需要实现的工具错误结构，不展开连接、传输或平台内部错误处理。

| 字段                          | 要求 | 说明                            |
| --------------------------- | -- | ----------------------------- |
| `content[].text`            | 建议 | 面向模型和用户的业务错误说明，应提供可理解的原因或下一步。 |
| `structuredContent.code`    | 必须 | number 类型的业务错误码，不使用字符串枚举。     |
| `structuredContent.message` | 必须 | string 类型的业务错误文案。             |
| `isError`                   | 必须 | 错误分支固定为 `true`。               |

平台约定工具执行错误的 `structuredContent` 至少包含数字类型的 `code` 和字符串类型的 `message`。`code` 用于稳定区分业务错误，发布后不得随意改变含义；`message` 用于说明错误原因。建议同时在 `content` 中给出模型和用户可理解、可采取行动的说明。

错误信息不得暴露敏感数据、凭证、内部调用链或仅供排障的实现细节。对于可恢复错误，应说明需要补充或修正的输入；对于不可恢复错误，应明确本次操作未完成，避免模型重复调用造成额外影响。

```json
{
  "content": [
    {
      "type": "text",
      "text": "起点无法识别，请补充更明确的起点。"
    }
  ],
  "structuredContent": {
    "code": 10001,
    "message": "起点无法识别"
  },
  "isError": true
}
```

## 8. 交付约束与产物边界

### 8.1 MCP Server 与 Skill

每个对外 MCP Server 必须提供配套 Skill。Skill 负责告诉模型在什么场景下选择哪些工具、如何组织调用以及如何理解结果；MCP Server 负责提供真实、可调用的能力。两者必须作为同一项能力共同设计、共同验证和共同发布。

Skill 引用的工具名称必须真实存在，参数名称、必填性、业务语义、返回语义和错误语义必须与 MCP Server 一致。MCP Server 发生兼容性变更时，必须同步评估并更新 Skill。Skill 的具体编写要求参见 [Skill 规范](/apps-plugin/docs/core-concepts/skill-guidelines.md) 和 [Skill 开发](/apps-plugin/docs/skill-development/overview.md)。

卡片不是 MCP Server 的必选产物。需要结构化展示或交互时可以提供卡片；不提供卡片时，工具仍必须通过 `content` 和 `structuredContent` 返回完整、可理解的业务结果。

### 8.2 与 Manifest 的关系

MCP 工具返回负责表达业务事实和操作结果，Manifest 负责声明这些结果的解释方式。工具的 `output.kind`、实体 Schema、稳定 ID 字段、模型可见性和可选卡片关联均在 Manifest 中配置，具体字段参见 [Manifest 配置规范](/apps-plugin/docs/core-concepts/manifest.md)。

工具返回与 Manifest 必须保持一致：实体返回必须对应 `entities` 输出类型，执行结果必须对应 `execution_result` 输出类型；实体类型、字段类型和稳定 ID 声明必须能覆盖实际返回。业务工具不得在返回中携带输出类型或展示配置来替代 Manifest。

### 8.3 数据与展示边界

业务数据应当在没有卡片的情况下仍可被理解。卡片只负责展示和交互，不改变工具返回的业务语义，也不承担补全缺失业务字段的职责。业务返回不得依赖某个具体卡片样式才能表达成功、失败或实体含义。

卡片需要的数据应来自工具返回中稳定的业务字段。展示字段如何映射、交互如何触发后续工具，由卡片和 Manifest 规范约束，不在本文重复定义。

## 9. 协议校验与外部行为

MCP Server 在交付前必须完成协议级验证。业务方不得依赖客户端或平台对不合法返回进行猜测、修复或静默降级。

| 校验对象         | 必须验证                                                | 不符合时                        |
| ------------ | --------------------------------------------------- | --------------------------- |
| 工具发现         | 工具名称唯一，描述完整，输入 Schema 合法                            | 视为工具定义不合规，不得发布。             |
| 工具调用         | 调用参数能够按 `inputSchema` 校验                            | 参数校验失败时，按第 7 节返回可恢复的工具执行错误。 |
| 通用返回         | `structuredContent` 为 object，`isError` 类型正确         | 视为无效工具返回。                   |
| 实体返回         | 存在 `entities` 数组；实体类型、稳定 ID 和字段 Schema 一致           | 不得依赖卡片或模型补全缺失字段。            |
| 执行结果         | 返回 object，字段类型和状态语义稳定                               | 视为输出契约不一致。                  |
| 错误返回         | `isError=true`，且 `code` 为 number、`message` 为 string | 视为错误结构不合规。                  |
| Manifest 一致性 | 输出类型、实体类型、字段和稳定 ID 与实际返回一致                          | 不得进入交付流程。                   |
| Skill 一致性    | 工具名称、参数、返回和错误语义与 Skill 描述一致                         | 视为交付产物不完整。                  |

本地验证应至少覆盖：正常结果、空结果、多个实体、参数错误、依赖失败和兼容性变更后的旧调用。具体调试与发布检查流程参见开发和发布相关文档。

## 10. 完整示例与字段速查

**实体查询工具。**&#x4E0B;面的工具定义与返回构成一组完整契约。工具名称、输入参数和实体字段应同时出现在配套 Skill 与 Manifest 的相应声明中。

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

```json
{
  "content": [
    { "type": "text", "text": "找到 1 条可用路线。" }
  ],
  "structuredContent": {
    "entities": [
      {
        "entity_id": "route_001",
        "entity_type": "route",
        "title": "公司到机场的路线",
        "duration_minutes": 42,
        "price_yuan": 128
      }
    ]
  },
  "isError": false
}
```

**空结果。**&#x67E5;询成功但没有匹配实体时，返回空数组；这不是工具执行错误。

```json
{
  "content": [
    { "type": "text", "text": "没有找到符合条件的路线。" }
  ],
  "structuredContent": {
    "entities": []
  },
  "isError": false
}
```

| 字段                           | 类型          | 要求     | 用途                 |
| ---------------------------- | ----------- | ------ | ------------------ |
| `Tool.name`                  | string      | 必须     | 工具稳定唯一标识           |
| `Tool.description`           | string      | 必须     | 说明能力、适用条件和业务效果     |
| `Tool.inputSchema`           | object      | 必须     | 定义调用参数             |
| `result.content`             | array       | 建议     | 模型和用户可理解的结果说明      |
| `result.structuredContent`   | object      | 必须     | 业务结构化结果            |
| `result.isError`             | boolean     | 可选     | 工具执行是否失败，默认 false  |
| `structuredContent.entities` | array       | 实体返回必须 | 业务实体集合             |
| `entity.entity_type`         | string      | 实体返回必须 | 匹配 Manifest 中的实体类型 |
| 实体稳定业务 ID 字段                 | 由 Schema 定义 | 实体返回必须 | 稳定标识同一业务实体         |
| `structuredContent.code`     | number      | 错误返回必须 | 稳定业务错误码            |
| `structuredContent.message`  | string      | 错误返回必须 | 业务错误说明             |

**常见不合规情况：**&#x8F93;入 Schema 与实际参数不一致；成功返回缺少 `structuredContent`；实体数组直接作为顶层返回；实体缺少类型或稳定 ID；执行结果错误地包在 `entities` 中；业务失败仍返回成功分支；返回结构与 Manifest 的 `output.kind` 不一致；Skill 引用不存在或已改名的工具。

## 11. 相关文档

- [MCP Server 概念与设计原则](/apps-plugin/docs/core-concepts/mcp-server-guidelines.md)
- [MCP Server 开发](/apps-plugin/docs/skill-development/mcp-server.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)
- [卡片设计规范](/apps-plugin/docs/design-principles/card-design.md)、[卡片（Widget）开发](/apps-plugin/docs/frontend-development/widget.md)
