白话机器学习

OpenAI 的 tools 字段、Anthropic 的 tool_use、Gemini 的 functionDeclarations 格式细节都不同，必填字段和枚举处理也有差异。我有个项目从 GPT 迁到 Claude，工具定义改了一整天。用 MCP 把工具抽到服务端，模型侧只管调 MCP 客户端，迁移成本就低多了。

我把一个 MCP 服务端部署给异地团队用，第一版用 stdio，结果跨网络根本连不上。换成 SSE 能跑了，但又踩了双端点的坑。最后迁到 Streamable HTTP 才算稳。这篇把三种传输模式掰开揉碎讲清楚，配上可直接切换传输模式的代码，让你知道每种模式该用在哪。

我之前给团队写过一个批量数据导出工具，跑一次要好几分钟。用户每次都来问我，到底是卡死了还是在干活。后来我把 MCP 的进度通知接上，界面能实时显示处理到第几条，问题一下子就没了。这篇就来聊聊 MCP 里那些容易被忽略的交互细节，包括自动补全、进度上报、日志推送和资源变更通知，配套可运行的代码。

去年我做一个部署工具的MCP Server，工具接收一个服务名就执行部署。结果有次模型把生产环境的服务名传进来直接部署了，差点酿成事故。我赶紧加了个硬编码的环境判断，治标不治本。后来MCP规范推出了Elicitation原语，我让工具在执行前向用户确认"确定要部署到production吗"，用户点同意才继续。从此再没出过误操作。这篇我把Elicitation这个交互机制完整讲一遍，它是MCP五大原语里最后一个，也是最贴近"人机协作"的一个。

前段时间我做一个数据分析工具，工具内部需要让大模型对查询结果做一轮摘要再返回。我一开始的方案是在Server里硬塞一个OpenAI的API Key，直接调GPT。结果上线第二天安全团队找上门，说Server里不该存API Key，而且不同用户想用不同模型也没法满足。后来我改用MCP的Sampling原语，Server不持有任何Key，需要LLM时反向请求Client，由Client用自己的模型能力生成结果。这篇我把这个"逆向通信"机制讲清楚。

前阵子我给团队维护一坨提示词，散落在十几个Python文件里，每人写法都不一样，有人把system prompt硬编码，有人用f-string拼，改一个变量得全局搜一遍。后来我把这些提示词迁移到MCP的Prompts原语里，统一用参数化模板管理，客户端能自动发现并填参数，团队再也没为"谁的提示词版本对"吵过架。这篇我把Prompts原语的设计理念和用法讲透。

上个月我给团队搭了个代码审查助手，想让模型读项目里的配置文件和日志。我第一反应是用Tools写个read_file工具，结果发现模型每次都要"决定调用"一下，对话里塞满了工具调用的噪音，而且同样的文件读了好几遍。后来我改用MCP的Resources原语，把文件作为资源暴露出去，客户端自己决定何时把内容塞进上下文，对话干净多了。这篇我把Resources从URI设计到订阅机制完整讲一遍。

上周我在做一个内部运维助手的demo，想让大模型帮我查线上服务的健康状态。我一开始图省事，直接把几个HTTP接口塞给Function Calling，结果换了模型厂商就得重写一遍schema，写到第三个的时候我已经麻了。后来我把这些接口改造成MCP的Tools原语，用FastMCP统一注册，模型只要支持MCP就能自动发现和调用。这篇我就把Tools从协议定义到调用流程完整拆一遍，附带可直接跑的代码和我踩过的几个坑。

我第一次抓包看MCP的通信内容时有点懵，消息里全是jsonrpc、method、params这些字段，看起来跟HTTP API完全不一样。后来才知道MCP底层用的是JSON-RPC 2.0协议，一个比我预想中更简洁的RPC规范。搞懂JSON-RPC 2.0之后再看MCP的消息流就豁然开朗了，所有工具调用、资源读取、能力协商的本质都是JSON-RPC消息的收发。这篇文章把JSON-RPC 2.0的规范和MCP的使用方式完整讲清楚，配上真实的消息示例。

