AI 工具与出海建站的账本。

首页 / 工作流与 MCP / 写一个 MCP server:工具设计的四条约束

写一个 MCP server:工具设计的四条约束

工具越多模型越笨。四个约束帮你把 server 做成"少而准",而不是"全但没人用"。

2026年9月23日 7 分钟读完 naket.top 更新 2026-09-29
写一个 MCP server:工具设计的四条约束

MCP server 最常见的失败不是技术问题,是"给了十个工具,模型一个都不爱用"。原因是描述含糊、返回太大、或者工具之间职责重叠。

约束一:工具数量控制在 3–5 个

每个工具的描述都会占上下文。十个工具的 server,光描述就能吃掉几千 token,而且模型要在里面做选择——选择成本比执行成本高。

一个知识库 server,三个工具就够:检索、读取、列目录。

约束二:描述写"什么时候用",不写"它是什么"

差:search_notes: 搜索笔记 好:search_notes: 按关键词检索本地笔记的标题与正文;当用户问"我以前记过什么"或需要引用自己的旧笔记时使用

差别在于后者告诉模型触发条件。

约束三:返回要小、要带定位

返回整篇文章会烧上下文。返回"前 3 条命中 + 每条的片段 + 行号"才是可用形态:

{
  "hits": [
    {"path": "70-服务器/3x-ui.md", "line": 12, "snippet": "…salamander…"}
  ]
}

有了行号,模型可以二次读取精确区间,而不是整篇吞进去。

约束四:错误信息要能指导下一步

差:{"error": "failed"} 好:{"error": "file not found", "hint": "用 list_tree 确认路径;注意排除 98-剪报 目录"}

模型不会猜,它只会照着提示做。错误信息写得具体,等于把排障知识前置到了工具层。

一个反例

我第一版写了七个工具(搜索、标签、日期范围、统计、导出…),结果模型几乎只用搜索。删到三个之后,使用率反而上升。

工具不是越多越好,是越准越好。

再加一条:不要做"万能工具"

run_shell(command) 这类工具看起来很强大,实际是灾难:模型会把复杂逻辑塞进一条命令里,出错时你无法从返回值判断哪一步错了。

正确做法是拆成有语义的工具:list_files、read_file、search_text。每个工具只做一件事,返回值结构固定,模型才学得会。

参数的写法

参数名要能自解释:q 不如 keyword,p 不如 path。类型尽量用枚举而不是自由字符串——format: "json"|"text" 比 format: string 少一半误用。

版本与兼容

工具描述改动会影响模型行为,等同于改接口。加工具可以,改已有工具的参数名要谨慎——最好新增一个工具,旧的标记 deprecated,跑一段时间再删。

一句总结

MCP server 的成败不在协议实现,在工具描述写得像不像给新人看的说明书。

一个真实案例

把"读数据库"做成一个 query(sql) 工具,模型很快就开始拼复杂 join,出错时只拿到"语法错误"。改成 list_tables、describe_table、sample_rows(table, limit) 三个工具后,模型反而能自己一步步查对——因为每一步都有确定返回值。

结论很直白:工具的粒度决定模型的成功率,不是模型不够聪明。

最后一个实践:先本地、再远程

本地 stdio 版本调试成本最低——日志直接打在终端里,改一行立刻重启。等工具语义稳定了,再包成远程 HTTP 服务,加上鉴权和限流。顺序反了,你会在排查网络问题里耗掉大部分时间。

MCP工具设计协议

延伸阅读

MCP 规范 ↗