孔小哥最近我一直在折腾一个方向：AI聊天再好用，它本质上还是个对话框。真正让AI发挥生产力的地方，是它能不能直接碰我们的代码仓库、数据库、本地文件和运维脚本。MCP协议（Model Context Protocol，模型上下文协议）就是奔着这个目标来的。说白了，它给AI应用定义了一套统一的工具调用标准，让客户端可以像插USB一样接入外部能力，而不是每个厂商各写各的私有接口。
这篇文章我按实际落地路径来写：先拆协议本身的架构和设计逻辑，再动手写一个自己的MCP Server，然后把它接入Claude Desktop、Cursor这类客户端，让AI真正操作文件系统、数据库、git工具链。最后会把我踩过的坑、调试思路和排查清单全部整理出来。想用AI做产品、写个人效率工具，或者单纯好奇“AI怎么自己动手干活”的，这篇值得你花半小时完整过一遍。
1. MCP协议到底在解决什么问题
1.1 从Function Calling到MCP：为什么需要一套协议
很多人第一次接触MCP时会有个疑问：OpenAI的Function Calling、各家大模型平台自带的工具调用不是早就有吗，为什么还要一个MCP？
这俩解决的问题层级不一样。Function Calling只是模型侧的一种能力约定——模型知道“哦，我可以在对话里输出一个函数调用指令”，但外部工具怎么被描述、怎么被发现、怎么执行，每家各搞一套。结果就是：你用OpenAI的Function Calling写了一套工具，换到国产模型要重写，换到本地部署的模型又要再适配一次。工具本身是资产，但这种“接口各自为政”的方式，让工具的复用成本变得很高。
MCP的定位是“工具调用的HTTP协议”。它把工具的描述格式（JSON Schema）、调用方式（JSON-RPC 2.0）、传输通道（stdio/HTTP）全部标准化。你写一个MCP Server，理论上可以同时被Claude Desktop、Cursor、Zed、以及任何支持MCP的客户端复用。这就像USB-C一样，接口统一了，设备才能到处插。
1.2 MCP的架构拆解：Host、Client、Server三层各管什么
MCP的架构很清晰，三个角色各司其职：
- Host（宿主）：也就是你正在使用的AI应用，比如Claude Desktop、Cursor、VS Code插件。它负责跟模型交互、收集用户意图、决定什么时候调用工具。
- Client（客户端）：运行在Host内部，每个MCP Server对应一个Client实例。它负责建立连接、维护会话、把Server的协议消息转换成Host能理解的事件。
- Server（服务端）：真正干活的进程。它暴露工具、资源和提示词三类能力，通过stdio或HTTP与Client通信。
这里面最值得注意的一点是：每个Server都是独立进程。这意味着你的工具服务可以跟AI应用完全解耦，写一个独立的Python脚本就够，不依赖你的主应用语言。我在实际项目中甚至把一个内网服务封装成了MCP Server，供团队里不同成员的不同客户端共用。
1.3 三大原语：Tools、Resources、Prompts
MCP协议定义了三大能力原语，很多人一开始只关注Tools，其实另外两个同样重要：
- Tools（工具）：模型可以主动调用的函数。有输入参数、有返回结果，适合执行动作，比如“查一下当前目录结构”“执行这条SQL”。
- Resources（资源）：可被读取的数据或文件，模型不会主动调用，而是由用户或Host按需加载。比如项目的README、配置文件、数据库Schema文档。
- Prompts（提示词模板）：预置的复用提示词，相当于把常用操作固化成模板。比如“帮我总结这个项目的架构”，一键触发。
在设计Server时，我的习惯是：能作为资源暴露的不要做成工具，能作为工具暴露的不要做成提示词。资源是被动读取的，安全风险低；工具是模型主动触发的，权限和副作用要把控严格。这个边界感很重要，后面讲安全的时候还会再提到。
需要模型API调用？ 免费领10W Token，多模型网关一键接入 Claude、DeepSeek 等主流模型。
2. 让AI真正“动手”的关键设计
2.1 为什么是JSON-RPC 2.0而非REST
MCP的通信协议选的是JSON-RPC 2.0，而不是我们更熟悉的REST风格。这个选择背后是有考量的。
REST的核心是资源导向，靠URL和HTTP动词来表达意图。但MCP场景里，客户端和Server之间是长连接的、双向的交互——模型要发工具调用请求，Se