我花了不少时间才把MCP的架构彻底搞明白。一开始我以为就是客户端连服务端那么简单，后来发现协议里分了Host、Client、Server三个角色，加上传输层和生命周期管理，整个体系比想象中复杂。这篇文章我把MCP的三层架构、组件职责、通信流程和生命周期管理从头到尾梳理一遍，配上ASCII图和表格，帮你建立完整的架构认知。

我第一次写 MCP 服务端用的是低级 API，注册工具要写一堆装饰器，初始化要手动拼 InitializationOptions，跑起来还得自己管 stdio 流。后来换成 FastMCP，同样的功能代码量少了七成。这篇把 FastMCP 的装饰器 API、生命周期管理、配置体系讲清楚，再跟低级 API 做个对比，最后给一个完整可运行的项目。

把上面10个错误按类别归一下。类别错误编号共性问题环境配置二、三、六、七依赖版本、模块系统、环境变量、路径格式协议理解五、八、九握手顺序、能力协商、消息格式代码实现一、四输出通道、返回格式调试排查十超时处理、进度反馈环境配置类的错误最多，占了4个。这些错误的特点是代码逻辑没问题，但因为运行环境差异导致失败。解决办法是固定开发规范，zod锁版本、ESM必声明、路径用绝对正斜杠、环境变量显式传。协议理解类的错误最隐蔽，因为握手看起来成功了，只有用到特定功能才暴露。

我写完第一个MCP Server后兴冲冲地配到Claude Desktop里，结果Claude那边毫无反应，连个报错都没有。我在终端手动运行server，只看到光标闪了闪就没了。调试了快两个小时，最后用MCP Inspector一连接，立刻发现是工具的inputSchema写错了，zod的类型定义跟实际参数对不上。从那以后Inspector成了我开发MCP Server的标配工具，这篇文章把它的安装、使用和调试技巧完整讲一遍。

我第一次写MCP Server用的是Python，因为官方文档的入门示例就是Python版。后来项目组要求统一技术栈，我得用TypeScript重写一遍，结果发现TypeScript SDK的API设计跟Python版差别还挺大，踩了不少坑。这篇文章把我用@modelcontextprotocol/sdk从头搭建一个完整MCP Server的过程记录下来，包含Tools、Resources、Prompts三种能力的完整实现，最后跟Python版做个横向对比。

前面四篇我们用的都是Tools，定义个函数让AI调用。但MCP其实有三类原语，Tools、Resources、Prompts。很多人写了一堆Server只用Tools，根本没碰过另外两个。我一开始也这样，直到有天我想让AI读一份固定的配置，每次都让模型调工具去取，来回一轮对话才拿到数据，又慢又费token。后来我把那份配置改成Resource，AI启动时就能直接读到，省了一大圈。三种原语各有定位，用对了能让Server更高效更好用。

前三篇我们写的Server都偏演示性质，算个加法阶乘没啥实际用处。这篇来个真东西，一个能查本地文件的MCP Server。我之前做项目时经常需要让AI帮我翻代码库里的某个函数实现，或者读某个配置文件的内容。手动复制粘贴太累，于是我用MCP写了个文件搜索Server，让AI自己去找、自己读。这篇我把完整实现分享出来，包括路径安全校验这个重头戏。

上一篇我们写了个计算器Server，在MCP Inspector里跑通了。但Inspector只是调试工具，真正用起来，得让AI客户端认识你的Server。我当时第一次接Claude Desktop，配了半天没反应，重启了五六次才搞明白是路径写错了。Cursor那边更折腾，配置文件位置找了半天。这篇我把两个主流客户端的接入方法一次性讲清楚，附上我踩过的连接坑和排查思路。我们继续用上一篇的，看看它在Claude Desktop和Cursor里被AI调用的完整效果。

