做Agent开发的人应该都有过这种经历模型本身能力再强真要让它去查个订单、写个工单、读个数据库你还是得写一堆胶水代码。早期我是每个工具写一个函数再手动拼JSON Schema喂给模型调完这家模型换那家接口风格还对不上维护成本高得离谱。后来接触了MCPModel Context Protocol自己动手写了一个MCP-Server才算是把工具调用的路彻底理顺了。这篇文章是Agent系列的第8.4篇专门讲MCP-Server的开发实战。我会从协议设计思路讲起再到具体的代码实现、调试排错、生产化部署全程用我实际跑过的项目做例子。适合已经了解Agent基础概念、想给Agent接入真实业务能力的开发者阅读也适合正好在选型工具调用方案的团队参考。1. MCP协议到底解决了什么问题1.1 工具调用的碎片化困局在MCP出现之前给Agent接工具是一件非常私房的事。每个平台有自己的一套规则OpenAI用function callingAnthropic有tool useLangChain有自己的一套Tool抽象开源社区还有各种自研的JSON-RPC方案。看起来都在做同一件事但接口定义、参数传递、返回结构、错误处理全都不一样。我举个例子。如果同一个订单查询能力要同时给OpenAI的GPT、Claude和本地开源模型用你得写三个适配层一个把函数定义转成OpenAI的tools格式一个转成Anthropic的tool格式还要给开源模型写一套独立的调用协议。写完这些还没完参数校验、错误码、重试逻辑这些细节还得分别处理工作量直接翻三倍。这还算好的。更麻烦的是工具往往不是给某个模型单独用的。企业内部通常有统一的业务系统比如订单中心、CRM、工单系统。每个系统都有自己的接口规范有的走HTTP有的走内部RPC有的直接连数据库。每接入一套系统Agent就得为它单独写一套工具适配逻辑时间长了代码仓库里全是一堆互不兼容的工具驱动维护的人真想摔键盘。1.2 MCP的统一模型与核心架构MCP的思路其实特别直白既然所有工具调用的本质都是模型发请求程序执行后返回结果那就把这个过程标准化做成一个通用协议。打个比方这就跟USB-C接口的普及一样。以前充电器百花齐放每台设备一个接口后来大家统一成了Type-C本质原因不是Type-C技术多高深而是标准化带来的互联互通价值太大了。MCP就是AI工具调用领域的Type-C。从架构上看MCP模型里有几个关键角色Host宿主应用比如Claude Desktop、Cursor这类客户端软件也可以是自研的Agent应用。Client内嵌在Host中的协议客户端负责跟MCP-Server建立连接、发送请求、接收响应。Server也就是我们这篇文章要开发的对象它暴露工具Tool、资源Resource、提示词Prompt三类能力。Transport传输层目前主流两种本地场景用stdio远程场景用Streamable HTTP。我之前自己做Agent的时候最直观的感受是MCP-Server把数据和操作统一成了标准对象。查询数据库返回的数据可以做成Resource执行某个动作做成Tool固定的处理流程做成Prompt。Agent拿到这些描述之后自动判断什么时候该调哪个工具、怎么传参数这就不需要我在业务代码里做各种if-else判断了。2. 项目初始化与技术选型2.1 开发环境与SDK取舍先聊一下技术选型。MCP官方提供了Python和TypeScript的SDK我自己的主力语言是Python所以核心开发用Python。如果你团队是前端背景用TypeScript也完全没问题协议本身是语言无关的。Python这边有两条路一是直接用官方的mcp库它底层但完整二是用社区社区封装的fastmcp库它把很多样板代码简化了。我实际跑下来的建议是业务工具类的Server直接用fastmcp协议研究类的需求用官方SDK。fastmcp最香的地方在声明式定义。你写一个普通Python函数加个装饰器它就是一个MCP工具了。参数类型、描述、默认值直接从函数签名和docstring里提出来不用手动写JSON Schema这对快节奏开发来说是实打实的提效。选型敲定之后环境准备好就可以开工了。我建议用uv来管理Python环境比pip干净很多uv init mcp-order-server cd mcp-order-server uv add fastmcp如果用官方SDK就执行uv add mcp[cli]。这一篇的实战代码围绕fastmcp展开这样代码量最少逻辑最清晰。2.2 最小可运行骨架MCP-Server的最小骨架其实就是一个Python文件。先看一个最简单的例子from fastmcp import FastMCP # 创建Server实例名称会在客户端里显示 mcp FastMCP(order-service) mcp.tool() def ping() - str: 简单连通性测试工具 return pong if __name__ __main__: mcp.run()把它跑起来一个MCP-Server就算完成了。你可以用npx modelcontextprotocol/inspector python server.py打开调试面板在里面就能看到一个叫ping的工具点一下就能调用。这个骨架看着简单但背后的启动流程值得一提。mcp.run()默认用的是stdio传输协议走JSON-RPC 2.0消息通过标准输入输出传递。这意味着MCP-Server不是一个需要手动启动的HTTP服务而是由客户端作为子进程拉起来的。宿主应用比如Claude Desktop配置好启动命令需要时自动拉起你的Python进程然后双方通过stdin/stdout一问一答。理解了这一点后面很多调试问题就都能想通了。比如为什么在Server代码里乱写print会导致客户端连不上就是因为print把数据输出到了stdout把协议消息流给污染了。这个问题到后面第4章还会重点展开。3. 核心开发用MCP-Server暴露真实业务能力3.1 第一个业务工具订单状态查询骨架搭起来了接下来做个有业务价值的工具。我拿一个真实场景举例给Agent一个查询内部订单状态的能力。业务逻辑大概是前端Agent收到用户的问题帮我查一下订单20250101AB的物流状态模型判断需要调用订单查询工具于是从对话里提取订单号传入工具函数服务端程序去订单系统拉数据返回给模型模型再组织语言回复用户。看懂了这条链路就知道MCP-Server的工具函数本质上是给模型提供的一个外部世界操作句柄。代码实现如下import json import time from fastmcp import FastMCP mcp FastMCP(order-service) # 模拟内部订单系统的数据源 MOCK_ORDERS_DB { 20250101AB: {status: shipped, logistics: SF1234567890, eta: 2025-01-05}, 20250102CD: {status: pending, logistics: , eta: None}, } mcp.tool() def get_order_status(order_id: str) - str: 根据订单号查询订单状态和物流信息。 Args: order_id: 订单号格式为日期两位字母例如20250101AB order MOCK_ORDERS_DB.get(order_id) if order is None: return json.dumps({error: order not found, order_id: order_id}, ensure_asciiFalse) return json.dumps({order_id: order_id, **order}, ensure_asciiFalse) if __name__ __main__: mcp.run()这里面有几个细节值得大家注意。第一工具描述必须写得足够清楚。Docstring不只是给人看的它是模型决定要不要调用以及怎么调的关键依据。模型不会看你的函数体它只依赖函数名、参数的Schema和描述来做决策。描述写得太宽泛比如查询订单模型可能不知道该传什么参数写得太啰嗦又会在上下文里占地方。第二返回结果最好是序列化好的字符串或结构化数据。fastmcp允许你直接返回dict但实际调试中我发现返回字符串更稳妥因为不是所有客户端都会帮你做二次序列化。直接用json.dumps已经足够。第三根据业务场景决定返回的内容粒度。订单查询返回status和logistics就没必要再把数据库里的内部备注、结算金额之类全带出来。模型上下文就那么大塞一堆无关字段会稀释它对关键信息的注意力甚至可能导致它回答问题时引用错误数据。3.2 再进一步资源与提示词模板MCP-Server除了工具还能暴露资源和提示词。很多人刚开始只盯着Tool把Resource和Prompt忽略了。我建议你把这三者当成一个整体来设计。拿订单系统来说除了查状态这个动作Agent可能还需要一份订单状态说明文档比如什么状态代表什么含义、哪些状态支持用户自助修改。这种静态数据就可以暴露成Resourcemcp.resource(docs://order-status-guide) def get_order_status_guide() - str: 订单状态说明文档供Agent查询状态含义时参考。 return ( 订单状态取值说明\n - pending: 已下单待发货\n - shipped: 已发货物流单号见logistics字段\n - completed: 已完成\n - cancelled: 已取消\n )资源的特点是用户可以直接读取不需要经过模型决策。模型在回答用户问题时如果觉得需要了解状态定义就可以通过Client去读取这个资源内容。这样的好处是状态说明可以独立维护不用硬编码在System Prompt里。Prompt模板则适合一些固定的处理套路。比如查一个订单并总结物流进度mcp.prompt() def order_progress(order_id: str) - str: 查询订单并生成物流进度摘要。 return ( f请查询订单 {order_id} 的状态 然后根据物流单号给出进度摘要。 如果状态是pending请告知用户尚未发货。 )有了这三个层次的组合Agent就像一个配备了完整工具箱的实习生Prompt告诉它遇到任务先做什么准备Tool给它动手的能力Resource给它必要的背景知识。这在多轮对话场景里非常有用因为知识不需要在每次对话开始时就全部塞进上下文需要时按需拉取就行。3.3 边界意识模型只决策代码来执行开发MCP-Server时最需要建立一条红线模型只负责决策和参数提取所有实际执行、权限判断、数据校验都得落在代码里。我见过不少翻车案例在工具函数里直接信任模型传来的参数不做校验。比如订单号查询模型提取出的字符串可能格式不对、可能带有多余空格、甚至可能是用户有意构造的恶意输入。如果你不加处理直接拿去拼SQL轻则查不到数据重则出安全问题。我习惯在工具函数入口做三层校验def _normalize_order_id(order_id: str) - str: return order_id.strip().upper() mcp.tool() def get_order_status(order_id: str) - str: 查询订单状态只允许查询规范格式的订单号 order_id _normalize_order_id(order_id) if len(order_id) ! 10 or not order_id[-2:].isalpha(): return json.dumps({error: invalid order_id format}, ensure_asciiFalse) # 后续逻辑...这条规范看起来基础但在生产环境里特别管用。模型是概率系统偶尔会提取出带标点、被截断的实体。咱们在工具函数里把所有防御性检查都做了让模型拿到的永远是干净的结果整体系统的稳定性会高出一个量级。另外有个经验工具函数要尽量保持无状态不要在里面维护全局变量。如果真要记录调用历史或者做缓存建议用独立的数据结构并且要考虑多实例并发时的竞争问题。模型可以同时发起多个工具调用如果你用全局list存数据数据错乱只是时间问题。4. 调试、排错与生产化4.1 调试利器MCP InspectorMCP-Server开发完了不经过调试直接上都是自欺欺人。给MCP-Server调试有一个官方工具叫MCP Inspector。它启动后会拉起一个网页界面可以直观地看到你的Server列出了哪些工具、资源、提示词还能手动传参调用查看返回结果。我的调试流程如下npx modelcontextprotocol/inspector python server.py启动后浏览器打开Inspector界面一般会看到工具列表、资源列表、提示词列表。选择某个工具它会自动帮你把参数表单渲染出来填完参数点运行就能看到工具函数的返回结果。Inspector最大的价值在于你可以把Agent客户端的黑盒过程拆开来看。当Agent调用工具失败时你之前完全不知道模型到底报了哪一步错有了Inspector你可以先把工具单点测通再把问题范围缩小到模型侧。我自己的习惯是每新增一个工具都先跑Inspector过了再接入实际客户端。没必要非得打包好整个应用再统一测试单点验证的效率高太多了。4.2 stdio模式下最隐蔽的坑MCP-Server开发过程中最让我头疼的坑全部集中在stdio传输模式。这个问题如果你不知道踩进去基本要靠看日志一点点磨很浪费时间。坑一print污染输出流stdio模式下Server的所有输出都要通过stdout传给客户端。如果你在代码里写了print(debug...)这条输出会混进协议消息流直接导致对端JSON-RPC解析失败。症状表现是客户端连接总是失败报错信息又模棱两可。解决办法很简单所有调试信息走日志模块输出到stderr或者文件。import logging logging.basicConfig(filename/tmp/mcp-server.log, levellogging.DEBUG)坑二工具超时没有预期管理MCP默认的请求处理是有超时的。如果你的工具逻辑里做了阻塞式的外部API调用外部服务响应慢就会导致工具调用超时客户端认为调用失败。解决方案有两个一是内部做好超时控制和重试二是如果有耗时特别长的任务可以考虑把Server做成异步形式或者在工具内部返回任务已提交的状态再提供查询接口。坑三未捕获的异常导致整个Server崩溃工具函数里如果出现未捕获异常整个进程可能直接退出。客户端那边根本来不及拿到友好错误提示。所以我的工具函数一律在最外层套try-except约定返回统一错误结构try: result do_something() return {ok: True, data: result} except Exception as e: log.error(tool failed: %s, e) return {ok: False, error: str(e)}4.3 常见问题速查表把我在多个项目里实际踩过的坑整理成一张表方便大家按图索骥排查问题现象可能原因解决办法客户端报Failed to fetch toolsServer启动失败或stdio消息被污染检查代码里是否有print输出单独跑server.py看是否报错工具调用超时外部API慢或阻塞操作没设置超时在工具内部设置requests timeout必要时拆分长任务参数校验失败模型传的参数格式与Schema不匹配在函数里做兼容转换比如order_id统一去空格转大写返回数据大量截断工具返回内容太大占满上下文精简返回字段只返回模型回答必需的数据Inspector能调用但Agent客户端不行客户端缓存了旧的工具列表重启客户端进程或者检查客户端配置里的命令行参数中文返回乱码客户端与Server编码不一致确保Python源码UTF-8返回内容用json.dumps的ensure_asciiFalse表格里出现的这些问题没有一个是需要高深技巧才能解决的但它们确实会拖慢整个开发节奏。多跑几次踩实了遇到类似问题自然就能一眼锁定。5. 从本地到生产接入与治理5.1 接入主流Agent客户端开发好的MCP-Server最终要接入实际的Agent客户端使用。现在主流的客户端都支持MCP协议接入方式大同小异。以Claude Desktop为例它的配置文件里面有一段mcpServers配置{ mcpServers: { order-service: { command: python, args: [/path/to/server.py], env: { ORDER_API_BASE: http://internal-api.example.com } } } }配置好之后重启客户端就能在工具列表里看到你的MCP工具了。Cursor的做法也类似项目根目录放一个.cursor/mcp.json或者直接在设置里添加MCP Server填入启动命令就行。如果是自研的Agent应用直接用SDK写一个MCP客户端去连接Server即可Python SDK里已经封装好了连接、查询工具列表、调用工具等整套方法。这里有个很重要的经验生产环境不要直接硬编码数据库密码、API密钥在代码里。用环境变量注入的方式既安全又灵活。同一个Server代码开发环境连测试库生产环境连生产库只需要改环境变量代码一行都不用动。5.2 远程部署与安全控制本地开发时用stdio很舒服但生产环境里Agent可能需要跑在不同的服务器上甚至云端部署。这时候就需要把MCP-Server从stdio切到Streamable HTTP模式。fastmcp切HTTP很简单if __name__ __main__: mcp.run(transportstreamable-http)默认会起一个HTTP服务客户端通过HTTP来连接。但远程化之后安全模型就完全不一样了。MCP本身对调用者没有认证机制它默认信任宿主应用。本地开发时无所谓因为Client和Server在同一台机器上信任关系是操作系统层面的一旦走HTTP到远端你就得自己解决认证和授权。我的建议是按下面的优先级来做传输层加密生产环境必须走HTTPS这是底线。调用方认证Server入口做Token校验或OAuth2认证确认请求来自你的Agent客户端。权限收敛MCP-Server的进程运行权限尽量小只给它能访问的系统资源不让Server成为进入内网的跳板。操作审计记录每次工具调用参数、调用方、时间后续出问题能追踪。做Agent安全的时候有一个思路特别重要MCP-Server相当于给模型开了一扇通向真实世界的门门里的东西必须由你来把关。模型不会意识到某个操作是否越权它只是按规则提取参数、发起调用。所有权限判断和安全逻辑都必须放在你的Server代码里。5.3 多Server治理与演进方向项目跑起来之后你会发现一个Agent可能不止接一个MCP-Server。比如订单查一个Server库存查一个Server内部文档查一个Server。多Server的好处是按业务域隔离坏处是工具数量膨胀之后模型的选择成本也会上升。我做过的两个治理动作值得参考。第一命名空间管理。每个Server的名称和工具名要遵循统一规范比如订单相关的Server里面的工具都以order_开头这样模型在判断用户要我查订单时能更快定位到正确工具集。第二工具数量控制。一个Server里的工具别无脑堆。模型在每次决策时通常只会从候选工具列表里选如果列表上百个搜索空间增大选错概率也会增加。控制单个Server工具数在10个左右比较合适多的可以考虑拆成多个Server或合并相似功能。说到演进方向我最近在把MCP-Server跟Agent的记忆体系做对接。MCP提供标准接口而需求是不变的Agent需要一个地方存储短期会话信息、长期用户偏好以及永久的业务规则。把这些存储能力封装成MCP工具Agent就可以按需调用而不需要在代码里耦合某个具体数据库。这个方向目前还在摸索阶段但已经有了比较清晰的手感。MCP-Server的定位就是Agent世界的统一技能接口如果你也在这条路上探索欢迎多交流。我在实际开发中还有一个体会写MCP-Server的门槛真的不高难的其实是对业务边界的理解和安全边界的把控。花半天时间把SDK文档过一遍你也能把第一个工具跑通但真正让Agent稳定可靠地工作靠的还是那些藏在细节里的校验、超时、重试、日志和权限控制。这篇文章里的经验都是我从一个个具体项目里磨出来的希望对正在做Agent开发的你有所帮助。
