MCP Server 协议规范
文档定位:本文面向 MCP Server 开发者,是 MCP 工具对外定义、调用返回和兼容性要求的唯一规范来源。业务方需要实现标准 MCP 工具能力,以及本文约定的实体、执行结果和错误返回结构。Manifest 的配置字段由 Manifest 配置规范 说明,具体开发步骤由 MCP Server 开发 说明。
核心约定:对外交付必须同时包含 MCP Server 和配套 Skill;卡片为可选产物。MCP 工具返回只表达业务事实与操作结果,不携带平台内部生成的运行时标识、内部路由字段或卡片模板配置。
1. 规范范围与术语
本文定义当前平台接入所采用的 MCP 工具协议,重点说明业务 MCP Server 需要提供的工具定义,以及 content、structuredContent 和 isError 三段返回结构。本文进一步规定实体、执行结果和业务错误三类返回,以及这些返回如何与 Manifest、Skill 和可选卡片保持一致。
本文使用“必须”表示强制要求,使用“应当”表示无特殊原因应遵循的要求,使用“可以”表示可选能力。示例中的业务名称和字段仅用于说明结构,不构成统一业务模型。
本文不规定业务系统内部的服务拆分、接口实现、鉴权逻辑、重试、幂等、日志等工程细节;这些内容继续遵循业务团队自身研发规范。本文也不描述平台内部的转换、路由和渲染实现。
2. 协议基线与兼容性
本文的协议基线以当前已确认的工具返回设计为准:业务 MCP Server 直接实现 content、structuredContent 和 isError,并根据工具用途返回实体集合、执行结果或业务错误。业务方不在本规范中自行选择或扩展其他 MCP 版本能力;如平台后续调整接入协议,以更新后的平台文档和开发工具为准。
协议边界。业务侧对工具定义、调用参数和工具返回负责;输出类型、字段用途和可选卡片关联由 Manifest 声明。未在本文或 Manifest 规范中声明的扩展字段,不能作为稳定接入能力依赖。
兼容性原则。工具名称、输入字段和返回字段一旦对外发布,即构成稳定契约。新增可选字段通常属于兼容变更;删除或重命名字段、修改字段类型或语义、把可选输入改为必填输入,都属于不兼容变更。
兼容变更也必须同步评估配套 Skill 和 Manifest。开发者不得仅以“Schema 仍可解析”为由改变工具的业务效果、权限影响或错误语义。
3. 工具定义规范
MCP Server 对外提供工具定义并接收工具调用。当前接入基线要求工具明确提供名称、描述和输入 Schema,使模型能够判断何时调用、需要提供什么参数,以及调用可能产生什么业务效果。
名称要求。工具名称应保持简洁、稳定且可区分,建议采用动作加对象的形式。同一 MCP Server 内不得重名;名称发布后如需调整,应按不兼容变更处理。具体业务命名继续遵循业务团队自身规范。
描述要求。描述应说明工具能做什么、何时适合调用以及重要前置条件。具有写入、提交、发送、支付等外部影响的工具,应在描述中明确其效果。描述不得用来绕过用户意图或诱导模型无条件调用。
输入 Schema 要求。inputSchema 的顶层必须是 object。参数类型、必填性、枚举和格式必须与实际处理逻辑一致;需要必填的字段同时写入 required。无参数工具应显式使用空 object Schema,避免客户端误传任意参数。业务参数校验仍由 MCP Server 负责,Schema 不能替代服务端校验。
4. 工具返回通用结构
业务工具返回采用 MCP ToolResult 风格。平台约定 structuredContent 承载可消费的业务结构化结果,content 承载与该结果一致的自然语言说明,isError 表达工具执行是否失败。
content 和 structuredContent 必须表达同一业务事实。自然语言说明可以概括结构化结果,但不得与结构化字段冲突,也不得把下游必须使用的关键业务数据只放在文本中。
业务返回只包含业务数据。输出类型、实体 Schema、模型可见性和卡片关联由 Manifest 声明;工具返回不得重复这些配置,也不得构造平台内部生成的运行时标识、内部路由字段或卡片模板配置。
5. 实体返回规范
当工具用于查询、搜索、推荐或读取可被后续引用的业务对象时,应使用实体返回。对应工具在 Manifest 中声明为 output.kind=entities,业务工具在 structuredContent.entities 中返回实体数组。
稳定 ID。稳定业务 ID 应来自业务系统,不得为同一实体的每次查询随机生成新值,也不得复用给不同实体。示例使用 entity_id,但本规范不强制业务使用这一字段名。
单实体与多实体。无论返回一个还是多个实体,都使用 entities 数组,不因数量变化切换返回结构。数组中的每个实体都必须独立满足类型、稳定 ID 和 Schema 要求。
实体与卡片。实体返回不等于一定生成卡片。没有配置卡片时,实体仍是合法业务结果,可供模型理解和后续调用使用;是否展示卡片由 Manifest 和卡片产物共同决定。
以下返回不符合规范:直接把实体数组作为 structuredContent;缺少 entity_type;缺少 Manifest 声明的稳定业务 ID;同一字段在不同调用中返回不同数据类型;在业务实体中混入卡片样式或平台运行时字段。
6. 执行结果规范
当工具用于创建、修改、提交、发送、启动或完成某项操作,且返回值主要表达本次操作是否完成及其业务结果时,应使用执行结果。对应工具在 Manifest 中声明为 output.kind=execution_result,业务工具直接把执行结果 object 放入 structuredContent,不增加 entities 包装。
执行结果字段由业务定义,但字段名称、类型和状态语义必须稳定。content 应给出简明结果说明;如果操作失败,应改用第 7 节定义的错误分支,而不是在成功分支中只返回一个表示失败的状态字符串。
7. 错误返回规范
业务工具执行失败时,必须返回 isError=true 的错误分支。本文只规范业务 MCP 服务需要实现的工具错误结构,不展开连接、传输或平台内部错误处理。
平台约定工具执行错误的 structuredContent 至少包含数字类型的 code 和字符串类型的 message。code 用于稳定区分业务错误,发布后不得随意改变含义;message 用于说明错误原因。建议同时在 content 中给出模型和用户可理解、可采取行动的说明。
错误信息不得暴露敏感数据、凭证、内部调用链或仅供排障的实现细节。对于可恢复错误,应说明需要补充或修正的输入;对于不可恢复错误,应明确本次操作未完成,避免模型重复调用造成额外影响。
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 在交付前必须完成协议级验证。业务方不得依赖客户端或平台对不合法返回进行猜测、修复或静默降级。
本地验证应至少覆盖:正常结果、空结果、多个实体、参数错误、依赖失败和兼容性变更后的旧调用。具体调试与发布检查流程参见开发和发布相关文档。
10. 完整示例与字段速查
实体查询工具。下面的工具定义与返回构成一组完整契约。工具名称、输入参数和实体字段应同时出现在配套 Skill 与 Manifest 的相应声明中。
空结果。查询成功但没有匹配实体时,返回空数组;这不是工具执行错误。
常见不合规情况:输入 Schema 与实际参数不一致;成功返回缺少 structuredContent;实体数组直接作为顶层返回;实体缺少类型或稳定 ID;执行结果错误地包在 entities 中;业务失败仍返回成功分支;返回结构与 Manifest 的 output.kind 不一致;Skill 引用不存在或已改名的工具。