上周有个读者私信我，说看了MCP的概念觉得很棒，但上手时卡在第一步，装了半天环境跑不起来。我让他把报错发过来一看，Python版本太低，又混装了fastmcp和官方mcp两个包，依赖打架。其实跑通第一个Server真的不难，难在没人把那些隐藏的坑提前告诉你。这篇我带你从零开始，用Python写一个能跑的MCP Server，定义一个工具，再用官方调试工具测一把。我把每一步踩过的坑都标出来，照着做不会翻车。

我去年帮一个客户做AI助手，需求很简单，让Claude能查公司内部的工单系统。我兴冲冲写了一堆function calling的函数，接通那天演示得很顺。结果第二周客户说想换ChatGPT，第三周又想接Cursor。每换一个宿主，我那套工具定义就得重写一遍，参数格式、调用约定全都不一样。那段时间我加班到凌晨两点，盯着屏幕上三个版本的胶水代码，心里只有一个念头，这事儿不该这么难。

80篇文章写完了。从第一篇"MCP是什么"到最后一篇"MCP工具商业化"，整整80篇，覆盖了从协议原理到企业架构到商业变现的完整链路。回头看看，这80篇文章其实就是我在MCP领域踩坑、实践、总结的全过程。文章里每一行代码都跑过，每一个结论都验证过。今天就做个总结，把这80篇文章的核心认知串成一张图。

把整个路径梳理一下。阶段一：开源验证（1-3个月）目标：验证需求，积累用户收入：零重点：做好基础功能，写好文档阶段二：需求挖掘（4-6个月）目标：发现高频需求，找到愿意付费的用户收入：少量定制开发费重点：跟用户聊天，了解真实场景阶段三：混合模式（7-12个月）目标：核心开源，高级功能收费收入：License费 + 技术支持费重点：功能拆分，定价测试阶段四：SaaS化（12个月以后）目标：云服务，按量计费收入：订阅费 + 调用费重点：运维保障，SLA承诺。

上个月有个在银行做技术架构的朋友找我喝酒，说他们部门有十几个团队都在搞AI Agent，每个团队自己搭自己的MCP Server，重复造轮子严重。A团队写了个查行内数据库的MCP Server，B团队不知道，又写了一个一模一样的。更要命的是安全团队开始介入了，说这些MCP Server散落在各处，没有统一管理，审计根本没法做。他问我有没有办法搭一个企业内部的MCP工具市场，让所有团队的MCP Server集中管理。我说这事我正好做过，今天就跟你聊聊怎么搭一个私有MCP Hub。

前阵子有个读者私信我说"你能不能推荐几个好用的MCP Server？这让我意识到，MCP生态已经发展到了一个阶段，光靠官方那几个Server已经不够看了，社区里的开源MCP Server才是真正的宝库。但用第三方代码这事，安全和可靠性是绕不过去的问题。今天这篇，我带你逛一遍MCP工具市场的全景，从怎么发现、怎么评估到怎么安全使用，完整走一遍。

我在做一个数据分析Agent项目的时候，遇到了一个让我困惑了好几天的问题。我给Agent注册了一个MCP工具叫"query_database"，同时又在Skills配置里声明了一个同名能力"query_database"。结果Agent运行的时候，有时候走MCP，有时候走Skills，行为完全不可预测。折腾了两天我才搞明白，Skills和MCP虽然都是给Agent加能力的，但它们的定位、运行机制和适用场景完全不同。混在一起用会出大问题。今天这篇，我把两者的本质区别、互补关系和正确用法讲清楚。

上周有个朋友找到我，说他们团队在搭一个多Agent协作平台，问我说"你看我们到底该用MCP还是A2A？“我当时愣了一下，因为这问题本身就问错了。MCP和A2A压根不是同一层的东西，就像问"该用螺丝刀还是锤子”，答案是都得用。这事让我意识到，很多人对Agent协议生态的全貌其实是很模糊的。今天这篇，我就把目前主流的五大Agent协议都摊开来讲，MCP、A2A、ARD、AP2、ACP，一个一个捋清楚。看完这篇，你应该能在选型时不犯迷糊。

