1. 为什么要花96小时去做一套MCP教程先交代一下背景。我是做智能体Agent开发的去年年底接到一个内部培训任务要给团队讲清楚MCP到底是什么、怎么用、怎么调试。原本以为一两天就能搞定结果一头扎进去陆陆续续做了96小时的内容整理和实战验证才有了这套教程。现在把这96小时里最有价值的东西提炼出来分享给同样在智能体开发这条路上的朋友。先说结论MCPModel Context Protocol模型上下文协议不是一个“可选装”的插件而是2025年以来智能体开发绕不开的基础设施。它解决的是一个非常具体的问题大模型需要访问外部数据或工具时过去每个应用都要自己写一套对接逻辑格式不一、接口混乱、维护成本极高。MCP把这件事标准化了让模型可以通过一套统一的协议去读写文件、查数据库、调用API、操作浏览器。那为什么需要96小时因为我发现市面上绝大多数MCP教程都有两个问题要么只讲概念不落地要么堆了一堆代码示例但完全不解释为什么这样做。我花了大量时间把协议规范、客户端实现、服务器实现、生态工具、调试方法全部过了一遍再用真实项目把这些知识点串起来。这篇文章就是把那96小时的精华浓缩出来的版本。如果你正在做智能体开发、AI应用集成或者想搞清楚什么是MCP Server、什么是MCP Client、它们之间怎么通信那么这篇文章适合你。不需要你有深厚的协议开发背景但至少要知道什么是API、什么是JSON。接下来我会从协议设计思路开始一路讲到工具选型、代码实现、问题排查尽量把每个环节的“为什么”也说清楚。2. MCP的核心设计为什么它能成为AI应用的“USB接口”2.1 一个比喻从“每家一个充电头”到统一的Type-C要理解MCP的价值可以先想想充电接口的混乱时代。早年手机品牌各用各的充电口家里抽屉里一堆线出门还要带好几根。后来Type-C统一了市场一根线走天下。MCP做的事情本质上是一样的——它统一了大模型与外部工具/数据源之间的“接口”。在MCP出现之前智能体接外部工具的方式非常碎片化。比如你写了一个智能体要查天气、订会议室、读数据库查天气需要调用一个HTTP API自己写请求、解析响应订会议室需要调用公司内部RPC接口格式完全不同读数据库要写SQL再封装。每接一个新工具就要写一份适配逻辑而且不同智能体之间无法复用。更麻烦的是大模型对工具的调用方式五花八门——有的是通过函数调用Function Calling有的是通过提示词约束输出JSON有的干脆靠模型自己“猜”。MCP的出现改变了这个局面。它定义了三个核心概念Resources资源数据源比如文件、数据库记录、API返回结果类似REST里的“资源”概念。Tools工具可执行的操作比如发送邮件、创建工单、执行代码类似函数或RPC方法。Prompts提示词模板预定义的用户交互模式比如“做一个每日汇报”这样带有上下文逻辑的模板。这三样东西通过MCP协议暴露给客户端也就是智能体框架或应用由大模型按需调用。服务器端只需要实现一次协议所有兼容MCP的客户端都能直接用。从协议设计上看MCP是基于JSON-RPC 2.0的。JSON-RPC是一种非常轻量的远程调用协议一个请求、一个响应、ID对应没有多余的传输层复杂度。这样设计的好处是无论是本地进程通信stdio、还是网络通信SSE/HTTP都可以很容易地承载MCP语义。后面讲代码时你会看到一个MCP Server其实就是一个监听JSON-RPC消息的程序。2.2 MCP的通信模式stdio与流式传输MCP定义了两种主要传输方式stdio传输MCP Server作为客户端的一个子进程启动通过标准输入stdin和标准输出stdout与客户端交换JSON-RPC消息。这种方式最简单适合本地工具、CLI集成、桌面应用。比如你写一个Python脚本作为MCP Server启动起来后它就在等待标准输入里的消息。Streamable HTTP传输基于HTTP的流式传输适合远程服务、多人协作场景。客户端通过HTTP请求与服务器通信服务器可以返回流式响应SSE。这种方式在Web应用、云服务中更实用。在实际项目中两种方式经常会混用。比如你本地跑一个调试用的MCP Server用stdio生产环境部署到服务器后用HTTP模式。MCP协议允许客户端和服务器在初始化阶段通过capabilities协商支持的传输类型和功能。2.3 MCP与Function Calling的区别很多朋友问我已经在用Function Calling了为什么还要MCP我的理解是Function Calling是“协议前时代”的产物它在模型与代码之间做了一层函数映射但每个应用的实现各自为政MCP把“工具调用”这件事标准化了。具体来说Function Calling是模型厂商提供的API能力你定义函数列表模型选择调用哪个函数并给出参数。它解决的是“模型怎么决定调用工具”。MCP是工具层的统一标准它解决的是“工具怎么被描述、被发现、被调用”。实际项目里两者完全可以共存。MCP Server把工具暴露给客户端客户端通过Function Calling机制让大模型决策何时调用某个MCP工具。Dify、Coze、CherryStudio这类平台就是在做“把MCP和模型能力无缝整合”这件事。3. 工具选型MCP生态的关键玩家和选择建议3.1 MCP Server那些开箱即用的服务端实现我在教程里把常见的MCP Server按使用场景分成了几类这里列出最实用的一些场景推荐MCP Server说明文件系统操作Filesystem MCP Server官方参考实现可读写本地文件、目录遍历适用于文件管理智能体数据库PostgreSQL MCP Server支持SQL执行、Schema读取智能体可以直接对话式查库浏览器操作Playwright MCP Server让智能体控制浏览器自动点击、填表单、抓页面做自动化测试非常好用技术文档查询Microsoft Learn MCP Server微软官方的Learn文档MCP方便在Visual Studio里直接问文档逆向/调试IDA MCP / x64dbg MCP可直接操控IDA Pro和x64dbg调试器做二进制分析时省大量精力设计协作Figma MCP Server让智能体读取Figma设计稿组件信息、导出样式数据办公场景Slack / 邮件 / 日历 MCP Server各类协作软件的官方或社区MCP实现方便智能体收发消息、管理日程数据分析各类数据库MCP Server 代码执行MCP智能体能自动写SQL、执行脚本并返回结果选择MCP Server时我的经验是优先用官方或知名公司维护的实现其次是社区活跃度高的项目最后才考虑自己写。原因很简单MCP Server本身涉及协议细节社区踩坑多自己写容易忽略边界情况。3.2 MCP Client承载MCP的智能体框架MCP Client是“吃”MCP服务的一方。实际可用的MCP Client很多这里按使用群体分类开发者向Claude Desktop、VS Code通过插件支持MCP、Continue.dev、Cursor。这些工具直接内置或通过插件支持MCP日常写代码、查资料很方便。平台向Dify、Coze、Cherry Studio。这类低代码/无代码平台一般都有“MCP节点”或“MCP插件市场”点几下就能接一个MCP工具。定制向你自己写的Python/TypeScript智能体框架。通过官方SDK或原生协议可以让Agent具备MCP工具调用能力。3.3 低代码平台与代码框架的取舍热门词里有一条是“利用平台构建的智能体与用Python构建的智能体有什么不一样”这问题我被人问了无数次。两者的核心差异在于“控制粒度”和“开发成本”维度低代码平台Dify、Coze代码框架Python、TypeScript上手速度快拖拽节点即可完成Agent流程慢需要写逻辑、处理协议扩展灵活性受平台能力限制复杂逻辑难以实现完全可控任何需求都能定制MCP支持平台提供MCP节点配置简单但深度有限通过SDK可完全掌控协议细节调试体验平台内Debug工具方便但信息有限可打印日志、断点调试、详细追踪适用人群产品、运营、非深度开发者软件工程师、架构师、AI开发者我的建议如果你的目标是把一个智能体落地用起来优先选平台如果你要深挖MCP协议、做复杂Agent系统那就用代码。很多团队的做法是“平台先验证、代码后固化”先用Coze/Dify跑通流程再提炼沉淀为代码系统这个路径我个人非常推荐。4. 实操从零搭建一个可用的MCP应用4.1 环境准备与核心SDK实际操作之前先准备好环境。我这里用Python作为示例语言因为MCP官方Python SDK最成熟、资料最多。# 使用Python 3.10环境 pip install mcp这个mcp包就是官方SDK它同时支持你搭建MCP Server和MCP Client。安装完成之后可以先验证版本python -c import mcp; print(mcp.__version__)如果版本号正常输出了环境就准备完毕。4.2 写一个最简单的MCP Server下面我写了一个最简单的MCP Server暴露一个calculate工具功能是做四则运算。# mcp_calculator_server.py from mcp.server import Server from mcp.server.stdio import stdio_server from mcp.types import Tool, TextContent app Server(calculator) app.list_tools() async def list_tools(): return [ Tool( namecalculate, descriptionPerform basic arithmetic: add, subtract, multiply, divide, inputSchema{ type: object, properties: { expression: { type: string, description: Arithmetic expression, e.g., 35*2 } }, required: [expression] } ) ] app.call_tool() async def call_tool(name: str, arguments: dict): if name calculate: expr arguments.get(expression, ) # 安全起见用eval前需要校验表达式这里简化处理 result eval(expr) # 注意生产环境不要用eval return [TextContent(typetext, textstr(result))] raise ValueError(fUnknown tool: {name}) async def main(): async with stdio_server() as (read_stream, write_stream): await app.run(read_stream, write_stream, app.create_initialization_options()) if __name__ __main__: import asyncio asyncio.run(main())这段代码做了三件事用app.list_tools()声明这个Server提供了哪些工具每个工具都带JSON Schema格式的参数定义。用app.call_tool()实现具体的工具逻辑收到客户端调用后执行并返回结果。通过stdio_server()建立起标准输入输出通道开始监听MCP消息。注意上面示例里为了简洁用了eval这在生产环境中是极其危险的。真实项目里建议用ast.literal_eval或者逆波兰表达式解析器防止任意代码执行。启动这个Serverpython mcp_calculator_server.py启动后程序会一直等待标准输入里的JSON-RPC消息不会打印任何东西。别慌这是正常的它在等客户端“握手”。4.3 写一个调用MCP工具的客户端光有Server没有Client跑不起来下面写一个最简单的Client# mcp_calculator_client.py import asyncio from mcp import ClientSession, StdioServerParameters from mcp.client.stdio import stdio_client async def main(): server_params StdioServerParameters( commandpython, args[mcp_calculator_server.py] ) async with stdio_client(server_params) as (read_stream, write_stream): async with ClientSession(read_stream, write_stream) as session: # 1. 初始化连接协商能力 init_result await session.initialize() print(Initialized:, init_result) # 2. 获取工具列表 tools await session.list_tools() print(Available tools:) for tool in tools.tools: print(f- {tool.name}: {tool.description}) # 3. 调用工具 result await session.call_tool( calculate, {expression: (35)*2} ) print(Result:, result.content[0].text) asyncio.run(main())运行结果会显示Initialized: ... Available tools: - calculate: Perform basic arithmetic: add, subtract, multiply, divide Result: 16这个小例子已经走完了MCP的核心流程客户端启动Server子进程 → 通过stdio建立通道 → 初始化握手机制 → 列出工具清单 → 调用工具并获取结果。这个过程中有几个容易忽略的地方initialize()不只是“打个招呼”它会在客户端和服务器之间交换能力信息比如支持哪些传输类型、协议版本是多少。如果版本不匹配握手会失败。list_tools()返回的是工具Schema客户端可以把这些Schema转换为大模型Function Calling的输入格式让模型“看到”有哪些工具可用。call_tool()里的参数必须和工具定义的JSON Schema匹配如果传了缺参数或类型错误的参数Server端会返回错误。4.4 让MCP Server接入大模型智能体上面的例子还是一个“命令自动补全”级别的玩具要让MCP真正发挥价值得把MCP工具接到大模型上。下面这段代码演示了怎么让一个大模型智能体通过MCP获得实时工具调用能力# agent_with_mcp.py import asyncio from openai import AsyncOpenAI from mcp import ClientSession, StdioServerParameters from mcp.client.stdio import stdio_client client AsyncOpenAI(api_keyyour-api-key, base_urlyour-base-url) async def run_agent_with_tool(user_query: str): # 先连接MCP Server拿到工具列表 server_params StdioServerParameters( commandpython, args[mcp_calculator_server.py] ) async with stdio_client(server_params) as (read_stream, write_stream): async with ClientSession(read_stream, write_stream) as session: await session.initialize() tools_response await session.list_tools() # 将MCP工具转换为OpenAI Function格式 functions [] for tool in tools_response.tools: functions.append({ type: function, function: { name: tool.name, description: tool.description, parameters: tool.inputSchema } }) # 第一次请求让模型决定是否调用工具 response await client.chat.completions.create( modelgpt-4o-mini, messages[{role: user, content: user_query}], toolsfunctions, tool_choiceauto ) message response.choices[0].message # 若模型决定调用工具 if message.tool_calls: for tool_call in message.tool_calls: fn_name tool_call.function.name fn_args json.loads(tool_call.function.arguments) # 调用MCP工具 mcp_result await session.call_tool(fn_name, fn_args) tool_result mcp_result.content[0].text # 把工具返回结果给模型让它组织最终回答 messages [ {role: user, content: user_query}, message, { role: tool, tool_call_id: tool_call.id, content: tool_result } ] final_response await client.chat.completions.create( modelgpt-4o-mini, messagesmessages, toolsfunctions ) print(最终回答:, final_response.choices[0].message.content) asyncio.run(run_agent_with_tool((35)*2等于多少))这个流程就是目前绝大多数“智能体调用工具”的真实链路大模型负责理解用户意图、决定要不要调工具、选哪个工具、传什么参数MCP负责把工具调用标准化让模型和工具解耦。4.5 用Dify平台快速接入MCP低代码路径用代码的方式适合开发者但如果你用的是Dify这类低代码平台接入MCP会更快。这里给出大概步骤在Dify的“工具”页面找“MCP”节点或者通过“自定义工具”导入MCP Server的URL。配置连接参数如果是本地stdio模式需要在运行环境中启动Server然后填写命令如果是HTTP模式填写Server的HTTP端点URL。配置完成后Dify会自动拉取工具列表你可以看到每个工具的名称、描述、参数Schema。在Agent应用编排页面把MCP工具拖入“工具列表”然后在提示词里说明“你可以使用这些工具”。测试时对话“帮我计算(35)*2”Dify会调用MCP Server并返回结果。低代码平台的好处是省去写代码和调试的负担坏处是出了问题不好排查——平台封装的错误信息往往不那么直接。我的习惯是先在本地用Python脚本验证MCP Server没问题再接平台。5. 实战案例多个真实项目中的MCP落地5.1 调试工具链IDA MCP x64dbg MCP热门词里频繁出现“IDA MCP”“x64dbg MCP”这引起了很多人的兴趣。简单说一下这个场景是干什么的。做逆向工程时分析人员的典型工作流程是用IDA Pro静态分析二进制、用x64dbg动态调试、观察寄存器与内存、不断切换工具。这个过程有大量重复性的“看这里、看那里”操作。MCP改造后智能体可以直接操控这两个调试器IDA MCP允许智能体向IDA发送“列出当前函数”“反汇编地址0x401000”“查找交叉引用”等指令。x64dbg MCP允许智能体设置断点、单步执行、读取寄存器值。于是分析人员可以用自然语言给智能体下达指令比如“在这个函数的开头设置断点运行到断点时告诉我eax寄存器的值”。智能体会把这些指令拆解为对IDA或x64dbg的MCP调用自动完成一系列操作。这个场景非常适合“辅助人类专家做重复性分析”但我要提醒一点工具调用本身不能替代人的判断。逆向工程的核心是“猜出程序的意图”目前智能体还做不到这一点更多是用来做“体力活”外包。5.2 浏览器自动化Playwright MCP另一个我经常用的场景是浏览器操作。Playwright MCP Server跑起来后智能体能控制浏览器执行点击、输入、页面抓取等动作。实际测试中下面这个流程跑得很稳定启动Playwright MCP Server。接入MCP Client比如Claude Desktop或自己的Python Client。让智能体“打开某个网址把页面里所有链接抓出来并保存成Markdown文件”。这背后Playwright MCP Server做了很多事它负责和浏览器实例通信把“打开网址”“点击元素”“滚动页面”等动作封装成MCP Tool暴露给Client端。Client端再把这些工具交给大模型决策实现“自然语言驱动浏览器”。我做自动化测试时特别喜欢这个组合让智能体按测试用例步骤操作页面每步截图留存发现异常时直接把报错信息交给模型分析原因。和传统自动化脚本相比好处是“改页面结构不太容易挂”因为智能体会理解页面元素含义而不是死板地根据绝对选择器定位。5.3 数据分析与报表生成还有一个值得提的场景是“自然语言查数据库”。传统BI工具要求用户懂SQLMCP接入后员工可以直接问“上个月华东区的销售额是多少”智能体自动查询数据库并返回结果。我之前的做法是部署PostgreSQL MCP Server配置好数据库连接信息。在Server端定义好Schema读取规则确保只暴露业务允许的数据表。接入智能体平台后员工提问智能体自动生成SQL并执行。这里有个安全细节MCP Server的权限范围一定要控制好。数据库MCP工具只需要SELECT权限千万不能给DELETE或DROP权限。否则智能体在生成SQL时万一出了偏差可能造成数据丢失。6. 常见问题与排查技巧实录6.1 常见报错与解决方案速查表使用MCP过程中我踩了不少坑这里整理成速查表问题典型报错原因解决方案初始化失败Unsupported protocol version客户端与服务器MCP版本不一致升级或锁定协议版本客户端与SDK版本保持一致stdio模式无响应Server启动后无任何输出Server端发生异常但未捕获在Server端添加日志输出到stderrstdio模式下stdout留作协议通信日志走stderr工具列表为空正常握手但list_tools返回空Server端list_tools装饰器未生效或返回了空列表检查装饰器注册的代码是否在启动逻辑之前确认Server实例是同一个对象调用工具报错Tool execution failed工具实现中抛出了异常在call_tool里捕获异常并返回错误信息给客户端而非直接抛出中文乱码输出结果乱码编码不统一在Server和Client两端都声明UTF-8Windows下建议在启动命令前加chcp 65001并发调用互斥崩溃多请求同时调用Server没有处理并发安全stdio模式下同一时间只能处理一个请求多个Client共享Server需改用HTTP模式或加任务队列找不到SDKModuleNotFoundError: No module named mcp没有安装或环境不对确认用对的Python环境安装虚拟环境混乱时建议重建venv6.2 调试MCP的独门技巧日志是王道MCP协议调试和普通HTTP调试最大的不同在于stdio模式下stdout是协议通道你不能像普通代码那样用print输出调试信息。很多新手在这里卡住程序“什么都没打印”就以为是自己代码没跑起来。我的做法是把日志输出到stderrimport sys import logging logging.basicConfig( streamsys.stderr, levellogging.DEBUG, format%(asctime)s %(levelname)s %(message)s ) logger logging.getLogger(mcp-server) logger.debug(Server started, waiting for messages...)这样日志会打印到终端错误流而不会干扰stdout的协议通信。如果是在IDE里跑也能正常看到控制台日志。提到IDE强烈推荐在调试MCP时使用VS Code的JavaScript调试终端或Python调试器。你可以在call_tool函数里打断点逐步查看请求参数。这个过程能帮你快速确认到底是协议层的问题还是业务逻辑的问题。6.3 配置代理或跨平台问题的那些事跨平台使用时我遇到过几个典型的坑Windows下stdio模式乱码Windows默认编码可能是GBK协议里传中文容易乱。解决方法是启动命令前设置编码python -X utf8 mcp_calculator_server.pyPATH环境不一致用commandpython启动子进程时如果Client端的环境变量和Server端不一致可能找到错误版本的Python。稳妥办法是用绝对路径或者把启动命令封装成一个单独脚本比如.sh或.bat。macOS/Linux下权限问题如果MCP Server要访问某些敏感目录如/etc或系统文件需要确保进程有足够权限。这类问题排查时先看对应文件读写的权限位。6.4 关于“MCP Tool是否能流式输出”的疑问热门词里有一条“使用MCP工具流式输出内容到文件”这里单独解释一下。MCP本身确实支持流式响应但大部分工具调用的场景是“一个请求、一个结果”的模式。要让MCP工具实现真正的流式输出比如生成一段长文本并实时返回需要做几件事MCP Server端支持SSE或类似机制把结果分块发送。客户端解析流式响应并逐段展示或写入文件。对于大文件写入场景更常见的做法是让MCP Server直接操作目标文件系统而不是通过流把内容从Server传到Client再写文件。Cherry Studio这类工具提到的“MCP工具流式输出内容到文件”我理解更多是“让智能体调用MCP工具去写文件同时实时显示进度”。做这样的功能时可以把写文件的逻辑放在MCP Server端通过进度事件如notifications/progress向客户端推送进度。MCP协议自带进度通知机制不需要额外定制。7. 制作这套教程时踩过的坑和总结最后聊一聊制作这套教程本身的经验这部分对想做技术分享的朋友可能更有用。第一MCP教程最大的难点不是代码而是“生态变化太快”。MCP协议还在快速迭代SDK的API接口会变第三方Server的质量参差不齐。做教程时我把所有代码都落在“官方SDK当前稳定版”上同时标注了“版本敏感”的API让大家以后看到新版本变更时知道要从哪查。第二MCP的“入门容易精通难”。写一个hello world级别的Server只需十分钟但要做好生产级应用需要掌握协议细节、错误处理、安全边界、并发模型。做教程时我把大量篇幅花在了“谢绝踩坑”上就是因为你真正上手时最耗时间的是排查那些看起来莫名其妙的问题。第三理解了MCP背后“标准化”的哲学思想后你对智能体开发的理解会上一个层次。智能体不再是一堆API调用拼出来的demo而是一个“能连接万物”的执行框架。你考虑的不再是“这个工具怎么接”而是“这个工具该不该暴露、暴露后怎么被描述、怎么保证用对”。如果你正在配置自己的MCP环境我的建议是先从官方示例跑通再换成自己的工具最后再折腾远程部署。不要一上来就去写复杂Server那只会增加排查难度。跑通一次完整的“Server—Client—调用—返回”链路之后你对MCP的掌控感会完全不一样。最后再分享一个小技巧如果你在某个平台看到“支持MCP插件”但配置界面比较简陋、还看不到工具列表很可能是它的MCP客户端实现不完整。这时候自己写个Python客户端去连接同一个Server看看能否正常发现工具能快速判断问题在哪一边。这个“用第三方客户端做交叉验证”的方法我在接各种平台时屡试不爽。 
长河君 · 2026/10/8 2:39:44 · 阅读 1.2k MCP协议实战：从JSON-RPC到智能体工具调用标准化
1. 为什么要花96小时去做一套MCP教程先交代一下背景。我是做智能体Agent开发的去年年底接到一个内部培训任务要给团队讲清楚MCP到底是什么、怎么用、怎么调试。原本以为一两天就能搞定结果一头扎进去陆陆续续做了96小时的内容整理和实战验证才有了这套教程。现在把这96小时里最有价值的东西提炼出来分享给同样在智能体开发这条路上的朋友。先说结论MCPModel Context Protocol模型上下文协议不是一个“可选装”的插件而是2025年以来智能体开发绕不开的基础设施。它解决的是一个非常具体的问题大模型需要访问外部数据或工具时过去每个应用都要自己写一套对接逻辑格式不一、接口混乱、维护成本极高。MCP把这件事标准化了让模型可以通过一套统一的协议去读写文件、查数据库、调用API、操作浏览器。那为什么需要96小时因为我发现市面上绝大多数MCP教程都有两个问题要么只讲概念不落地要么堆了一堆代码示例但完全不解释为什么这样做。我花了大量时间把协议规范、客户端实现、服务器实现、生态工具、调试方法全部过了一遍再用真实项目把这些知识点串起来。这篇文章就是把那96小时的精华浓缩出来的版本。如果你正在做智能体开发、AI应用集成或者想搞清楚什么是MCP Server、什么是MCP Client、它们之间怎么通信那么这篇文章适合你。不需要你有深厚的协议开发背景但至少要知道什么是API、什么是JSON。接下来我会从协议设计思路开始一路讲到工具选型、代码实现、问题排查尽量把每个环节的“为什么”也说清楚。2. MCP的核心设计为什么它能成为AI应用的“USB接口”2.1 一个比喻从“每家一个充电头”到统一的Type-C要理解MCP的价值可以先想想充电接口的混乱时代。早年手机品牌各用各的充电口家里抽屉里一堆线出门还要带好几根。后来Type-C统一了市场一根线走天下。MCP做的事情本质上是一样的——它统一了大模型与外部工具/数据源之间的“接口”。在MCP出现之前智能体接外部工具的方式非常碎片化。比如你写了一个智能体要查天气、订会议室、读数据库查天气需要调用一个HTTP API自己写请求、解析响应订会议室需要调用公司内部RPC接口格式完全不同读数据库要写SQL再封装。每接一个新工具就要写一份适配逻辑而且不同智能体之间无法复用。更麻烦的是大模型对工具的调用方式五花八门——有的是通过函数调用Function Calling有的是通过提示词约束输出JSON有的干脆靠模型自己“猜”。MCP的出现改变了这个局面。它定义了三个核心概念Resources资源数据源比如文件、数据库记录、API返回结果类似REST里的“资源”概念。Tools工具可执行的操作比如发送邮件、创建工单、执行代码类似函数或RPC方法。Prompts提示词模板预定义的用户交互模式比如“做一个每日汇报”这样带有上下文逻辑的模板。这三样东西通过MCP协议暴露给客户端也就是智能体框架或应用由大模型按需调用。服务器端只需要实现一次协议所有兼容MCP的客户端都能直接用。从协议设计上看MCP是基于JSON-RPC 2.0的。JSON-RPC是一种非常轻量的远程调用协议一个请求、一个响应、ID对应没有多余的传输层复杂度。这样设计的好处是无论是本地进程通信stdio、还是网络通信SSE/HTTP都可以很容易地承载MCP语义。后面讲代码时你会看到一个MCP Server其实就是一个监听JSON-RPC消息的程序。2.2 MCP的通信模式stdio与流式传输MCP定义了两种主要传输方式stdio传输MCP Server作为客户端的一个子进程启动通过标准输入stdin和标准输出stdout与客户端交换JSON-RPC消息。这种方式最简单适合本地工具、CLI集成、桌面应用。比如你写一个Python脚本作为MCP Server启动起来后它就在等待标准输入里的消息。Streamable HTTP传输基于HTTP的流式传输适合远程服务、多人协作场景。客户端通过HTTP请求与服务器通信服务器可以返回流式响应SSE。这种方式在Web应用、云服务中更实用。在实际项目中两种方式经常会混用。比如你本地跑一个调试用的MCP Server用stdio生产环境部署到服务器后用HTTP模式。MCP协议允许客户端和服务器在初始化阶段通过capabilities协商支持的传输类型和功能。2.3 MCP与Function Calling的区别很多朋友问我已经在用Function Calling了为什么还要MCP我的理解是Function Calling是“协议前时代”的产物它在模型与代码之间做了一层函数映射但每个应用的实现各自为政MCP把“工具调用”这件事标准化了。具体来说Function Calling是模型厂商提供的API能力你定义函数列表模型选择调用哪个函数并给出参数。它解决的是“模型怎么决定调用工具”。MCP是工具层的统一标准它解决的是“工具怎么被描述、被发现、被调用”。实际项目里两者完全可以共存。MCP Server把工具暴露给客户端客户端通过Function Calling机制让大模型决策何时调用某个MCP工具。Dify、Coze、CherryStudio这类平台就是在做“把MCP和模型能力无缝整合”这件事。3. 工具选型MCP生态的关键玩家和选择建议3.1 MCP Server那些开箱即用的服务端实现我在教程里把常见的MCP Server按使用场景分成了几类这里列出最实用的一些场景推荐MCP Server说明文件系统操作Filesystem MCP Server官方参考实现可读写本地文件、目录遍历适用于文件管理智能体数据库PostgreSQL MCP Server支持SQL执行、Schema读取智能体可以直接对话式查库浏览器操作Playwright MCP Server让智能体控制浏览器自动点击、填表单、抓页面做自动化测试非常好用技术文档查询Microsoft Learn MCP Server微软官方的Learn文档MCP方便在Visual Studio里直接问文档逆向/调试IDA MCP / x64dbg MCP可直接操控IDA Pro和x64dbg调试器做二进制分析时省大量精力设计协作Figma MCP Server让智能体读取Figma设计稿组件信息、导出样式数据办公场景Slack / 邮件 / 日历 MCP Server各类协作软件的官方或社区MCP实现方便智能体收发消息、管理日程数据分析各类数据库MCP Server 代码执行MCP智能体能自动写SQL、执行脚本并返回结果选择MCP Server时我的经验是优先用官方或知名公司维护的实现其次是社区活跃度高的项目最后才考虑自己写。原因很简单MCP Server本身涉及协议细节社区踩坑多自己写容易忽略边界情况。3.2 MCP Client承载MCP的智能体框架MCP Client是“吃”MCP服务的一方。实际可用的MCP Client很多这里按使用群体分类开发者向Claude Desktop、VS Code通过插件支持MCP、Continue.dev、Cursor。这些工具直接内置或通过插件支持MCP日常写代码、查资料很方便。平台向Dify、Coze、Cherry Studio。这类低代码/无代码平台一般都有“MCP节点”或“MCP插件市场”点几下就能接一个MCP工具。定制向你自己写的Python/TypeScript智能体框架。通过官方SDK或原生协议可以让Agent具备MCP工具调用能力。3.3 低代码平台与代码框架的取舍热门词里有一条是“利用平台构建的智能体与用Python构建的智能体有什么不一样”这问题我被人问了无数次。两者的核心差异在于“控制粒度”和“开发成本”维度低代码平台Dify、Coze代码框架Python、TypeScript上手速度快拖拽节点即可完成Agent流程慢需要写逻辑、处理协议扩展灵活性受平台能力限制复杂逻辑难以实现完全可控任何需求都能定制MCP支持平台提供MCP节点配置简单但深度有限通过SDK可完全掌控协议细节调试体验平台内Debug工具方便但信息有限可打印日志、断点调试、详细追踪适用人群产品、运营、非深度开发者软件工程师、架构师、AI开发者我的建议如果你的目标是把一个智能体落地用起来优先选平台如果你要深挖MCP协议、做复杂Agent系统那就用代码。很多团队的做法是“平台先验证、代码后固化”先用Coze/Dify跑通流程再提炼沉淀为代码系统这个路径我个人非常推荐。4. 实操从零搭建一个可用的MCP应用4.1 环境准备与核心SDK实际操作之前先准备好环境。我这里用Python作为示例语言因为MCP官方Python SDK最成熟、资料最多。# 使用Python 3.10环境 pip install mcp这个mcp包就是官方SDK它同时支持你搭建MCP Server和MCP Client。安装完成之后可以先验证版本python -c import mcp; print(mcp.__version__)如果版本号正常输出了环境就准备完毕。4.2 写一个最简单的MCP Server下面我写了一个最简单的MCP Server暴露一个calculate工具功能是做四则运算。# mcp_calculator_server.py from mcp.server import Server from mcp.server.stdio import stdio_server from mcp.types import Tool, TextContent app Server(calculator) app.list_tools() async def list_tools(): return [ Tool( namecalculate, descriptionPerform basic arithmetic: add, subtract, multiply, divide, inputSchema{ type: object, properties: { expression: { type: string, description: Arithmetic expression, e.g., 35*2 } }, required: [expression] } ) ] app.call_tool() async def call_tool(name: str, arguments: dict): if name calculate: expr arguments.get(expression, ) # 安全起见用eval前需要校验表达式这里简化处理 result eval(expr) # 注意生产环境不要用eval return [TextContent(typetext, textstr(result))] raise ValueError(fUnknown tool: {name}) async def main(): async with stdio_server() as (read_stream, write_stream): await app.run(read_stream, write_stream, app.create_initialization_options()) if __name__ __main__: import asyncio asyncio.run(main())这段代码做了三件事用app.list_tools()声明这个Server提供了哪些工具每个工具都带JSON Schema格式的参数定义。用app.call_tool()实现具体的工具逻辑收到客户端调用后执行并返回结果。通过stdio_server()建立起标准输入输出通道开始监听MCP消息。注意上面示例里为了简洁用了eval这在生产环境中是极其危险的。真实项目里建议用ast.literal_eval或者逆波兰表达式解析器防止任意代码执行。启动这个Serverpython mcp_calculator_server.py启动后程序会一直等待标准输入里的JSON-RPC消息不会打印任何东西。别慌这是正常的它在等客户端“握手”。4.3 写一个调用MCP工具的客户端光有Server没有Client跑不起来下面写一个最简单的Client# mcp_calculator_client.py import asyncio from mcp import ClientSession, StdioServerParameters from mcp.client.stdio import stdio_client async def main(): server_params StdioServerParameters( commandpython, args[mcp_calculator_server.py] ) async with stdio_client(server_params) as (read_stream, write_stream): async with ClientSession(read_stream, write_stream) as session: # 1. 初始化连接协商能力 init_result await session.initialize() print(Initialized:, init_result) # 2. 获取工具列表 tools await session.list_tools() print(Available tools:) for tool in tools.tools: print(f- {tool.name}: {tool.description}) # 3. 调用工具 result await session.call_tool( calculate, {expression: (35)*2} ) print(Result:, result.content[0].text) asyncio.run(main())运行结果会显示Initialized: ... Available tools: - calculate: Perform basic arithmetic: add, subtract, multiply, divide Result: 16这个小例子已经走完了MCP的核心流程客户端启动Server子进程 → 通过stdio建立通道 → 初始化握手机制 → 列出工具清单 → 调用工具并获取结果。这个过程中有几个容易忽略的地方initialize()不只是“打个招呼”它会在客户端和服务器之间交换能力信息比如支持哪些传输类型、协议版本是多少。如果版本不匹配握手会失败。list_tools()返回的是工具Schema客户端可以把这些Schema转换为大模型Function Calling的输入格式让模型“看到”有哪些工具可用。call_tool()里的参数必须和工具定义的JSON Schema匹配如果传了缺参数或类型错误的参数Server端会返回错误。4.4 让MCP Server接入大模型智能体上面的例子还是一个“命令自动补全”级别的玩具要让MCP真正发挥价值得把MCP工具接到大模型上。下面这段代码演示了怎么让一个大模型智能体通过MCP获得实时工具调用能力# agent_with_mcp.py import asyncio from openai import AsyncOpenAI from mcp import ClientSession, StdioServerParameters from mcp.client.stdio import stdio_client client AsyncOpenAI(api_keyyour-api-key, base_urlyour-base-url) async def run_agent_with_tool(user_query: str): # 先连接MCP Server拿到工具列表 server_params StdioServerParameters( commandpython, args[mcp_calculator_server.py] ) async with stdio_client(server_params) as (read_stream, write_stream): async with ClientSession(read_stream, write_stream) as session: await session.initialize() tools_response await session.list_tools() # 将MCP工具转换为OpenAI Function格式 functions [] for tool in tools_response.tools: functions.append({ type: function, function: { name: tool.name, description: tool.description, parameters: tool.inputSchema } }) # 第一次请求让模型决定是否调用工具 response await client.chat.completions.create( modelgpt-4o-mini, messages[{role: user, content: user_query}], toolsfunctions, tool_choiceauto ) message response.choices[0].message # 若模型决定调用工具 if message.tool_calls: for tool_call in message.tool_calls: fn_name tool_call.function.name fn_args json.loads(tool_call.function.arguments) # 调用MCP工具 mcp_result await session.call_tool(fn_name, fn_args) tool_result mcp_result.content[0].text # 把工具返回结果给模型让它组织最终回答 messages [ {role: user, content: user_query}, message, { role: tool, tool_call_id: tool_call.id, content: tool_result } ] final_response await client.chat.completions.create( modelgpt-4o-mini, messagesmessages, toolsfunctions ) print(最终回答:, final_response.choices[0].message.content) asyncio.run(run_agent_with_tool((35)*2等于多少))这个流程就是目前绝大多数“智能体调用工具”的真实链路大模型负责理解用户意图、决定要不要调工具、选哪个工具、传什么参数MCP负责把工具调用标准化让模型和工具解耦。4.5 用Dify平台快速接入MCP低代码路径用代码的方式适合开发者但如果你用的是Dify这类低代码平台接入MCP会更快。这里给出大概步骤在Dify的“工具”页面找“MCP”节点或者通过“自定义工具”导入MCP Server的URL。配置连接参数如果是本地stdio模式需要在运行环境中启动Server然后填写命令如果是HTTP模式填写Server的HTTP端点URL。配置完成后Dify会自动拉取工具列表你可以看到每个工具的名称、描述、参数Schema。在Agent应用编排页面把MCP工具拖入“工具列表”然后在提示词里说明“你可以使用这些工具”。测试时对话“帮我计算(35)*2”Dify会调用MCP Server并返回结果。低代码平台的好处是省去写代码和调试的负担坏处是出了问题不好排查——平台封装的错误信息往往不那么直接。我的习惯是先在本地用Python脚本验证MCP Server没问题再接平台。5. 实战案例多个真实项目中的MCP落地5.1 调试工具链IDA MCP x64dbg MCP热门词里频繁出现“IDA MCP”“x64dbg MCP”这引起了很多人的兴趣。简单说一下这个场景是干什么的。做逆向工程时分析人员的典型工作流程是用IDA Pro静态分析二进制、用x64dbg动态调试、观察寄存器与内存、不断切换工具。这个过程有大量重复性的“看这里、看那里”操作。MCP改造后智能体可以直接操控这两个调试器IDA MCP允许智能体向IDA发送“列出当前函数”“反汇编地址0x401000”“查找交叉引用”等指令。x64dbg MCP允许智能体设置断点、单步执行、读取寄存器值。于是分析人员可以用自然语言给智能体下达指令比如“在这个函数的开头设置断点运行到断点时告诉我eax寄存器的值”。智能体会把这些指令拆解为对IDA或x64dbg的MCP调用自动完成一系列操作。这个场景非常适合“辅助人类专家做重复性分析”但我要提醒一点工具调用本身不能替代人的判断。逆向工程的核心是“猜出程序的意图”目前智能体还做不到这一点更多是用来做“体力活”外包。5.2 浏览器自动化Playwright MCP另一个我经常用的场景是浏览器操作。Playwright MCP Server跑起来后智能体能控制浏览器执行点击、输入、页面抓取等动作。实际测试中下面这个流程跑得很稳定启动Playwright MCP Server。接入MCP Client比如Claude Desktop或自己的Python Client。让智能体“打开某个网址把页面里所有链接抓出来并保存成Markdown文件”。这背后Playwright MCP Server做了很多事它负责和浏览器实例通信把“打开网址”“点击元素”“滚动页面”等动作封装成MCP Tool暴露给Client端。Client端再把这些工具交给大模型决策实现“自然语言驱动浏览器”。我做自动化测试时特别喜欢这个组合让智能体按测试用例步骤操作页面每步截图留存发现异常时直接把报错信息交给模型分析原因。和传统自动化脚本相比好处是“改页面结构不太容易挂”因为智能体会理解页面元素含义而不是死板地根据绝对选择器定位。5.3 数据分析与报表生成还有一个值得提的场景是“自然语言查数据库”。传统BI工具要求用户懂SQLMCP接入后员工可以直接问“上个月华东区的销售额是多少”智能体自动查询数据库并返回结果。我之前的做法是部署PostgreSQL MCP Server配置好数据库连接信息。在Server端定义好Schema读取规则确保只暴露业务允许的数据表。接入智能体平台后员工提问智能体自动生成SQL并执行。这里有个安全细节MCP Server的权限范围一定要控制好。数据库MCP工具只需要SELECT权限千万不能给DELETE或DROP权限。否则智能体在生成SQL时万一出了偏差可能造成数据丢失。6. 常见问题与排查技巧实录6.1 常见报错与解决方案速查表使用MCP过程中我踩了不少坑这里整理成速查表问题典型报错原因解决方案初始化失败Unsupported protocol version客户端与服务器MCP版本不一致升级或锁定协议版本客户端与SDK版本保持一致stdio模式无响应Server启动后无任何输出Server端发生异常但未捕获在Server端添加日志输出到stderrstdio模式下stdout留作协议通信日志走stderr工具列表为空正常握手但list_tools返回空Server端list_tools装饰器未生效或返回了空列表检查装饰器注册的代码是否在启动逻辑之前确认Server实例是同一个对象调用工具报错Tool execution failed工具实现中抛出了异常在call_tool里捕获异常并返回错误信息给客户端而非直接抛出中文乱码输出结果乱码编码不统一在Server和Client两端都声明UTF-8Windows下建议在启动命令前加chcp 65001并发调用互斥崩溃多请求同时调用Server没有处理并发安全stdio模式下同一时间只能处理一个请求多个Client共享Server需改用HTTP模式或加任务队列找不到SDKModuleNotFoundError: No module named mcp没有安装或环境不对确认用对的Python环境安装虚拟环境混乱时建议重建venv6.2 调试MCP的独门技巧日志是王道MCP协议调试和普通HTTP调试最大的不同在于stdio模式下stdout是协议通道你不能像普通代码那样用print输出调试信息。很多新手在这里卡住程序“什么都没打印”就以为是自己代码没跑起来。我的做法是把日志输出到stderrimport sys import logging logging.basicConfig( streamsys.stderr, levellogging.DEBUG, format%(asctime)s %(levelname)s %(message)s ) logger logging.getLogger(mcp-server) logger.debug(Server started, waiting for messages...)这样日志会打印到终端错误流而不会干扰stdout的协议通信。如果是在IDE里跑也能正常看到控制台日志。提到IDE强烈推荐在调试MCP时使用VS Code的JavaScript调试终端或Python调试器。你可以在call_tool函数里打断点逐步查看请求参数。这个过程能帮你快速确认到底是协议层的问题还是业务逻辑的问题。6.3 配置代理或跨平台问题的那些事跨平台使用时我遇到过几个典型的坑Windows下stdio模式乱码Windows默认编码可能是GBK协议里传中文容易乱。解决方法是启动命令前设置编码python -X utf8 mcp_calculator_server.pyPATH环境不一致用commandpython启动子进程时如果Client端的环境变量和Server端不一致可能找到错误版本的Python。稳妥办法是用绝对路径或者把启动命令封装成一个单独脚本比如.sh或.bat。macOS/Linux下权限问题如果MCP Server要访问某些敏感目录如/etc或系统文件需要确保进程有足够权限。这类问题排查时先看对应文件读写的权限位。6.4 关于“MCP Tool是否能流式输出”的疑问热门词里有一条“使用MCP工具流式输出内容到文件”这里单独解释一下。MCP本身确实支持流式响应但大部分工具调用的场景是“一个请求、一个结果”的模式。要让MCP工具实现真正的流式输出比如生成一段长文本并实时返回需要做几件事MCP Server端支持SSE或类似机制把结果分块发送。客户端解析流式响应并逐段展示或写入文件。对于大文件写入场景更常见的做法是让MCP Server直接操作目标文件系统而不是通过流把内容从Server传到Client再写文件。Cherry Studio这类工具提到的“MCP工具流式输出内容到文件”我理解更多是“让智能体调用MCP工具去写文件同时实时显示进度”。做这样的功能时可以把写文件的逻辑放在MCP Server端通过进度事件如notifications/progress向客户端推送进度。MCP协议自带进度通知机制不需要额外定制。7. 制作这套教程时踩过的坑和总结最后聊一聊制作这套教程本身的经验这部分对想做技术分享的朋友可能更有用。第一MCP教程最大的难点不是代码而是“生态变化太快”。MCP协议还在快速迭代SDK的API接口会变第三方Server的质量参差不齐。做教程时我把所有代码都落在“官方SDK当前稳定版”上同时标注了“版本敏感”的API让大家以后看到新版本变更时知道要从哪查。第二MCP的“入门容易精通难”。写一个hello world级别的Server只需十分钟但要做好生产级应用需要掌握协议细节、错误处理、安全边界、并发模型。做教程时我把大量篇幅花在了“谢绝踩坑”上就是因为你真正上手时最耗时间的是排查那些看起来莫名其妙的问题。第三理解了MCP背后“标准化”的哲学思想后你对智能体开发的理解会上一个层次。智能体不再是一堆API调用拼出来的demo而是一个“能连接万物”的执行框架。你考虑的不再是“这个工具怎么接”而是“这个工具该不该暴露、暴露后怎么被描述、怎么保证用对”。如果你正在配置自己的MCP环境我的建议是先从官方示例跑通再换成自己的工具最后再折腾远程部署。不要一上来就去写复杂Server那只会增加排查难度。跑通一次完整的“Server—Client—调用—返回”链路之后你对MCP的掌控感会完全不一样。最后再分享一个小技巧如果你在某个平台看到“支持MCP插件”但配置界面比较简陋、还看不到工具列表很可能是它的MCP客户端实现不完整。这时候自己写个Python客户端去连接同一个Server看看能否正常发现工具能快速判断问题在哪一边。这个“用第三方客户端做交叉验证”的方法我在接各种平台时屡试不爽。