这期是“直接发”系列的第002篇。上次写智能体应用时我提到过工具调用Function Calling的碎片化问题这次干脆单独拿出来聊聊MCP协议。如果你在2025年前后开始搞AI应用开发大概率已经听过这个词——MCPModel Context Protocol模型上下文协议。简单说它是一套把AI模型和外部工具、数据源连接起来的标准化协议目前已经成为业内公认的“工具调用通用接口”。这篇不是协议文档的翻译也不是照抄官方示例。我会从实际做项目踩坑的角度讲清楚MCP协议解决了什么问题、它是怎么运转的再带着你从零写一个能跑的MCP Server最后把它接到Web项目里和Dify这类智能体平台上。内容偏实战建议你打开电脑跟着敲看完能直接抄作业那种。1. MCP协议到底是什么一次讲清三个核心问题1.1 AI应用的工具调用困境在MCP出现之前AI接入外部工具这件事基本是各做各的。OpenAI有自己的Function CallingAnthropic有Tool UseLangChain有自己的一套Tool定义方式每个框架的工具描述、参数格式、调用返回规则都不一样。你在一套体系里写好的工具换到另一个平台基本作废要么重新适配要么写一堆胶水代码。更麻烦的是数据源的连接方式完全没有统一标准。一个AI应用要读数据库、查业务系统、获取内网API数据每个都得单独写适配层。数据库有连接池、宿主机有SSH认证、内部系统有各式各样的鉴权逻辑这些东西和模型本身又互相耦合。今天换个模型适配层全得跟着动项目长期维护下去非常痛苦。MCP的出现就是为了解决这个问题。它定义了一套“模型-协议-工具/数据源”的标准通信方式就像给AI应用装了一个统一的USB-C接口。工具接入方只需要实现MCP Server模型应用只要实现MCP Client双方按协议说话不用关心对方内部是怎么实现的。1.2 MCP的核心抽象Server、Client、Tool、ResourceMCP的模型结构其实可以类比成日常用的客户端-服务器架构只不过这里的“服务器”指的不是物理机而是暴露工具能力的进程。MCP Host用户日常接触的AI应用本体比如Claude Desktop、IDE插件、Dify这类智能体平台。MCP ClientHost内与Server建立连接、发起请求的组件负责协议通信。MCP Server独立的工具服务进程把某个领域的能力暴露出来。一个Server可以注册多个Tool、Resource和Prompt。MCP Tool模型可以按需调用的功能单元是动态的、有副作用的比如“查天气”“下单”“改数据库”。MCP Resource模型可以读取的数据资源是静态的、只读的比如数据库里的表、本地文件内容。MCP Prompt预置的提示词模板跨项目复用时很省事。关键的区分点是Tool和Resource。我见过不少人在初期分不清这两者其实有个粗暴的判断标准如果这个操作会改变状态写数据库、调用外部API、执行命令就做成Tool如果只是把数据拿出来给模型看读文件、查配置表做成Resource更合适。1.3 一次MCP通信的完整流程打开任意一个已配置MCP的AI客户端在对话里让模型调用一次工具背后发生的完整流程是这样的Host启动MCP Client通过stdio或HTTP/SSE与MCP Server建立连接。双方完成initialize握手并协商协议版本和各自支持的能力例如是否支持采样、是否支持根资源。Client发送[tools/list]拿到Server注册的所有工具清单包括名称、描述、入参JSON Schema。这些工具清单被注入模型的上下文模型根据用户意图、工具描述、参数Schema判断该调用哪个工具决定好参数值。Client发送[tools/call]把工具名和参数传给Server。Server执行具体逻辑把结构化结果返回给Client。Client把工具结果追加给模型模型基于结果生成最终回复。整个流程基于JSON-RPC 2.0的消息格式所以MCP本身并不绑定任何编程语言。你完全可以用Python写Server用Node.js写Client只要两边都按协议说话就行。2. 环境准备与最小MCP Server实现2.1 技术选型官方SDK还是FastMCP官方Python SDK是最具兼容性的选择底层细节实现完整适合对协议要求严格、功能复杂的场景。不过对大多数人来说官方SDK的样板代码确实偏多写一个小工具要定义一堆东西上手体感一般。我实际项目里更常用的是一个社区封装叫FastMCP它在官方SDK之上做了极简化包装。你只需要定义一个函数加一行装饰器这个函数瞬间就变成了一个标准的MCP Tool。整个Server的启动、协议细节、参数校验框架全部帮你处理掉了。如果你想让一个工具尽快跑起来验证效果优先选FastMCP。如果你做企业级复杂Server需要精细控制协议行为再考虑官方SDK。本文为了便于理解示例代码里我会用FastMCP来演示最后也会说明两者如何互相切换。2.2 环境搭建与项目初始化先准备一个干净的环境。我用的是Python 3.10理论上3.9也能跑但类型注解的新语法还是3.10之后更舒服。创建虚拟环境和安装依赖mkdir mcp-demo cd mcp-demo python -m venv .venv source .venv/bin/activate # Windows是 .venv\Scripts\activate pip install fastmcp pip install psutil # 后面做系统监控工具要用装好之后可以顺便看一眼安装了哪些依赖pip list | grep mcp你会看到类似mcp、fastmcp这样的包名。需要注意一个坑fastmcp这个包对mcp库的版本有要求最好直接用官方推荐的组合不要手动把某个库单独升级到太新的测试版版本冲突会带来很多莫名其妙的问题。2.3 第一个MCP Server服务器状态查询工具我设计了一个很实用的例子写一个MCP Server暴露两个Tool——一个查询CPU和内存使用率一个查询磁盘分区信息。这样你在任意MCP客户端里都可以直接用自然语言问“当前服务器负载怎么样”AI会自己决定调用哪个工具。先创建server.pyimport psutil from fastmcp import FastMCP mcp FastMCP(SystemMonitor) mcp.tool() def get_cpu_memory_usage() - dict: 获取当前服务器的CPU使用率和内存使用情况 cpu_percent psutil.cpu_percent(interval1) memory psutil.virtual_memory() return { cpu_percent: cpu_percent, memory_total_gb: round(memory.total / (1024 ** 3), 2), memory_used_gb: round(memory.used / (1024 ** 3), 2), memory_percent: memory.percent, } mcp.tool() def get_disk_usage(path: str /) - dict: 查询指定路径所在磁盘分区的使用情况 Args: path: 要查询的路径默认是服务器根目录 usage psutil.disk_usage(path) return { path: path, total_gb: round(usage.total / (1024 ** 3), 2), used_gb: round(usage.used / (1024 ** 3), 2), free_gb: round(usage.free / (1024 ** 3), 2), percent: usage.percent, } if __name__ __main__: mcp.run()这段代码里有几个细节值得展开讲讲。第一函数名本身就是工具名。在MCP协议里工具名会原样传给模型所以工具命名要尽量短、语义清楚。get_cpu_memory_usage比query_cpu_status更明确因为模型可以通过名字直接判断这个工具能干什么。第二函数的docstring会作为工具描述进入协议。MCP把工具的description字段传给模型模型靠这个判断工具的使用场景。这个地方一定要写清楚“这个工具是干什么的”不要只写参数不要用敷衍的描述。你写得好不好直接决定模型调用工具的准确率。第三带默认值的参数会自动成为可选参数。get_disk_usage里的path: str /FastMCP会把它解析成JSON Schema里的optional。模型不会每次都填这个参数它会根据用户问题判断是否需要指定路径。最后启动方式mcp.run()默认走的是stdio传输。这个在本地测试和桌面端接入时最方便后面接Web平台时会换成HTTP模式。2.4 用MCP Inspector验证Server代码写完了先别急着接客户端用官方自带的调试工具MCP Inspector做一次快速验证。MCP Inspector是一个Web调试面板你可以在浏览器里看到Server暴露了哪些工具手动填参数调用甚至自动生成协议请求消息。启动方式只需要一条命令mcp dev server.py启动后会有个本机端口浏览器打开就能看到面板。切到Tools标签你会看到Server自动注册的两个工具get_cpu_memory_usage和get_disk_usage。点开get_cpu_memory_usage传入空参数点Call按钮右侧就会返回类似这样的JSON{ cpu_percent: 23.4, memory_total_gb: 16.0, memory_used_gb: 6.2, memory_percent: 38.7 }这个返回值符合预期说明我们的MCP Server本身是能正常工作的。走这一步非常重要因为后面如果客户端接入出问题至少可以先把责任定位在Server端还是Client端。3. 客户端接入让AI真正用起来3.1 官方SDK客户端调用示例Server写好了我们来当一次“客户端”。这里我直接写一个Python程序模拟Client的行为完整走一遍“初始化→拿工具清单→调用工具”的流程。创建client.pyimport asyncio from mcp import ClientSession, StdioServerParameters from mcp.client.stdio import stdio_client async def main(): # 1. 配置要连接的Server启动参数 server_params StdioServerParameters( commandpython, args[server.py], cwdNone, ) # 2. 启动子进程并建立stdio通道 async with stdio_client(server_params) as (read_stream, write_stream): # 3. 创建会话自动完成initialize握手 async with ClientSession(read_stream, write_stream) as session: # 4. 获取工具列表 tools await session.list_tools() print(可用工具:, [tool.name for tool in tools.tools]) # 5. 调用工具 result await session.call_tool(get_cpu_memory_usage, {}) print(调用结果:, result) if __name__ __main__: asyncio.run(main())运行方式python client.py你会看到控制台打印可用工具: [get_cpu_memory_usage, get_disk_usage] 调用结果: ...一段包含CPU和内存数据的结构化内容这个脚本的骨架和你把MCP接入Claude Desktop、Dify平台时的内部逻辑是完全一致的。区别只是Host界面帮你做了界面层底层协议交互一模一样。3.2 理解Tools调用的参数流转很多人第一次写完Client会对“模型怎么知道要传什么参数”感到疑惑。把参数流转的过程拆开看事情就清楚了。当Client向Server发送tools/listServer返回的工具定义里包含一个inputSchema字段。比如get_disk_usage的Schema大致长这样{ type: object, properties: { path: { type: string, description: 要查询的路径默认是服务器根目录 } }, required: [] }这个Schema进入Host后会被拼接到系统提示词里。模型看到用户的问题“查一下C盘空间够不够”结合get_disk_usage的描述和Schema就知道应该调用这个工具并生成参数{path: C:\\}。所以Schema质量决定调用准确率。如果你的入参是一个复杂的嵌套结构最好给每个字段都写清楚描述给枚举值写清楚可选范围。模型不是程序员它只能根据你传递给它的文字信息来推断参数。我建议在定义工具函数时使用Google风格或numpy风格的docstring把参数含义写在一行里FastMCP会自动解析成Schema里的description。这个动作虽然小但对最终体验的提升非常明显。3.3 Tools和Resources的区别与选型前面提过Tool和Resource是两种不同的协议原语这里展开细说。Tool更适合“动作型”能力比如“创建订单”“发送通知”“执行SQL”。这些操作通常有副作用有的还需要鉴权。Tool的执行结果一般直接返回给模型由模型组织成最终回答。所谓“AI智能体”就是靠模型反复调用Tool、观察结果、再决定下一步来实现的。Resource更适合“上下文型”能力比如“读取项目规范文档”“读取数据库表结构”“读取某份报表”。它不是动态执行动作而是把数据当作上下文的一部分塞给模型。你可以把Resource类比成一组可动态加载的上下文文件。在实践中如果你希望模型“看看某个文件再回答问题”应该用Resource如果你希望模型“调用某个接口完成特定操作”应该用Tool。两者可以同时存在于一个MCP Server中互不冲突。FastMCP里注册一个Resource也很简单from fastmcp import FastMCP mcp FastMCP(ConfigCenter) mcp.resource(config://app) def get_config() - str: 返回应用配置信息 return open(app_config.yaml).read()Resource有一个URI标识config://app这种自定义协议是允许的。Client端通过read_resource方法去读取。4. 实战扩展MCP与全栈开发场景结合4.1 与Flask Web应用协同工作很多团队当前的整体架构是前端Flask后端AI能力。MCP Server有个老生常谈的问题——它默认走stdio只适合本地被某个Client拉起。如果Web应用要通过HTTP暴露工具能力就得开启MCP的HTTP传输模式。FastMCP切换到HTTP模式的方式很简单if __name__ __main__: mcp.run(transporthttp)默认会启动一个基于ASGIuvicorn的HTTP服务监听在8000端口。你可以在浏览器访问http://localhost:8000/mcp这是HTTPSSE的接入端点。注意一点如果mcp.run()默认开发服务器不够用你需要自己挂载到已有的Flask应用里。FastMCP底层基于mcp官方库官方SDK的ASGI服务对象是可以直接嵌入Flask的。我的一个常见做法是把MCP Server单独作为微服务跑在独立进程里Flask应用通过HTTP client去调用两者互不阻塞。这样MCP Server能独立扩缩容权限和密钥也能和Web主应用隔离。import httpx from flask import Flask, jsonify, request app Flask(__name__) MCP_HTTP_URL http://127.0.0.1:8000/mcp app.route(/api/ai/check_server, methods[GET]) def check_server(): # 这里假设我们通过某种方式获取MCP的session token # 实际项目会有完整的鉴权流程这里做简化 params request.args path params.get(path, /) result call_mcp_tool(get_disk_usage, {path: path}) return jsonify(result) def call_mcp_tool(tool_name: str, arguments: dict): # 通过HTTPSSE方式向MCP Server发起tools/call # 完整实现需要处理SSE流这里用伪代码表示 pass上面call_mcp_tool里的SSE流处理较长如果在正式项目里建议直接用官方SDK封装好的HTTP client不要自己裸写SSE解析。你只需要记住一个原则Web主应用和MCP Server保持进程隔离通过HTTP通信这样部署和排障都更简单。4.2 在Dify智能体平台接入MCP ServerDify这类开源智能体平台是MCP协议最典型的受益者。以前你要让Dify调用一个自定义工具得在平台里配置OpenAPI Schema或手动写工具描述很繁琐。现在Dify原生支持MCP协议你只需要填一个Server地址平台就能自动获取工具清单。在Dify里接入MCP的流程大概是这样进入某个Agent应用的编排页面找到“工具”或“MCP”配置入口。如果你想连远程MCP Server选择“HTTP”类型填http://服务器IP:8000/mcp这个地址。如果Server在Dify同一台机器上也可以选择“stdio”类型填启动命令python server.py。连接成功后MCP Server里注册的工具会自动出现在工具列表里你手动勾选允许哪些工具被Agent调用。在Agent对话框里输入“查看服务器磁盘空间使用情况”模型会自动完成工具调用。实际项目中我强烈建议把Server用HTTP模式部署到内网固定端口而不是让Dify用stdio去拉起进程。原因很简单Dify容器和Server进程之间的生命周期管理很麻烦一旦Server进程崩了Dify不会自动拉起最终结果就是Agent工具长时间不可用。HTTP模式下你只需要管好Server的systemd或supervisor进程Dify挂了再恢复重新连接就会很顺。4.3 批量注册工具的最佳实践当你有很多工具要暴露给模型时注册方式本身没问题真正的瓶颈在于工具描述的质量。模型上下文窗口有限不可能一次性加载几百个工具的描述。所以实际生产环境的经验是控制单个Server的工具数量尽量控制在5-20个左右。如果拆分不了太多Server给工具起名用统一前缀比如user_get、user_update、order_create、order_query这样模型理解起来更友好。参数用扁平的字符串、数字和布尔类型少用深层嵌套对象。模型生成JSON参数时嵌套太深容易出错。所有字段的description必须写清楚“是什么”和“怎么填”不要写“参数1”这种无意义的文字。每次修改Tool定义后重新连接MCP让Client获取最新清单否则模型还会基于旧的描述做判断。这几条做下来模型调用工具的成功率会有非常直观的提升。5. 常见问题与排查技巧实录5.1 连接不上/握手失败的排查最常见的MCP接入问题是连接失败。前端表现为对话时模型一直报“工具调用失败”后台日志显示initialize失败或握手超时。我建议按这个顺序排查先直接跑mcp dev server.py看Server能否正常启动工具能否正常列出。检查连接方式是否匹配。stdio模式要求Client能拉起来子进程HTTP模式要求端口可访问。检查协议版本。MCP的版本迭代很快Server和Client版本不匹配握手就会失败。检查日志级别。开发阶段把日志调到DEBUG官方SDK会打印完整的JSON-RPC收发消息能很清楚地看到哪一步断了。5.2 工具返回被截断的处理如果你在MCP Client里调用一个返回大量数据的工具结果只有前半段后面被截断多半是返回体积超过了会话配置的上限。MCP协议里对单个消息体大小有约定具体值取决于你自己的Client配置。处理办法通常有两种一是工具函数内部做分页和裁剪一次性只返回最必要的字段二是在Client侧调整最大消息长度。我偏向第一种因为这个限制不只是协议层面的对模型理解也有好处。模型拿到一份几十KB的JSON反而不容易提取重点。5.3 并发和超时问题当多个用户同时调用同一个MCP Server的工具时如果你的Server只支持单线程处理后来者的请求就会排队形成假卡死。解决办法是给HTTP模式下的Server加并发能力。FastMCP的HTTP模式基于uvicorn你可以在启动命令里显式指定Worker数量。即便只有一个进程只要工具函数不依赖全局可变状态异步并发也能大幅提升吞吐。工具执行时间如果超过几秒Client端通常会有超时限制。真正的解决方案是不要把长任务塞进MCP Tool里同步执行。如果必须执行就让Tool先返回“任务已受理请稍后查询结果”之类的确认信息再异步跑后台任务另配一个查询任务状态的Tool。这是我在实际项目中用过的最可靠的模式。5.4 踩坑清单汇总表为了方便你直接参考我把实际项目和网上案例中比较典型的坑整理成了一张表按问题、现象、原因、解决方式四个维度列出来问题现象原因解决方式握手失败Client报initialize超时协议版本不匹配统一升级Server/Client SDK到相同主版本工具列表为空界面上看不到任何工具工具注册失败或被异常吞掉在main块里加日志确认工具函数正常注册工具调用超时模型说“调用失败”单次执行超过Client超时上限长任务做异步化快速返回受理结果参数缺字段模型传的参数不完整工具描述和Schema不清晰重写docstring补充字段枚举值和单位端口冲突HTTP模式启动失败8000端口被占用指定其他端口或用nginx反向代理绑定具体路径多用户串数据登录用户A看到B的数据Server端全局变量缓存工具函数内不允许使用全局可变状态按请求上下文隔离这张表里的每一条都是我或朋友在真实项目中遇到过的。尤其是最后一条“串数据”看着低级但一旦出现排查起来很费劲。MCP Tool的函数本质上是一个无状态的服务千万不要把用户会话数据存成全局变量否则并发场景下一定会出乱子。从写第一个MCP Server到现在我的总体感受是MCP可能不是AI应用开发的最终答案但它是目前把“AI模型”和“业务系统”解耦得最干净的一次尝试。你不需要为了某个模型厂家的私有协议重写所有工具也不用等某个大模型平台把功能做全标准协议摆在那里谁接入谁受益。我这边的实际项目里已经把MCP Server做成了内部的一套“能力中台”几十个业务的通用能力权限校验、数据查询、工单操作全部以MCP Tool的形式暴露出去任何智能体应用拉起就能用。如果你刚开始接触这个概念建议先把我上面的例子跑通然后把你自己最常用的两三个系统接口封装进去接到Dify或你喜欢的聊天客户端里体验一下“AI直接用你定义的接口完成任务”的感觉你会上瘾的。