去年年底的时候，我部署了一个多Agent系统到公网上。客服Agent通过A2A调用退款Agent，退款Agent能操作退款数据库。我当时觉得反正是内网通信，没加认证。结果上线第三天，有人扫到了我的端口，直接发了个A2A请求过去，退款Agent老老实实执行了退款操作。那次事故让我意识到，Agent之间的通信安全不是可选项，而是必须项。你的Agent暴露在网络上，任何人都可以发HTTP请求过来。如果没有认证和授权机制，你的Agent就是别人的免费工具。

前段时间我在做一个自动化开发工具的demo，想让AI自己完成一个完整的软件开发流程。需求很简单，写一个计算器模块，包含加减乘除四个函数，然后写测试用例验证。一个人干的话半小时搞定，但我偏想试试用多个Agent协作完成。项目经理Agent负责拆分任务和分配，开发Agent负责写代码，测试Agent负责验证。听起来很美好，但真正动手做的时候发现坑特别多。最大的问题是怎么让这些Agent有秩序地协作，而不是各干各的互相打架。这篇就来分享我搭建这个AI开发团队的完整过程，包括架构设计、代码实现和踩过的坑。

上周有个做AI平台的朋友跟我聊到一个想法。他说平台上有各种Agent，有的擅长翻译，有的擅长数据分析，有的擅长写代码。用户调一个Agent就付一次钱，但问题是Agent之间也会互相调用。比如数据分析Agent可能调用翻译Agent来处理多语言数据，那这个钱怎么算？谁来付？付多少？这个问题涉及到Agent经济模型的核心。如果Agent之间没有一套标准化的支付协议，那Agent的商业化就只能停留在单Agent模式，多Agent协作就没法真正落地。AP2（Agent Payment Protocol）就是为解决这

我在做上一个多Agent项目的时候，用的A2A协议。整体跑起来还行，但有个问题一直困扰我。当Agent之间需要持续对话、来回交换多次消息的时候，A2A的请求-响应模式就显得很笨重。每发一条消息就要建一次HTTP连接，处理完就断，跟打电话一样，说完一句就挂了，再想说得重新拨号。后来我在调研的时候发现了ACP（Agent Communication Protocol），它的思路完全不同。ACP用的是消息队列模型，Agent之间通过异步消息通信，不需要维持长连接。

上周有个朋友跟我吐槽，说他做了个客服系统，Agent能查订单能查物流，但碰到退款问题就傻眼了，因为退款流程在另一个专门的Agent上。他问我，两个Agent之间怎么通信？工具调用和Agent间通信能不能用同一套协议？这个问题其实非常典型。很多人刚接触Agent开发的时候，会把MCP和A2A搞混，甚至觉得用一个就够了。我当时也是这么想的，后来踩了不少坑才明白，这俩解决的根本不是同一个问题。今天这篇就来聊聊MCP和A2A怎么协同工作，以及怎么用它们搭建一个真正能跑的客服Agent系统。

前几篇我们讲了A2A协议的概念、Agent Card、任务委托、ARD注册中心，理论铺垫得差不多了。今天来干货，用Python从零搭建两个真正能对话的Agent。场景是这样的: Agent A是一个研究Agent，负责收集和分析资料;Agent B是一个写作Agent，负责把研究结果写成文章。Agent A做完研究后，通过A2A协议把任务委托给Agent B，B写完文章后回调通知A。整个过程包括消息序列化、任务状态跟踪、结果回调、超时重试，全都在代码里实现。

