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

MCP Server 协议规范

文档定位:本文面向 MCP Server 开发者,是 MCP 工具对外定义、调用返回和兼容性要求的唯一规范来源。业务方需要实现标准 MCP 工具能力,以及本文约定的实体、执行结果和错误返回结构。Manifest 的配置字段由 Manifest 配置规范 说明,具体开发步骤由 MCP Server 开发 说明。

提示

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

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 版本能力;如平台后续调整接入协议,以更新后的平台文档和开发工具为准。

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

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

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

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

3. 工具定义规范

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

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

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

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

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

{
  "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 声明;工具返回不得重复这些配置,也不得构造平台内部生成的运行时标识、内部路由字段或卡片模板配置。

{
  "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。稳定业务 ID 应来自业务系统,不得为同一实体的每次查询随机生成新值,也不得复用给不同实体。示例使用 entity_id,但本规范不强制业务使用这一字段名。

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

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

{
  "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.entitiesstructuredContent 直接为结果 object
是否要求实体类型和稳定 ID要求不要求,除非业务结果本身需要
卡片可以配置不以实体卡片作为返回目标
{
  "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 中给出模型和用户可理解、可采取行动的说明。

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

{
  "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 规范 和 Skill 开发。

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

8.2 与 Manifest 的关系

MCP 工具返回负责表达业务事实和操作结果,Manifest 负责声明这些结果的解释方式。工具的 output.kind、实体 Schema、稳定 ID 字段、模型可见性和可选卡片关联均在 Manifest 中配置,具体字段参见 Manifest 配置规范。

工具返回与 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. 完整示例与字段速查

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

{
  "name": "search_routes",
  "description": "根据起点和终点查询路线,不发起导航。",
  "inputSchema": {
    "type": "object",
    "properties": {
      "origin": { "type": "string", "description": "出发地" },
      "destination": { "type": "string", "description": "目的地" }
    },
    "required": ["origin", "destination"],
    "additionalProperties": false
  }
}
{
  "content": [
    { "type": "text", "text": "找到 1 条可用路线。" }
  ],
  "structuredContent": {
    "entities": [
      {
        "entity_id": "route_001",
        "entity_type": "route",
        "title": "公司到机场的路线",
        "duration_minutes": 42,
        "price_yuan": 128
      }
    ]
  },
  "isError": false
}

空结果。查询成功但没有匹配实体时,返回空数组;这不是工具执行错误。

{
  "content": [
    { "type": "text", "text": "没有找到符合条件的路线。" }
  ],
  "structuredContent": {
    "entities": []
  },
  "isError": false
}
字段类型要求用途
Tool.namestring必须工具稳定唯一标识
Tool.descriptionstring必须说明能力、适用条件和业务效果
Tool.inputSchemaobject必须定义调用参数
result.contentarray建议模型和用户可理解的结果说明
result.structuredContentobject必须业务结构化结果
result.isErrorboolean可选工具执行是否失败,默认 false
structuredContent.entitiesarray实体返回必须业务实体集合
entity.entity_typestring实体返回必须匹配 Manifest 中的实体类型
实体稳定业务 ID 字段由 Schema 定义实体返回必须稳定标识同一业务实体
structuredContent.codenumber错误返回必须稳定业务错误码
structuredContent.messagestring错误返回必须业务错误说明

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

11. 相关文档