1. 为什么要在百数里折腾 MCP而不是继续写普通插件百数这个平台用过的人都知道它的表单、流程、报表能力已经能覆盖大部分企业内部的轻量应用场景。但真到了要跟外部系统打交道的时候比如调一个本地的 Python 脚本做数据清洗、接一个第三方的 MCP Server 来扩展智能体的能力边界很多人第一反应还是写个插件呗。我一开始也是这么想的直到踩了几次坑才发现插件和 MCP 根本不是一个层面的东西。MCP全称 Model Context Protocol直译过来叫模型上下文协议。你可以把它理解成一套智能体和外部工具之间的通用插座标准。以前智能体要调一个工具得针对每个工具写一套适配代码工具换了接口智能体这边就得跟着改。MCP 做的事情就是把这个适配层标准化——只要工具按照 MCP 协议暴露自己的能力任何支持 MCP 的智能体都能直接挂载使用不用改一行智能体侧的代码。那为什么要在百数里做这件事因为百数本身有表单数据、有流程引擎、有用户体系这些是天然的上下文来源。而 MCP 负责的是能力扩展。两者结合你就能做出这样的东西用户在百数表单里填一段需求触发流程流程调用一个私有 Python 工具做数据处理处理结果再通过 MCP Server 暴露给智能体智能体基于这些数据生成分析报告回写到百数报表里。整条链路里百数管数据和流程Python 工具管计算MCP 管连接智能体管决策。这套东西适合谁如果你已经会用百数搭表单和流程又懂一点 Python想让自己的应用聪明起来那这篇内容就是给你写的。如果你完全没碰过 Python也没关系我会把每一步拆到能直接抄的程度。但有一点要说在前面MCP 不是银弹它解决的是标准化连接的问题不解决工具本身好不好用的问题。工具写得烂挂上 MCP 一样烂。还有一个常见的误解得先澄清。很多人以为 MCP 是某个具体软件或者某个云服务其实不是。MCP 是一套协议规范你可以自己实现 Server也可以用别人写好的。百数这边要做的事情本质上是三件第一写一个符合 MCP 规范的私有 Python 工具第二把这个工具或者外部现成的 MCP Server 接进来第三让智能体能够挂载并调用这些能力。下面我按这个顺序把每一步的细节和坑都摊开讲。2. 私有 Python 工具的编写从能跑到能被 MCP 调用2.1 先想清楚工具边界别一上来就写代码我见过太多人一上来就打开编辑器开始写def main()写到一半发现不知道这个工具到底该接收什么参数、返回什么格式。MCP 工具和普通 Python 脚本最大的区别在于普通脚本你自己知道怎么调MCP 工具是给智能体调的智能体不知道你的潜规则。所以在写代码之前先拿张纸把这三件事写清楚输入是什么是百数表单里的一条记录还是一个文件路径还是一个 JSON 字符串输入的结构决定了你后面怎么定义 MCP 的 tool schema。输出是什么是纯文本是结构化 JSON还是直接写回百数输出格式决定了智能体能不能理解你的返回结果。失败怎么办网络超时、文件不存在、参数缺失这些情况返回什么MCP 协议里错误处理是有规范的不能随便抛个异常就完事。举个例子假设我要做一个根据百数表单里的销售数据生成月度汇总的工具。输入应该是表单 ID 和时间范围输出应该是一个结构化的汇总对象失败时应该返回明确的错误码和错误信息。这三件事想清楚了代码其实半小时就能写完。2.2 Python 环境准备别小看这一步环境这块我踩过的坑比写代码本身还多。先说 Python 版本MCP 相关的库对版本有要求建议直接用 3.10 及以上。3.9 及以下在某些异步库上会有兼容性问题别问我怎么知道的。安装 Python 本身就不展开了官网下载安装包一路下一步就行。重点说几个容易出问题的地方第一虚拟环境一定要建。我见过有人直接在系统 Python 里 pip install 一大堆包结果不同项目之间依赖打架最后连 Python 本身都跑不起来。用 venv 或者 conda 都行我个人习惯 venv轻量python -m venv mcp_env source mcp_env/bin/activate # Windows 用 mcp_env\Scripts\activate第二pip 源的问题。如果你在国内默认源下载某些包会非常慢甚至超时。换成国内镜像源能省很多时间pip config set global.index-url https://pypi.tuna.tsinghua.edu.cn/simple第三依赖锁定。MCP 相关的库更新比较频繁今天能跑的代码明天可能就因为某个依赖升级跑不起来了。建议用pip freeze requirements.txt把当前环境的依赖版本固定下来部署的时候用pip install -r requirements.txt复现。2.3 用 MCP SDK 写一个最小可用的工具MCP 官方提供了 Python SDK装起来很简单pip install mcp然后写一个最小的 Server。这里我用一个查询百数表单数据的例子因为这是最常见的场景from mcp.server import Server from mcp.server.stdio import stdio_server from mcp.types import Tool, TextContent import json app Server(baishu-tool) app.list_tools() async def list_tools(): return [ Tool( namequery_form_data, description根据表单ID和时间范围查询百数表单数据, inputSchema{ type: object, properties: { form_id: {type: string, description: 百数表单ID}, start_date: {type: string, description: 开始日期格式YYYY-MM-DD}, end_date: {type: string, description: 结束日期格式YYYY-MM-DD} }, required: [form_id, start_date, end_date] } ) ] app.call_tool() async def call_tool(name: str, arguments: dict): if name query_form_data: form_id arguments[form_id] start_date arguments[start_date] end_date arguments[end_date] # 这里调用百数的API获取数据 result fetch_baishu_data(form_id, start_date, end_date) return [TextContent(typetext, textjson.dumps(result, ensure_asciiFalse))] raise ValueError(f未知工具: {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())这段代码有几个关键点值得说。list_tools返回的是工具的描述信息智能体就是靠这个描述来决定什么时候调用你的工具。所以description一定要写清楚别写查询数据这种模糊的描述要写根据表单ID和时间范围查询百数表单数据智能体才能准确判断。inputSchema用的是 JSON Schema 格式required字段一定要标清楚不然智能体可能传空参数进来你的代码就会炸。call_tool里做参数校验和实际的数据获取返回的必须是TextContent列表这是 MCP 协议规定的格式。2.4 工具写完之后本地怎么验证写完代码别急着往百数里接先在本地跑通。MCP Server 通常用 stdio 模式启动也就是标准输入输出。你可以用 MCP Inspector 这个官方工具来测试npx modelcontextprotocol/inspector python your_server.py它会启动一个网页界面你可以在里面看到你的工具列表手动传参数调用看返回结果对不对。这一步能帮你排除掉 80% 的低级错误比如 schema 写错、返回值格式不对、异常没处理。我个人的习惯是在本地验证阶段就把所有边界情况都测一遍参数缺失、日期格式错误、表单 ID 不存在、网络超时。这些情况在智能体调用的时候一定会出现与其到时候手忙脚乱不如提前处理好。3. 外部 MCP Server 的接入别重复造轮子3.1 什么时候该用外部 Server什么时候该自己写这个问题我被问过很多次。我的判断标准很简单如果这个能力是通用的用外部 Server如果是跟你的业务强绑定的自己写。什么叫通用能力比如文件读写、网页抓取、数据库查询、代码执行这些几乎所有智能体都需要社区里已经有成熟的 MCP Server 实现直接拿来用就行。什么叫业务强绑定比如查询百数表单数据、触发百数流程、回写百数报表这些跟你的平台强相关外部 Server 不可能有只能自己写。还有一个中间地带有些外部 Server 功能很全但配置复杂或者跟你的环境不兼容。这时候要算一笔账——是花两天时间调通外部 Server还是花半天自己写一个精简版我遇到过好几次外部 Server 文档写得天花乱坠实际接进来一堆依赖冲突最后还不如自己写。3.2 接入外部 Server 的三种方式外部 MCP Server 的接入方式常见的有三种第一种stdio 方式。这是最简单的外部 Server 就是一个可执行程序你通过标准输入输出跟它通信。配置的时候指定命令和参数就行。比如接入一个文件系统 Server{ mcpServers: { filesystem: { command: npx, args: [-y, modelcontextprotocol/server-filesystem, /path/to/allowed/dir] } } }这种方式的好处是简单直接坏处是 Server 进程跟你的主进程绑在一起Server 挂了主进程也会受影响。第二种SSE 方式。Server-Sent EventsServer 作为一个独立的 HTTP 服务运行通过 SSE 推送消息。这种方式适合 Server 需要长期运行、多个客户端共享的场景。配置的时候指定 URL{ mcpServers: { remote-server: { url: http://localhost:8080/sse } } }第三种Streamable HTTP 方式。这是比较新的方式结合了 HTTP 的灵活性和流式传输的效率。适合部署在服务器上、需要跨网络访问的场景。选哪种我的经验是本地工具用 stdio团队共享用 SSE跨网络部署用 Streamable HTTP。别一上来就追求高级方式stdio 能解决的问题没必要上 HTTP。3.3 接入过程中最容易翻车的几个点依赖冲突。外部 Server 通常有自己的依赖如果你的环境里已经装了不同版本的同一个库就会冲突。解决办法是给每个外部 Server 建独立的虚拟环境或者用容器隔离。权限问题。有些 Server 需要访问文件系统或者网络如果你的运行环境权限受限Server 启动就会失败。这个在容器化部署的时候特别常见要提前确认好权限配置。版本兼容。MCP 协议本身还在演进不同版本的 Server 和客户端之间可能有兼容性问题。接入之前先确认双方的协议版本别到时候调了半天发现是版本不匹配。超时设置。外部 Server 如果响应慢你的智能体就会一直等。一定要设置合理的超时时间并且处理好超时后的降级逻辑。4. 智能体挂载 MCP 能力从能连到好用4.1 挂载的本质是什么很多人把挂载想得很神秘其实本质就一件事把 MCP Server 提供的工具列表注册到智能体的工具池里让智能体在需要的时候能调用。这个过程分两步。第一步是发现智能体启动或者初始化的时候会去问每个配置好的 MCP Server你有哪些工具Server 返回工具列表和 schema。第二步是调用智能体在推理过程中判断需要用哪个工具然后按照 schema 传参数Server 执行后返回结果。听起来简单但实际做的时候问题往往出在判断这一步。智能体怎么知道该用哪个工具靠的是工具的description和inputSchema。如果描述写得模糊智能体就会用错工具或者该用的时候不用。4.2 工具描述怎么写才能让智能体看懂这是我觉得整个流程里最需要经验的部分。写工具描述本质上是在写给智能体看的说明书。几个原则第一说清楚什么时候用。不要只写查询数据要写当用户需要根据时间范围查询百数表单中的销售记录时使用。智能体是靠场景匹配来决定调用的。第二参数描述要具体。form_id不要只写表单ID要写百数表单的唯一标识符可以在表单设置页面找到。智能体不知道你的平台长什么样你得告诉它。第三返回结果要可预期。如果返回的是 JSON在描述里说明结构。智能体拿到结果后要解析结构不清晰它就没法用。第四错误情况要说明。告诉智能体什么情况下会返回错误错误码是什么意思。这样智能体在遇到错误时能做出合理的反应而不是直接卡死。我一般会花写代码两倍的时间来打磨工具描述因为代码写错了能调试描述写错了智能体根本不知道怎么用。4.3 多工具协同的场景怎么设计单个工具挂载很简单难的是多个工具协同。比如一个完整的业务流程查询数据 → 数据清洗 → 生成报表 → 回写百数。这四个步骤对应四个工具智能体需要按顺序调用。这里有个坑智能体不一定按你预期的顺序调用。它可能先调清洗再调查询结果清洗的时候没数据。解决办法有两个一是把有依赖关系的工具合并成一个工具内部按顺序执行二是在工具描述里明确依赖关系比如调用此工具前必须先调用 query_form_data。我个人的偏好是第一种把强依赖的工具合并。虽然工具粒度变粗了但可靠性高很多。智能体不是人它不会理解你的业务流程你只能通过工具设计来引导它。4.4 挂载后的调试与监控挂载完成不代表万事大吉。上线之后要监控几件事调用成功率哪些工具经常失败失败原因是什么调用频率哪些工具被频繁调用是不是有智能体在死循环响应时间哪个工具拖慢了整体流程参数分布智能体传的参数是否符合预期有没有异常值这些数据能帮你持续优化工具设计。我见过一个案例某个工具的描述写得不够清楚智能体总是传错参数导致调用成功率只有 30%。后来把描述改清楚成功率直接上到 95%。工具本身没变就是描述变了。5. 整条链路的联调与踩坑实录5.1 联调顺序从内到外别跳步联调最忌讳的就是一把梭所有东西一起上出了问题不知道是哪一环。我的习惯是按这个顺序来单独测 Python 工具用 MCP Inspector 手动调用确认工具本身没问题。单独测外部 Server用同样的方式确认外部 Server 能正常响应。测智能体挂载先只挂一个工具确认智能体能发现并调用。测多工具协同逐步增加工具观察智能体的调用行为。测百数集成最后把百数的表单和流程接进来跑完整链路。每一步都确认没问题再进下一步。这样出问题的时候范围就缩小到当前这一步排查起来快很多。5.2 我踩过的几个典型坑坑一异步和同步混用。MCP 的 Python SDK 是异步的但百数的 API 客户端可能是同步的。直接在异步函数里调同步代码会阻塞事件循环导致整个 Server 卡死。解决办法是用asyncio.to_thread把同步调用包起来或者用异步的 HTTP 客户端。坑二编码问题。百数返回的数据里如果有中文处理不当会出现乱码。Python 3 默认是 UTF-8但如果你在某个环节用了encode(gbk)之类的就会出问题。统一用 UTF-8返回 JSON 的时候加ensure_asciiFalse。坑三长连接断开。SSE 方式的长连接如果网络不稳定会断开。断开之后智能体就收不到结果了。要加心跳机制和自动重连。坑四工具名冲突。如果你挂了多个 Server不同 Server 可能有同名工具。智能体调用的时候会混淆。解决办法是给工具名加前缀比如baishu_query_form_data、filesystem_read_file。坑五日志缺失。出问题的时候没有日志只能靠猜。一定要在每个关键节点打日志包括工具调用、参数、返回结果、异常信息。日志级别要可配置生产环境别打太多调试的时候再打开。5.3 性能优化的几个实际手段链路跑通之后如果发现慢可以从这几个地方优化缓存。百数表单数据如果变化不频繁可以缓存起来不用每次都查。缓存要设过期时间避免数据不一致。批量。如果智能体需要查多条数据别一条一条查做成批量接口。MCP 工具可以接收数组参数一次返回多条结果。异步。多个独立的工具调用可以并行执行别串行等。Python 的asyncio.gather能帮你做到这一点。精简返回。工具返回的数据别一股脑全丢给智能体只返回它需要的字段。返回数据越大智能体处理越慢token 消耗也越多。6. 一些关于工具设计和智能体协作的个人体会做这套东西做下来我最大的体会是MCP 工具的设计本质上是在设计智能体的能力边界。你给它什么工具它就能做什么事你的工具设计得好不好直接决定了它好不好用。我见过很多人把 MCP 当成技术活觉得只要代码写对了就行。但实际上代码只是基础真正决定成败的是工具的设计。一个描述清晰的简单工具比十个描述模糊的复杂工具更有价值。还有一个体会是别指望智能体理解你的业务。它只会按照你给的 schema 和描述来调用工具。你的业务流程再复杂也得拆成它能理解的工具调用序列。这不是智能体的局限这是所有工具调用系统的共性——你得把复杂的事情拆简单而不是指望系统自动理解复杂。最后说一个实际的小技巧。在正式上线之前我会用一批刁钻的测试用例来压测智能体的调用行为参数缺失、参数类型错误、超长输入、特殊字符、并发调用。这些情况在真实使用中一定会出现提前测出来比上线后被用户发现要好得多。这套东西目前还在持续迭代MCP 协议本身也在演进新的特性和最佳实践不断出现。但核心思路是不变的把能力标准化把连接简单化把智能体的边界交给工具设计来决定。