上篇讲到A2A协议的时候，我留了一个问题: Agent怎么找到彼此?当时只是简单提了一句Agent Card放在路径下。但实际项目里，你不可能让每个Agent去记住其他所有Agent的地址。这就像微服务里的服务发现一样。你写过微服务的话应该知道Eureka或者Nacos，服务启动时注册上去，调用方从注册中心查地址。Agent也需要类似的机制，这就是ARD协议要解决的问题。

前段时间我在做一个多Agent协作的项目，场景是这样的: 一个研究Agent负责收集资料，一个写作Agent负责把资料整理成文章，一个审核Agent负责检查质量。三个Agent需要互相通信、委托任务、传递结果。一开始我天真地以为直接用HTTP接口互相调就行，写了几个REST API让它们互调。结果很快就乱了: Agent A调Agent B的时候B还没准备好，Agent B处理完了不知道怎么通知A，任务状态谁也说不清。搞了一周还是一团糟。

我在做某个金融科技项目的时候，甲方安全团队给了一份清单，要求MCP Server必须同时具备认证、授权、审计、脱敏、速率限制五项能力，缺一项就不让上线。当时我翻了翻MCP官方文档，发现协议本身只规定了传输层的基本安全建议，具体怎么实现全靠自己。折腾了两周总算搞定了，今天就把这个完整的安全MCP Server方案拆解给你看。

上周有个朋友在搞一个医疗AI项目，用MCP协议把患者数据接给大模型分析。上线第二天就被安全部门叫去喝茶了，原因是他打的日志里把患者的身份证号和手机号完整记下来了。安全部门一句话怼回来:"你知道数据安全法第几条吗?"他一脸懵地来找我，说你能不能帮我搞一套完整的审计合规方案。这事其实特别典型。我们写MCP Server的时候，往往只想着功能跑通就行，日志随便打打，参数原样记。等真上线了，合规问题一把就卡住你。今天我就把审计日志、数据脱敏、合规检查这三块揉在一起讲清楚，帮你少踩坑。

from dataclasses import dataclass, field # 数据类from typing import Dict, List, Set, Optional # 类型提示from enum import Enum # 枚举类型import json # JSON处理"""权限枚举,定义所有可用的权限点"""# 数据库相关权限DB_QUERY = "database:query" # 查询数据库DB_INSERT = "database:insert" # 插入数据。

OAuth 2.1的授权码流程分为五步。Client向Authorization Server请求授权,用户在浏览器里登录并授权,Authorization Server返回授权码,Client用授权码换Access Token,后续请求携带Token访问MCP Server。跟传统OAuth 2.0相比,2.1强制要求PKCE(Proof Key for Code Exchange),这解决了授权码被截获的风险。对桌面和移动端应用特别重要,因为它们无法安全地存储Client Secret。

前阵子有个安全研究员在Twitter上发了个帖子,说他通过一个精心构造的文件名,让AI助手把用户的SSH私钥读出来发给了第三方。我一看就坐不住了,因为我自己写的MCP Server也有类似的问题。MCP让AI能够调用工具、访问数据,这带来了巨大的便利,但同时也打开了一扇安全的大门。今天我就把自己踩过的安全坑和防御方案系统整理出来,希望能帮大家避雷。

我在做公司内部AI平台的时候遇到一个头疼的问题。前面几十篇文章我们写了十几个MCP Server,数据库的、文件系统的、云服务的、消息队列的,每个都能单独跑。但真要在生产环境用起来,总不能让用户配十几个MCP Server地址吧?那体验也太差了。我花了两周时间把这些Server整合成一套完整的工具链,用docker-compose一键部署。中间踩了不少坑,今天把整个方案分享出来。

上周有个朋友找我吐槽,说他们团队同时管着AWS、Azure和阿里云三套云环境,每次想查个实例状态都得切三个控制台,来回登录折腾得要死。他问我能不能用MCP把这些云服务的API封装一下,让AI助手直接帮你查资源、开关机器、看监控指标。我一听就觉得这主意不错,这不就是MCP Server最擅长的场景嘛。今天就手把手带大家做一个支持三大云平台的MCP Server。