MCP Server 概念与设计原则
本文面向准备在豆包中提供业务工具能力的开发者,重点说明 MCP Server 的定位、能力边界和高层设计原则。本文不展开字段协议、开发步骤和调试命令;具体实现与精确协议分别参见 MCP Server 开发 和 MCP Server 协议规范。
定位与术语
MCP Server 是遵循 MCP 向模型提供工具能力的服务端组件。一个 MCP Server 可以提供一个或多个 MCP 工具;MCP Server 是能力的服务载体,MCP 工具是模型可以发现和调用的具体业务能力。本文讨论 MCP Server 的整体边界,也重点说明其中 MCP 工具的设计原则。
在豆包能力体系中,业务系统继续负责领域数据和业务逻辑,MCP Server 负责把可复用的业务能力表达为稳定的工具契约,配套 Skill 负责说明这些工具在具体场景中的使用方式。业务方不需要为了接入模型而改变已有业务系统的核心实现。
MCP Server 不是普通业务 API 的简单转发层,也不应把已有接口逐个复制为工具。普通业务 API 主要服务确定性的程序调用;MCP 工具还需要让模型理解它代表什么业务意图、何时适合调用,以及调用结果意味着什么。
MCP Server 与 Skill、卡片的关系
MCP Server 是能力主体,回答“能做什么”;Skill 是使用说明,回答“在什么场景、以什么方式使用”;卡片是可选的展示能力,回答“如何把结果更合适地呈现给用户”。
MCP Server 与 Skill 必须配套。仅提供工具而没有 Skill,模型可能无法稳定判断何时使用,或者无法在多工具之间形成正确的调用策略。二者应在工具语义、使用条件和结果理解上保持一致,并作为同一个能力单元共同演进。多个工具共同完成一个业务流程时,应由配套 Skill 描述选择条件、调用顺序和必要的衔接方式。MCP Server 保持每项能力边界稳定,Skill 负责把这些能力组合为面向具体场景的解决方案。
卡片按场景选配。当结果包含适合结构化浏览、比较或操作的信息时,可以通过卡片提升体验;当自然语言已经能够清楚表达结果时,无需为了展示形式强行接入卡片。卡片不应改变工具的业务语义,也不应成为理解工具结果的唯一前提。
MCP Server 的业务数据需要与卡片展示解耦。MCP Server 表达业务事实和操作结果,卡片负责展示结构与交互方式。这样可以在不改变工具能力的情况下调整展示,也可以让没有卡片的场景继续使用同一项能力。
适用场景与能力边界
MCP Server 应提供具有明确业务含义、能够独立说明并可被模型安全调用的能力。它面向模型表达必要的输入、业务结果和失败语义,但不承担与工具能力无关的会话编排、界面展示或业务系统治理职责。
一项能力通常在满足以下条件时适合通过 MCP Server 提供:
- 对应清晰、可描述的用户目标或业务目标;
- 能够形成相对稳定的业务语义,而不是短期页面操作或内部流程步骤;
- 模型可以基于明确上下文判断是否需要调用;
- 调用结果能够帮助模型或用户继续完成任务;
- 能力所涉及的身份、权限、隐私和风险边界可以被清楚界定。
对话策略和多工具使用流程由 Skill 表达,展示样式和用户交互由卡片等展示能力承接。业务逻辑、业务鉴权、数据治理和服务稳定性继续遵循业务团队自身的研发规范;豆包侧的用户身份和权限模型参见 用户身份与权限模型。平台内部链路和实现细节不应成为业务方设计工具时的依赖。
如果一项能力只能依赖大量隐含上下文才能使用,或只是内部实现中的一个过细步骤,通常应先重新梳理业务边界,而不是直接设计为 MCP 工具。
设计原则
选对该实现的 Tool,而不是把 API 全搬过来
工具设计需要以业务能力为中心。从用户希望完成的目标出发抽象工具,而不是从已有接口列表出发。工具名称和边界应表达业务含义,避免把内部服务名、流程节点或技术实现直接暴露给模型。
工具设计需要边界清晰且可组合。一个工具应承担一个连贯的业务职责,能够独立说明、独立判断是否调用,同时可以通过 Skill 与其他工具组合成完整流程。
常见错误是把已有的 REST 接口逐个封装为 Tool。模型上下文有限,list_all_* 这类返回大列表的 Tool 会消耗大量 token,且无法帮助模型做出决策。
- 少而准 > 多而散:一个 MCP Server 内的 Tool 数量不超过 15 个,超过时应拆分或合并。
- 每个 Tool 都要有清晰、唯一的目的:让模型能够像人一样把任务拆解到正确的 Tool 上;功能重叠的 Tool 会让模型反复犹豫。
- 每个决策节点对应一个 Tool:例如,“查门店 → 查商品 → 下单”三个步骤对应 3 个 Tool。
- 用搜索代替罗列:把
list_contacts换成search_contacts(query),让服务端做过滤,只返回模型真正要的几条。
工具拆分应围绕用户可感知的业务子目标进行。理想的工具粒度既不是内部接口的一一映射,也不是覆盖整个业务领域的“万能工具”,而是在单次调用中完成一个边界明确、结果可判断的业务动作。
拆分时可以依次判断:用户是否能够说清这次调用要完成什么;工具是否可以独立描述其成功结果;模型是否能够与相邻工具区分;调用是否包含不同风险或不同性质的动作。如果一个工具同时包含查询、选择和不可逆执行等多类职责,通常应重新评估边界。
命名与 Schema 要严格,字段要语义化
工具 Schema 需要语义化,对模型友好。模型应当能够从显式信息中理解工具用途,不依赖只有业务研发人员知道的隐含知识。不同工具之间应有清楚的语义区分,避免名称相近、职责重叠或使用条件冲突。
关于命名与 Namespace:
- 需要动词开头 + lowercase snake_case:
brewnow_create_order✅;禁止search/get/find这类泛名 ❌(模型会乱选)。 - 服务前缀必加:
brewnow_*、kfc_*,避免跨 MCP Server 同名工具混淆。 - 需要时再加资源前缀:工具量大时用
brewnow_orders_search、brewnow_stores_search这样的"服务_资源_动作"三段式,帮模型按资源做选择。 - 参数命名要消歧:用
user_id而不是user,用store_id而不是store,避免模型把名字、ID、对象混在一起。
关于参数命名:
- 所有参数都带 description,enum 必须穷举合法值,关键字段附
examples。 additionalProperties: false+strict: true:拒绝模型瞎传字段,宁可报错也不要静默吞掉。- 返回结构稳定:无论有没有结果,顶层字段集合不变;schema 描述的字段必须真实存在,schema 没承诺的字段不要默默冒出来。
- 返回有意义的上下文:优先用
name/store_name/file_type这种语义化字段,避免把uuid/mime_type/256px_image_url这种纯技术 ID 当主键暴露给模型。 - 支持
response_format: "concise" | "detailed":默认 concise 省 token,模型需要下钻时再换 detailed;必要时也可以把分页 / 截断 / 过滤参数加上默认值,避免一次返回打爆上下文。
错误必须告诉模型“下一步怎么改”
错误响应是最被忽视、但对模型最关键的部分——正常路径出错的概率约 10%,而错误路径出错后模型继续做错事的概率高达 90%。失败需要可理解、可恢复。失败结果应帮助模型和用户判断发生了什么,以及是否可以补充信息、调整请求或稍后重试。具体错误结构遵循协议规范。
升级时需同步评估对 Skill 及卡片的影响
契约稳定且可演进。工具一旦被 Skill 和场景使用,其核心语义就形成了对外承诺。新增能力应优先采用兼容方式;必须改变既有语义时,应明确升级路径并同步评估相关 Skill 和卡片。
隐私原则
最小必要暴露。只向模型提供完成目标所必需的能力和数据,避免暴露与当前任务无关的信息。涉及用户数据、敏感操作或不可逆行为时,应优先明确权限、隐私和风险边界。
以上原则关注 MCP Server 对外能力的设计,不替代业务服务已有的安全、稳定性、合规和工程质量要求。
能力演进与设计检查
MCP Server 的能力设计可以先在边界明确的场景中验证。验证重点是模型能否稳定理解和选择工具、工具结果能否支持后续任务,以及能力边界是否适合复用。能力升级应以保持既有语义为默认原则,MCP Server、Skill 和选配的卡片需要同步评估和更新。
在进入开发前,建议检查:
- 该能力是否确实适合由模型调用;
- 工具是否对应清晰、可描述的业务目标;
- 职责是否连贯,是否存在过细、过宽或与其他工具重叠的问题;
- 模型是否能在不依赖内部知识的情况下理解并选择工具;
- 调用结果是否足以支持模型或用户继续完成任务;
- 是否提供了与工具实际能力一致的配套 Skill;
- 是否确有卡片展示需要,无卡片时结果是否仍可理解;
- 工具核心语义是否稳定,后续扩展是否能够保持兼容;
- 身份、权限、隐私和高风险操作边界是否明确。
如果其中多个问题无法明确回答,建议先调整能力抽象,再进入具体开发和协议设计。
开发过程中,建议按照下述七个维度的规则进行自检;工具定义以 MCP Server 的 tools/list 返回为准,工具结果以 tools/call 的原始返回(raw MCP response)为准,重点检查其中的 content、structuredContent 和 isError。
MCP 小程序开发产物质量 Checker 规则目录
七维规则总览
规则明细与执行方式
以下表格中的返回字段均指 MCP Server 直接返回的 ToolResult;实体数据位于 structuredContent.entities[].result,执行结果直接位于 structuredContent。具体结构参见 MCP Server 协议规范。
T-PROTO 协议与结构
T-NAME 命名与描述
T-SCHEMA 入参与校验
T-OUT 输出与数据契约
T-ERR 错误处理
T-PERF 性能与稳定性
T-SAFE 安全与副作用
下一步
- MCP Server 开发:了解实现、接入和验证流程。
- MCP Server 协议规范:查阅工具定义和返回协议的精确要求。
- Skill 规范、Skill 开发:了解配套 Skill 的设计与编写方法。
- 卡片设计规范、卡片(Widget)开发:在确有展示或交互需要时设计和开发卡片。
- Manifest 配置规范:查阅工具、实体和卡片配置要求。