接一个 MCP Server

第一步：先接一个现成的

自己写之前，先接一个官方或社区维护的 server，把流程走通。配置通常包含三样：

{
  "mcpServers": {
    "example": {
      "command": "启动命令",
      "args": ["参数"],
      "env": { "需要的环境变量": "值" }
    }
  }
}

不同客户端的配置文件位置不一样，以官方文档 的 quickstart 为准。本地 server 多用 command + args 直接拉起进程。

第二步：确认工具真的可用

配置完不要假设成功，验证三件事：

1. 客户端能看到工具清单：说明连接建立、schema 读取成功。
2. 模型会选它：问一个明显该用该工具的问题，看它是否发起调用。
3. 结果回得来：工具返回的内容出现在回答里，而不是「调用失败」。

第 2 步最容易出问题：工具的描述写得含糊，模型就不会选它。 比如工具叫 fetch、描述是「获取数据」——模型不知道获取什么数据。 改成「抓取指定 URL 的网页正文，返回纯文本」，命中率会明显不同。

第三步：写一个最小 server

用官方 SDK（TypeScript 或 Python），只做一个工具：

工具名：word_count
描述：统计给定文本的字数和行数
参数：text（字符串，必填）
返回：{ chars, lines }

三个要点：

• 描述写给模型看：它决定模型会不会选这个工具；
• 参数 schema 收紧：类型、必填、范围都写清楚；
• 返回要短：工具结果会进上下文，一次返回几万字会挤掉真正的内容。

第四步：本地接线

1. 把 server 跑起来（stdio 模式下由客户端拉起，不用手动启动）；
2. 在客户端配置里加上它；
3. 重启会话，确认工具清单里出现 word_count；
4. 用一段文本试一次，核对返回的数字。

第五步：加边界

能用的下一步是「能安全地用」：

• 只读优先：先做查询类工具，写操作后加；
• 白名单：文件路径、域名、命令都限定范围；
• 超时：工具调用要有超时，否则一个卡住的请求会拖死整轮对话；
• 日志：记录每次调用的参数和返回大小，排障和算成本都用得上。

常见错误

• 工具描述太泛：模型不知道什么时候该用。
• 返回整篇文档：上下文被一份工具结果吃光。
• 没有超时：外部服务一慢，整个会话卡住。
• 把权限交给模型：危险操作要在 server 侧校验，不是靠提示里写「不要」。

自测

1. 你的 server 提供的工具，描述能让一个不了解项目的人看懂吗？
2. 工具返回的内容有多大？占了多少上下文？
3. 如果模型连续调用同一个工具十次，会发生什么？

下一步

• 协议与角色：MCP Server 是什么
• 工具循环的边界：给模型一个工具
• 上线前检查：上线前过一遍这张清单