波仔
🐎 第6章 海纳百川：MCP
📄 一句话概括

配置有两种写法：命令行一条命令搞定，或者写进 .mcp.json。后者才是能进版本库、团队共用的形式。 演示里四份配置只过了一份。问题集中在两处：密钥明文、缺启动命令——都写得很像对的。

📝 本章和前面几章的关系

上一节选定了传输方式，这一节把它落成配置。 配置本身不难，难的是「放哪儿」——四个作用域，放错了不是不生效，就是把自己或团队的密钥泄出去。

一、两种写法

命令行：一次一条，落在用户级配置里。试的时候用，快，不用建文件。 .mcp.json：项目根一个文件，跟着仓库走。团队共用、能评审、能回滚。 差别不在功能，在「谁能看见、能不能审」。团队要用的东西必须能进版本库，否则没法评审。

所以试的时候用命令行，定了就搬进 .mcp.json——这个顺序比反过来省事。

二、四份配置逐个检查

演示里四份：一份干净的 stdio、一份带密码的、一份 HTTP 带 token 的、一份只有 args 没有 command 的。 结果只过了一份。另外三份的问题：两份密钥明文，一份缺启动命令。 缺 command 那份最典型：服务器根本起不来，但配置里「写了好几个字段」，看起来很像是对的。

而它报出来的现象是「连不上」，不是「配置错了」——这就是为什么这类错查起来慢。

三、密钥明文是最常见的一条

把密码写进 .mcp.json，文件一进版本库，密码就跟着进了历史。后面删掉也没用，历史里还在。 正确做法是用环境变量占位：配置文件里写变量名，真实值由运行环境提供。 这一条不复杂，但每年都有人栽在上面，因为「先跑通再说」的时候最顺手。

更麻烦的是它不会报错：密钥明文写着，功能一切正常，直到某天有人翻了仓库历史。

四、配置的位置与作用域

用户级：跟着人走，所有项目都有。放个人常用的小工具。 项目级：进版本库，团队共用。放这个项目要的服务器。 项目本地：不进版本库。放本机特有路径、个人密钥。

企业级：统一下发。放合规网关、审计这类必须统一的东西。 一条实用约定：能进版本库的放项目级，带密钥的放项目本地。前者让别人省事，后者让自己安全。

五、为什么作用域要分四层

因为「谁需要看见」和「谁能改」是两件事。用户级别人看不见，项目级谁都能改。 分层的目的是让默认行为正确：不确定放哪儿的时候，选最小的那一层。 放小了顶多是自己多配一次；放大了是所有人都被影响，还可能把密钥带进历史。

这和记忆层的规矩是同一条：范围越大放得越靠上，但靠上的内容必须真的通用。

六、动手 Demo：四份 MCP 配置，三份有毛病

配置有两种写法：命令行一条命令搞定，或者写进 .mcp.json。后者才是能进版本库、团队共用的形式。 这里把四份真实形态的配置拿出来逐个检查。

CFG = [(u"mini-notes", u"stdio", [u"command", u"args"], True),
       (u"pg", u"stdio", [u"command", u"args", u"env"], False)]

ok = sum(1 for _n, _t, _k, clean in CFG if clean)

实跑输出：

--------------------------------------------------------------------
四份 MCP 配置，三份有毛病
--------------------------------------------------------------------

  配置有两种写法：命令行一条命令搞定，或者写进 .mcp.json。后者才是能进版本库、团队共用的形式。

  ① 两种写法的区别
  --------------------------------------------------------------------
| 形式 | 落在哪 | 适合 |
|---|---|---|
| 命令行 | 一次一条，写进用户级配置 | 试的时候用 |
| .mcp.json | 项目根一个文件，进版本库 | 团队共用 |


  ② 四份配置逐个检查
  --------------------------------------------------------------------
| 名字 | 类型 | 字段数 | 结论 |
|---|---|---|---|
| mini-notes | stdio | 2 个字段 | 通过 |
| pg | stdio | 3 个字段 | 密钥明文 |
| todo | http | 2 个字段 | 密钥明文 |
| broken | stdio | 1 个字段 | 缺 command |

  四份里 1 份通过。
  另外三份的问题：一份缺启动命令（只有 args 没有 command，服务器根本起不来），
  两份把密钥明文写进了配置。

  ③ 密钥明文是最常见的一条
  --------------------------------------------------------------------
  把密码写进 .mcp.json，一旦这个文件进了版本库，密码就跟着进了历史。删掉也没用——历史里还在。
  正确做法是用环境变量占位：配置文件里写变量名，真实值由运行环境提供。
  这一条不复杂，但每年都有人栽在上面，因为「先跑通再说」的时候最顺手。

  ④ 配置的位置与作用域
  --------------------------------------------------------------------
| 位置 | 范围 | 放什么 |
|---|---|---|
| 用户级 | 跟着人走，所有项目都有 | 个人常用的小工具 |
| 项目级 | 进版本库，团队共用 | 这个项目要的服务器 |
| 项目本地 | 不进版本库 | 本机特有路径、个人密钥 |
| 企业级 | 统一下发 | 合规网关、审计 |

  ! 一条实用约定：能进版本库的放项目级，带密钥的放项目本地。前者让别人省事，后者让自己安全。

①两种写法的差别不在功能，在「谁能看见、能不能审」：命令行落在用户级配置里， 点 mcp.json 跟着仓库走。团队要用的东西必须能进版本库。 ②四份里只过了一份。 另外三份的问题：一份缺启动命令（只有 args 没有 command，服务器根本起不来）， 两份把密钥明文写进了配置。 ③密钥明文这条最坑的是它不报错：功能一切正常，直到某天有人翻了仓库历史。 正确做法是用环境变量占位，配置里只写变量名。 ④四个作用域：用户级放个人小工具、项目级放团队共用的、项目本地放本机路径和个人密钥、 企业级放合规网关和审计。 一条实用约定：能进版本库的放项目级，带密钥的放项目本地。前者让别人省事，后者让自己安全。

30 秒实验

  1. 把那份缺 command 的补上启动命令，重跑一遍。它还会被拦吗？ 为什么「补上就过」这件事不能说明它原来没问题？
  2. 给两份密钥明文的改成环境变量占位，重跑一遍。现在就全过了吗？ 还有哪一条检查是这套规则查不出来的？
  3. 把项目级的配置挪到用户级，重跑一遍。检查能通过，但团队里其他人会怎样？

常见误区

  1. 把密码、token 直接写进 .mcp.json。文件一进版本库，密码就进了历史，删掉也没用。
  2. 配了 args 忘了 command。服务器根本起不来，而现象只是「连不上」。
  3. 团队共用的服务器只配在自己机器上。别人拉下代码还得问你怎么配。
  4. 本机特有路径写进项目级配置。别人拉下来一跑就是错的路径。
  5. 把不确定的东西放用户级。作用域放大了，所有人都被影响。
自测三问（点开对答案） 1. 命令行配置和 .mcp.json 该分别在什么时候用？ —— 试的时候用命令行，快；定了就搬进 .mcp.json，能进版本库、能评审、能回滚。 2. 密钥为什么不能写进 .mcp.json？ —— 文件进版本库后密钥就进了历史，后面删掉也没用。应该用环境变量占位，配置里只写变量名。 3. 四个作用域分别放什么？ —— 用户级放个人小工具、项目级放团队共用的、项目本地放本机路径和个人密钥、 企业级放合规网关和审计。

配置会写了，下一节拿数据库练手：把「查一下有多少条订单」包成两个工具。

相关笔记