百数平台MCP开发实战：用Python工具扩展AI智能体能力

这次我们来看百数平台的 MCP 开发流程。百数是一款低代码/BI 数据分析平台支持通过 Python 进行私有工具扩展而 MCPModel Context Protocol是让 AI 智能体调用外部工具的标准协议。把两者结合起来就可以让百数智能体调用你自己编写的私有 Python 工具完成数据查询、业务计算、文件处理和第三方 API 请求等任务。本文会围绕“私有 Python 工具编写”和“智能体挂载”两条主线展开先讲清楚 MCP 服务的结构再给出一套可以照着做的开发流程环境准备、工具编码、启动验证、百数平台挂载、接口调用和批量任务设计。如果你正在研究低代码平台与 AI Agent 的集成这篇文章可以直接收藏。1. 核心能力速览先把百数 MCP 开发涉及的核心能力列出来方便快速判断这套方案适不适合你的场景。能力项说明项目类型低代码平台扩展 MCPModel Context Protocol工具服务核心功能编写私有 Python 工具注册为 MCP 工具供百数智能体调用开发语言Python 3.10推荐 3.11 或 3.12依赖管理uv、pip 或 conda推荐使用 uv 管理虚拟环境MCP 传输方式stdio 用于本地调试HTTP/SSE 用于远程部署挂载入口百数平台的智能体配置 / MCP 服务管理页面工具内可调用能力任何 Python 库、HTTP API、数据库、本地文件系统批量任务可在智能体中多次调用也可在工具内部实现循环批量逻辑适合场景私有数据查询、业务计算、文档处理、AI 工作流编排部署环境本地开发机、内网服务器、云主机均可说明上表中的传输方式和挂载入口是 MCP 常见做法百数平台的具体配置项名称以你实际使用的控制台为准。显存占用不涉及MCP 服务本身主要是 CPU 和内存占用。2. 适用场景与使用边界2.1 适用场景百数 MCP 开发要解决的核心问题是让 AI 智能体不再只靠大模型自身的知识而是能调用真实业务系统里的工具。典型场景包括智能体需要查询私有数据库但不想把数据库口令直接暴露在 Prompt 里。智能体需要调用百数表单 API按条件筛选订单、客户、库存等数据。智能体需要执行 Python 计算、文件格式转换、第三方 HTTP 请求再基于结果生成分析报告。开发团队想沉淀一套内部工具库供多个智能体共用。BI 报表场景中智能体需要根据用户提问自动拉取指标数据并生成说明。2.2 使用边界以下是不能碰的边界开发前先明确MCP 工具只是把 Python 函数暴露给 AI函数的能力边界就是你的代码能力边界。不要给智能体开放删除、清库、文件覆盖、批量发送消息等高危操作。涉及企业数据、个人隐私、版权素材时必须确认授权范围。本地开发使用的数据不要随便上传到公开 MCP 服务私有工具建议部署在内网或本地。不要在代码里硬编码密钥必须使用环境变量或密钥管理服务。工具返回的内容会被大模型处理后展示给用户注意避免输出敏感字段。3. 环境准备与前置条件在编写 Python 工具之前先确认本地环境是否满足条件。3.1 操作系统与 Python 版本百数 MCP 开发主要面向 Python 开发者一般支持Windows 10/11、macOS、Linux 发行版。Python 3.10 及以上版本推荐 3.11 或 3.12。能正常访问百数平台控制台并具备一个可登录账号。检查当前 Python 版本python --version如果尚未安装 Python建议先安装官方版本并把 Python 和 pip 加入系统环境变量。3.2 包管理与虚拟环境推荐使用 uv 管理 Python 虚拟环境它比传统 pip 更快也更适合 MCP 这类需要依赖隔离的项目。pip install uv或者使用 Python 自带的 venvpython -m venv .venv source .venv/bin/activate # Windows 下使用 .venv\Scripts\activate3.3 MCP SDK 安装MCP 官方提供了 Python SDK推荐安装mcp包同时可以配合fastmcp简化开发体验。pip install mcp[cli] fastmcp国内网络环境如果安装慢可以替换为国内 PyPI 镜像源。安装完成后可以用以下命令确认python -c import mcp; print(mcp.__version__)3.4 百数平台相关准备在百数平台中你至少需要一个可登录的账号并进入目标应用/工作区。准备创建一个智能体。如果需要调用百数开放 API需要获取对应的 API 密钥或凭证具体以百数官方文档为准。4. 私有 Python 工具编写MCP 工具的本质是一个 Python 函数加上 MCP 装饰器后变成 AI 可发现、可调用、有输入输出 Schema 的服务。写工具的思路和写普通函数一样区别在于要多关注参数文档和返回格式。4.1 项目结构建议创建一个独立目录便于管理和迁移mcp-tool-demo/ ├── .env # 环境变量不入库 ├── requirements.txt ├── README.md └── src/ └── demo_tool/ ├── __init__.py └── server.py4.2 编写第一个最小工具下面是一个用 FastMCP 暴露“计算两数之和”的最小示例from fastmcp import FastMCP mcp FastMCP(my-tools) mcp.tool() def add(a: int, b: int) - int: 计算两个整数之和返回整数结果。 return a b if __name__ __main__: mcp.run()说明FastMCP(my-tools)创建一个 MCP 服务实例。mcp.tool()将add函数注册为工具。函数的 docstring 会被 AI 读取必须写清功能、参数含义和返回值。mcp.run()默认以 stdio 方式运行适合本地调试。4.3 编写有业务价值的工具只算加法满足不了业务需求。下面演示一个查询本地 JSON 销售数据的工具import json from pathlib import Path from typing import Optional from fastmcp import FastMCP mcp FastMCP(sales-tool) DATA_FILE Path(sales.json) def _load_sales() - list: if not DATA_FILE.exists(): return [] with DATA_FILE.open(r, encodingutf-8) as f: return json.load(f) mcp.tool() def query_sales_by_region(region: str, start_date: Optional[str] None) - str: 查询指定区域的销售数据。 参数: region: 区域名称例如 华东、华南。 start_date: 可选起始日期格式 YYYY-MM-DD。 返回: 销售明细的 JSON 字符串。 records _load_sales() result [r for r in records if r.get(region) region] if start_date: result [r for r in result if r.get(date, ) start_date] return json.dumps(result, ensure_asciiFalse, indent2) if __name__ __main__: mcp.run()这个工具的用途是让智能体调用query_sales_by_region来读取本地销售快照避免把整个文件内容塞进 Prompt。实际项目中可以把_load_sales()替换为数据库查询、百数 API 请求或内部服务调用。4.4 工具参数 Schema 设计MCP 会根据函数的类型提示自动生成 JSON Schema。为了让 AI 准确调用建议遵循以下规则参数名使用易懂的英文或拼音。明确类型标注int、str、Optional[str]、list[str]等。在 docstring 中注明取值范围和默认行为。返回统一为 JSON 字符串避免返回 Python 对象导致序列化错误。示例mcp.tool() def get_daily_report(biz_date: str, group_by: str day) - str: 获取业务日报。 参数: biz_date: 业务日期格式 YYYY-MM-DD。 group_by: 聚合维度可选 day、month。 返回: 日报结果 JSON 字符串。 # 具体实现省略 return json.dumps({biz_date: biz_date, group_by: group_by, status: ok})4.5 工具内调用第三方 HTTP APIMCP 工具内部可以调用任何 HTTP API。下面是一个带有正确异常处理的示例import os import requests from fastmcp import FastMCP mcp FastMCP(http-tool) def _request_with_timeout(url: str, timeout: int 10) - dict: resp requests.get(url, timeouttimeout) resp.raise_for_status() return resp.json() mcp.tool() def get_weather(city: str) - str: 查询指定城市的天气。 参数: city: 城市名称例如 北京。 返回: 天气信息 JSON 字符串。 api_key os.getenv(WEATHER_API_KEY, ) url fhttps://api.example.com/weather?city{city}key{api_key} try: data _request_with_timeout(url, timeout8) return json.dumps(data, ensure_asciiFalse) except Exception as e: return json.dumps({error: str(e)}, ensure_asciiFalse)注意这里的 URL 是示例实际需要替换为你所使用的天气服务密钥必须从环境变量读取。4.6 工具内调用百数 API如果业务数据在百数表单中可以通过百数开放 API 查询。下面给出一个示例结构正式开发前请根据百数官方 API 文档调整请求地址、请求方式和参数名import os import requests from fastmcp import FastMCP mcp FastMCP(baisu-tool) BAISU_API_URL os.getenv(BAISU_API_URL, https://your-baisu-api.example.com/api) BAISU_API_KEY os.getenv(BAISU_API_KEY, ) def _headers() - dict: return { Authorization: fBearer {BAISU_API_KEY}, Content-Type: application/json } mcp.tool() def query_form_data(form_id: str, keyword: str ) - str: 查询百数表单数据。 参数: form_id: 表单 ID。 keyword: 可选关键字过滤。 返回: 查询结果 JSON 字符串。 payload {formId: form_id, keyword: keyword} resp requests.post(BAISU_API_URL, jsonpayload, headers_headers(), timeout30) return resp.text这段代码只是模板真实请求参数以百数开放平台的 API 文档为准。拿到文档后套入同样的函数结构即可。5. MCP 服务启动与本地验证代码写完后需要启动 MCP 服务并验证工具是否可用。5.1 stdio 方式启动在项目根目录执行python src/demo_tool/server.py启动后进程通常不会打印太多内容而是等待标准输入输出上的 MCP 协议消息。如果看到报错说明依赖缺失或代码有问题需要先解决。5.2 使用 MCP Inspector 调试mcp[cli]自带 Inspector可以可视化查看工具列表和调用结果。常用命令python -m mcp shim或者使用 FastMCP 的调试入口python -c from fastmcp.cli import main; main()更通用的做法是安装mcpCLI 后执行mcp dev src/demo_tool/server.py启动后会在终端输出一个调试地址通常是http://127.0.0.1:6277以实际输出为准。打开地址后可以查看当前服务注册了哪些工具。选择工具并填写参数。直接调用工具并观察返回结果。查看错误堆栈定位异常。5.3 SSE 方式启动如果百数智能体运行在远程服务器上需要把 MCP 服务暴露为 HTTP 端点。FastMCP 支持 SSE 传输if __name__ __main__: mcp.run(transportsse)启动命令不变python src/demo_tool/server.py启动后服务会监听一个端口并在日志中打印地址。具体 host、port 配置需要根据你使用的 FastMCP 版本调整。提醒不要把服务直接暴露到公网。本地联调可以使用内网穿透临时映射公网地址联调完成后立即关闭。5.4 启动后的验证清单启动 MCP 服务后按以下清单逐项检查进程是否常驻是否因为依赖缺失退出。Inspector 是否能看到注册的工具。调用工具是否返回预期结果。日志中是否出现异常堆栈。监听端口是否被占用必要时更换端口。6. 在百数平台挂载智能体这是把私有工具真正“用起来”的关键一步。6.1 理解挂载流程百数平台的智能体通常支持配置外部 MCP 工具。通用流程是在平台控制台找到智能体或 AI 助手配置。添加一个 MCP 服务填写服务名称、传输类型和服务地址。平台拉取工具清单展示服务中注册的所有工具。选择需要的工具并配置用途说明。在智能体对话中测试调用。具体入口和字段名称以百数官方控制台为准但整体流程大同小异。6.2 本地联调注意事项本地开发时百数平台通常无法直接访问127.0.0.1需要选择以下方案之一使用内网穿透工具把本地 MCP 服务映射为临时公网地址仅用于联调验证。将 MCP 服务部署到一台百数平台可访问的服务器上填写服务器地址。确认平台支持 SSE 传输协议再配置对应地址。联调通过后必须关闭临时映射避免服务长期暴露。6.3 挂载后的效果验证挂载完成后在智能体对话框中输入类似指令请调用销售查询工具查一下华东区2024年7月1日之后的销售数据。如果智能体正确选择了query_sales_by_region并传入region华东、start_date2024-07-01工具会返回 JSON 数据智能体可以基于该数据生成总结。这表示挂载链路已经通了。如果智能体没有识别工具优先检查MCP 服务是否在运行。工具名称是否被正确拉取。工具描述是否足够清晰。平台是否需要额外的权限配置。7. 接口调用与批量任务设计MCP 工具本身是函数但函数内部可以调用任何 API。在百数 MCP 开发中常用方式有两种工具内调用第三方接口工具内调用百数 API。两种方式的结构类似关键在于配置好凭证和超时。7.1 工具内调用第三方 API 示例import os import requests from fastmcp import FastMCP mcp FastMCP(api-tool) mcp.tool() def get_wakatime_stats(username: str) - str: 查询用户的编码统计信息。 参数: username: 用户名。 url fhttps://api.example.com/users/{username}/stats try: resp requests.get(url, timeout10) return resp.text except Exception as e: return json.dumps({error: str(e)}, ensure_asciiFalse) if __name__ __main__: mcp.run()关键点是超时、异常捕获、密钥不硬编码。7.2 批量任务设计MCP 本身不负责调度但智能体可以在一次会话中多次调用同一工具。比如遍历多个城市逐个调用天气查询工具。遍历多个区域逐个调用销售查询工具。读取文件列表对每个文件调用处理工具。更可控的做法是在 Python 工具内部实现循环批量逻辑import json from typing import List from fastmcp import FastMCP mcp FastMCP(batch-tool) mcp.tool() def batch_query_sales(regions: List[str]) - str: 批量查询多个区域的销售数据。 参数: regions: 区域名称列表例如 [华东, 华南]。 返回: 各区域销售数据合并后的 JSON 字符串。 results {} for region in regions: # 替换为真实查询逻辑 results[region] {region: region, total: 100} return json.dumps(results, ensure_asciiFalse)批量场景下要控制单次调用耗时并在 docstring 中写明最大批量数量避免超时。7.3 HTTP 接口调用示例模板如果你需要直接通过 HTTP 调用 MCP 服务可以参考下面的 curl 模板。不同 MCP 框架的请求路径可能不同实际使用前先确认服务端路由。curl -X POST http://127.0.0.1:8000 \ -H Content-Type: application/json \ -d {jsonrpc:2.0,id:1,method:tools/call,params:{name:add,arguments:{a:1,b:2}}}注意这里的 URL 和方法体是 MCP JSON-RPC 风格的通用示例具体实现以所用框架和路由为准。开发调试阶段建议优先使用 Inspector。8. 资源占用与性能观察MCP 服务本身很轻量资源占用主要来自 Python 进程和依赖库。8.1 关注项本地调试运行 Inspector 会占用更多 CPU 和内存因为调试界面需要渲染。生产环境运行mcp.run()时内存占用通常在几十 MB 到几百 MB取决于 Python 包大小。如果工具内部加载模型或大文件内存会明显增长。8.2 观察方法Linux/macOS 下执行ps aux | grep pythonWindows 下使用任务管理器查看 Python 进程的内存占用。8.3 降低资源占用只安装必要的依赖避免一次性引入大模型库。数据库查询尽量使用分页避免全量加载。文件处理使用流式读取。不常用的服务可以按需启动用进程守护工具管理生命周期。8.4 性能瓶颈常见瓶颈包括工具内部请求外部 API 超时。大量数据拼接 JSON 字符串导致内存上升。多工具并发调用时 Python 进程未能充分利用多线程。服务暴露在公网后收到大量无关请求。这些都需要结合具体代码和部署环境分析不能一概而论。9. 常见问题与排查方法下面这张表汇总了百数 MCP 开发中的高频问题。问题现象可能原因排查方式解决方案服务启动后很快退出依赖缺失、端口被占用、语法错误查看启动日志命令行运行脚本观察报错安装依赖、更换端口、修复语法Inspector 看不到工具装饰器忘记加、服务实例未运行检查代码中是否有mcp.tool()补上装饰器重启服务智能体无法调用工具工具名称和描述不清晰平台未刷新在平台重新拉取工具清单检查服务地址优化工具描述重新保存配置调用工具超时网络问题、外部 API 慢、批量数据量过大在代码中加入耗时日志增加超时时间减小单次数据量分片处理返回 JSON 格式混乱返回了 Python 对象而非字符串检查函数返回类型统一用json.dumps转为字符串地址端口冲突本地端口被占用Windows 用netstat -anoLinux 用ss -ltnp更换端口启动或关闭占用进程数据泄露风险工具权限过大密钥硬编码审查工具函数是否包含危险操作限制权限使用环境变量存储密钥智能体反复报错参数缺失docstring 描述不清或参数名与业务不一致检查函数签名和文档字符串重写 docstring补充参数示例10. 最佳实践与使用建议10.1 开发阶段先写一个最简单的 “加法工具”验证 MCP 链路通不通再逐步增加业务功能。每个工具只做一件事函数体保持精简便于调试和复用。工具命名要直观例如query_sales_data避免使用难以理解的缩写。docstring 中写明参数格式、返回值结构、失败时返回什么。10.2 部署阶段密钥放在环境变量或密钥管理服务中禁止硬编码。MCP 服务建议运行在内网通过反向代理进行访问控制。如果平台需要公网地址联调完成后及时关停临时映射。日志输出要脱敏避免把用户隐私和敏感字段打进日志。10.3 使用阶段第一次调用工具时先使用测试数据验证结果。批量任务要设置合理的重试机制区分限流和故障。定期审查工具权限移除不再使用的工具。涉及人脸、声音、版权素材的工具必须确认授权后再开放给智能体。上线后要监控调用日志观察是否出现异常高频调用。10.4 合规提醒再次强调本文所有示例都用于合规开发测试。使用百数 MCP 工具时必须遵守所在国家和地区的法律法规、企业数据安全管理制度、百数平台使用协议以及第三方 API 的授权要求。不得将 MCP 服务用于任何非法用途不得绕过平台限制不得窃取账号或破坏系统。11. 总结与下一步百数 MCP 开发的核心链路很清晰编写 Python 函数用 MCP 注册为工具再挂载到百数智能体上。最值得先验证的是那个最简单的示例工具确认工具清单能被平台拉取、智能体能正确调用就可以证明整条链路是通的。最容易踩的坑有三个工具描述写得太含糊导致 AI 不会调用本地服务没有安全的访问方式导致联调困难密钥直接写在代码里造成安全隐患。解决这三个问题后面的业务扩展就会顺利很多。下一步可以继续扩展的方向把本地 JSON 数据源换成数据库或百数开放 API。在工具内部增加缓存降低外部接口的调用压力。编写多工具协作的智能体流程让 AI 自动决定调用哪个工具。将 MCP 服务容器化发布到内网服务器实现稳定复用。建议收藏备用写自己的第一个百数 MCP 工具时对照这篇文章一步步来就行。