接入现实：MCP 与系统集成 · 里程碑长文：把你的系统插到 AI 的 USB-C 口上
这个里程碑要做什么
选一个你自己真实在用的系统——记账本、笔记库、工单系统、待办清单，任选其一——为它写一个 MCP Server，暴露 3–5 个工具（例如：查询余额、新增一笔账、按标签检索），然后在 Claude Desktop 或其他支持 MCP 的客户端里配置好，真实调用成功。
验收画面是具体的：你在 Claude 对话框里用自然语言说「帮我记一笔：午饭 35 元」，打开你的账本，里面真的多了一条记录。
为什么是它（设计意图）
MCP 官方把它类比为「AI 应用的 USB-C 接口」：Server 写一次，所有支持 MCP 的客户端（Claude、VS Code、Cursor 等）都能用。亲手打通一次，你就理解了为什么「把内部 API 包成 MCP Server」是当前最实用的落地方式。
前三个阶段，Agent 的循环是你自己写的；这一阶段你的工具被别人的循环调用——视角反转会逼你重新理解工具设计：name 和 description 写不好，调用方就会用错。安全红线也第一次变得真实：你的 Server 握着真实系统的写权限，「工具即权限——最小权限、只读默认、敏感操作二次确认」将从口号变成你的 schema 设计。工具的命名、描述、参数说明、返回格式，就是模型的全部世界——这是上下文工程最具体的一次实战。给模型的信息要像给新员工的 onboarding 文档：精确、分层、可检索；写得含糊，「新员工」就会用你的工具闯祸，而且祸会闯在你的真实系统里。
还有一个容易被忽视的收益：选自己每天在用的系统，意味着你会成为自己工具的第一个重度用户。调用频率一上来，工具命名是否顺口、返回是否精炼、权限是否碍事，都会以最直接的方式给你反馈——这是任何教程都给不了的设计训练。
配套资源怎么用
- 施工图纸：MCP 官方文档（modelcontextprotocol.io）——先读协议概念（tools / resources / prompts、stdio 与 HTTP 传输），再照你所用语言 SDK 的 quickstart 把骨架跑起来。
- 读源码学设计：MCP Servers 官方合集（github.com/modelcontextprotocol/servers）——挑 filesystem 或 git 这种简单 server 通读，学三件事：工具怎么命名、描述怎么写、错误怎么返回。
- 客户端接入：Anthropic 的 MCP 教程（Building with MCP）讲 Claude 侧的配置方式，照做即可。
- 理论印证：Berkeley LLM Agents MOOC 的 Tool Use 讲次（视频仍可在官网看），从研究视角理解工具调用的能力边界。
- 中文伴手：技术爬爬虾的 AI 工具系列，看中文社区怎么把 MCP 讲清楚、有哪些现成玩法可参考。
- 重读《Building Effective Agents》——这次重点体会「工具是给模型用的界面」这一层意思。
常见翻车点
- 选了一个不属于你的系统：给别人的 API 包 MCP 是练习，给自己每天在用的系统包 MCP 才是里程碑——只有真实使用才会暴露设计问题。
- 工具粒度过大：一个「管理账本」的万能工具，靠 action 参数路由。模型的工具选择准确率会直线下降。一个工具一个职责。
- 描述写成给人看的文档：模型能看到的只有 name 和 description，含糊其辞等于让调用方瞎猜。写清「什么时候该用我、参数什么意思、返回什么」。
- 默认给写权限：第一版请只读。写工具加二次确认（如要求复述操作内容），删除类操作干脆不做。
- 错误返回成 stack trace：模型拿到一堆 traceback 只会懵。错误信息要可操作：「参数 date 格式应为 YYYY-MM-DD」。
- stdio 污染：用 print 调试，日志混进协议通道，客户端直接解析失败。日志走 stderr 或文件。
- 一次暴露 20 个工具：工具越多模型选错概率越高，3–5 个起步，验证稳定后再加。
验收清单
- MCP Server 在 Claude Desktop（或其他 MCP 客户端）配置成功，出现在工具列表
- 至少 3 个工具：含只读查询类与至少 1 个写入类，写入类有二次确认或等效保护
- 自然语言端到端用通：一句话触发工具调用，真实系统状态发生改变
- 每个工具的 description 写清用途、参数含义与返回结构
- 非法参数 / 系统错误时返回可操作的自然语言错误，而非 stack trace
- 权限审计：Server 持有的凭证与连接是完成这些工具的最小权限
- 调试日志不走 stdio 主通道
延伸建议
把「读」和「写」拆成两个 Server 或两组工具，体会权限分层的部署含义。把同一个 Server 挂到 VS Code / Cursor 里——一次实现、处处可用，这就是 MCP 的复利。留意你这一版写下的工具描述：第五阶段做评测时，它会成为你要控制的变量之一。