MCP系列第五集：从零开始构建MCP工具函数，TaoToken统一Key接入实战-北京尧图网络

1. 为什么我要自己写 MCP 工具函数MCP 工具函数说白了就是给大模型装上一双能干活的手。模型本身只会输出文字但通过 MCP 协议定义的工具函数它就能去查数据库、发消息、读文件、调接口。我一开始也觉得这东西离自己很远直到发现手头几个重复性任务——比如每天整理日志、定时拉取数据——完全可以让模型自己判断该调哪个函数才决定从零写一个。MCP 工具函数的核心逻辑其实就三步把业务逻辑封装成一个普通 Python 函数用装饰器把它注册成 MCP 能识别的工具然后运行时响应模型的调用请求。FastMCP 这个框架把这套流程压到了极简你写函数、加装饰器、启动服务剩下的参数校验、协议映射它全包了。这篇文章适合两类人一是刚接触 MCP、想搞明白工具函数到底怎么落地的开发者二是已经在用 Claude Desktop 或 Cursor但想把自己内部能力接进去的人。我会用 Python FastMCP 从零写一个可运行的工具服务再把它接到 TaoToken 的统一 Key 通道上最后跑一次端到端调用验证。全程代码可复制报错也有对照排查。先说清楚一个概念MCP 工具函数不是插件也不是简单的 API 封装。它是一份带类型注解和描述元数据的协议声明模型看到的是这份声明而不是你的源码。所以函数名、参数类型、description 写得好不好直接决定模型会不会正确调用。这一点在后面配置环节会反复体现。2. TaoToken 统一 Key 接入前的准备在写工具函数之前得先把调用通道理清楚。MCP 服务本身只负责“暴露工具”真正让模型发起调用的是客户端而客户端要连上模型就需要一个稳定的 API 入口。TaoToken 在这里扮演的就是统一 Key 通道的角色——你不需要为每个模型单独配一套 Key 和 Base URL一个 Key 走通对话、编码、Agent 场景。我试过把工具服务直接挂在本地让客户端调结果换模型时地址和 Key 全要改一遍非常碎。后来改成统一走 TaoToken 的 API 通道客户端配置只维护一份工具服务只管注册函数职责就分开了。你需要提前准备三样东西第一一个 TaoToken 的 API Key。到控制台的 API Keys 页面创建复制出来先存好后面配置里要用。地址是 https://taotoken.net/api-keys 注意这个页面是 deep link直接进 Key 管理。第二确认你的 Python 环境。FastMCP 要求 Python 3.10 以上我本地用的是 3.11比较稳。用python --version确认一下低于 3.10 的先升级。第三装依赖。FastMCP 可以用 pip 装也可以用 uv 管理。我习惯用 uv速度快、隔离干净pip install fastmcp # 或者用 uv uv pip install fastmcp装完之后验证一下python -c import fastmcp; print(fastmcp.__version__)能打印出版本号就说明环境没问题。如果报ModuleNotFoundError多半是装到了别的 Python 解释器里用which python和which pip对一下路径。这里有个容易忽略的点MCP 服务默认走 stdio 传输也就是通过标准输入输出和客户端通信。这意味着你不能在工具函数里随便print调试信息否则会污染协议数据流客户端会解析失败。调试信息一律走logging写到 stderr 或者文件。这个坑我在第一次跑的时候踩过客户端一直报解析错误查了半天才发现是函数里有个 print。TaoToken 的 API 地址是 https://taotoken.net/api 配置客户端时 Base URL 填这个Key 填刚才创建的。模型 ID 按你实际要用的填比如对话场景和编码场景可以选不同的模型。这三件套——Base URL、Key、Model ID——在后面客户端配置里会一起出现缺一不可。3. 用 FastMCP 装饰器写第一个工具函数现在进入正题写代码。我建一个目录叫mcp-demo里面放一个server.py。整个服务的骨架非常短from fastmcp import FastMCP import logging logging.basicConfig(levellogging.INFO) logger logging.getLogger(mcp-demo) mcp FastMCP(demo-tools) mcp.tool(description计算两个整数的和用于演示基础工具函数) def add(a: int, b: int) - int: 返回 a 与 b 的和 logger.info(add called with %s, %s, a, b) return a b if __name__ __main__: mcp.run()就这么几行一个 MCP 工具服务就起来了。FastMCP(demo-tools)创建服务实例mcp.tool装饰器把add注册成工具description是给模型看的说明类型注解a: int, b: int会自动生成参数校验规则。模型调用时传字符串 3 和 5框架会尝试转成 int转不了就返回参数错误。再写一个稍微实用点的工具模拟查询订单状态mcp.tool(description根据订单号查询订单状态返回状态字符串) def query_order(order_id: str) - str: 模拟订单查询实际项目替换为数据库调用 fake_db { A1001: 已发货, A1002: 待付款, A1003: 已完成, } status fake_db.get(order_id, 订单不存在) logger.info(query_order %s - %s, order_id, status) return status注意description的写法。不要写“查询订单”要写清楚“根据订单号查询订单状态返回状态字符串”。模型是靠这句话判断什么时候该调这个工具的。描述越具体误调用越少。如果你要写异步工具直接用async def就行FastMCP 原生支持import asyncio mcp.tool(description异步等待指定秒数后返回完成信息) async def wait_task(seconds: int) - str: await asyncio.sleep(seconds) return fwaited {seconds}s启动服务python server.py这时候服务会以 stdio 模式挂起等待客户端连接。你直接跑会看到它“卡住”这是正常的它在等输入。要单独测试工具逻辑可以写个测试脚本直接调函数或者用 MCP Inspector 连上去手动调。关于装饰器参数除了description还可以传name自定义工具名。默认用函数名但函数名带下划线有时候模型识别不好可以改成更自然的写法mcp.tool(namequeryOrderStatus, description根据订单号查询订单状态) def query_order(order_id: str) - str: ...工具名建议用驼峰或短横线别用太长的下划线串。参数名也一样order_id比oid好模型能理解语义。4. 把工具服务接到 TaoToken 通道并验证调用工具服务写好了接下来要让它真正被模型调用。这一步分两块客户端配置和端到端验证。先说客户端配置。以 Claude Desktop 为例配置文件在~/Library/Application Support/Claude/claude_desktop_config.jsonmacOS或%APPDATA%\Claude\claude_desktop_config.jsonWindows。你要在mcpServers里加上自己的服务同时模型通道走 TaoToken{ mcpServers: { demo-tools: { command: python, args: [/absolute/path/to/mcp-demo/server.py] } } }注意args里必须是绝对路径相对路径客户端解析不到。配好后重启 Claude Desktop它会在启动时拉起这个 MCP 服务。模型通道这边如果你用的是支持自定义 Base URL 的客户端比如 Cursor 或 Cline配置里填三件套{ baseUrl: https://taotoken.net/api, apiKey: 你的_TaoToken_Key, model: 你选用的模型ID }Base URL 就是 https://taotoken.net/api 不要加多余路径。Key 用控制台创建的那个。Model ID 按场景选编码类任务和对话类任务可以不同。配好之后做端到端验证。在客户端对话框里输入“帮我算一下 128 加 256然后查一下订单 A1001 的状态。” 模型应该会先调add再调query_order最后把两个结果拼起来回答。如果调用成功你会在客户端看到工具调用记录服务端日志也会打印add called with 128, 256和query_order A1001 - 已发货。这就说明整条链路通了客户端 → TaoToken 通道 → 模型 → MCP 工具服务 → 返回结果。验证的时候建议先单独测一个工具别一上来就组合调用。先问“128 加 256 等于多少”确认add被调用了再加订单查询。这样出问题好定位。另外TaoToken 的模型对话页面也可以用来快速验证模型本身是否正常响应地址是 https://taotoken.net/chat 先确认通道没问题再排查工具服务。5. 常见报错与排查对照这一节列几个我实际遇到过的报错对照着查能省不少时间。报错一401 Unauthorized或invalid api key这是 Key 的问题。先确认 Key 有没有复制完整前后有没有空格。然后确认 Base URL 填的是 https://taotoken.net/api 不是别的地址。如果 Key 是在别的项目里用的确认它没有过期或被删除。到 API Keys 页面重新生成一个再试。报错二local proxy failed或连接超时这种一般是客户端到 API 通道的网络问题或者 Base URL 写错了。检查配置里的 URL 有没有多写斜杠、少写路径。另外确认你的客户端版本支持自定义 Base URL有些老版本不认这个字段。报错三Error reading choices或返回体解析失败这个多半是模型 ID 填错了或者该模型不支持当前调用方式。换一个确认可用的 Model ID 再试。也有可能是工具服务里print污染了 stdio 流检查server.py里有没有裸print全部换成logging。报错四OAuth相关错误如果你用的是需要 OAuth 的客户端比如某些版本的 Claude Code配置方式不一样。Claude Code 的配置在~/.claude/settings.json或项目级.mcp.json认证走的是 OAuth 流程而不是简单 Key。这种情况下确认你的客户端版本和认证方式匹配别把 Key 模式硬套到 OAuth 模式上。报错五工具没被调用模型直接回答这不是报错但很常见。原因是description写得太模糊模型没意识到该调工具。把描述改具体比如把“查询订单”改成“根据订单号查询订单状态输入为订单号字符串返回状态文本”。另外确认工具服务真的被客户端拉起来了看客户端日志里有没有demo-tools的启动记录。报错六ModuleNotFoundError: No module named fastmcp客户端拉起服务时用的 Python 解释器和你装 fastmcp 的不是同一个。在配置里把command改成绝对路径的 Python比如/usr/local/bin/python3或者用虚拟环境的解释器路径。排查顺序建议先确认 Key 和 Base URL 对再确认模型 ID 对然后确认工具服务能独立启动最后看客户端日志。一层层往下查别跳步。6. 继续往下走把工具函数用起来工具函数跑通之后真正的价值在于复用。你可以把公司内部的查询接口、文件处理逻辑、数据清洗脚本都包成 MCP 工具模型就能按需调用。我现在的做法是每个业务域一个服务文件共用同一个 TaoToken 通道客户端配置里挂多个mcpServers条目。长期做编码和 Agent 任务的话可以考虑用 Coding Plan 把通道固定下来地址是 https://taotoken.net/coding-plan 这样模型和工具的组合更稳定不用每次调。如果你还没创建 Key直接去 https://taotoken.net/api-keys 建一个然后照着第 3 节的代码把第一个工具跑起来。接入文档在 https://taotoken.net/doc 配置细节都在里面。最后留一个实用建议工具函数的description和参数类型注解值得你花比写逻辑更多的时间去打磨。模型能不能正确调用八成取决于这两样而不是你的业务代码写得多漂亮。

MCP系列第五集：从零开始构建MCP工具函数，TaoToken统一Key接入实战

相关推荐

OpenAI Agent 工具全面开发者指南——从 RAG 到 Computer Use：Responses API 与 MCP 实战拆解，把 endpoint 改到 TaoToken

win安装openai codex后，把auth.json改到TaoToken的完整配置指南

Hermes-Agent分层校准部署实战：NPU/GPU/Mac全平台适配

更多资讯

OpenRig铝型材模拟赛车支架DIY：从选型到装配的完整指南

Ever Gauzy 商品评论插件（@gauzy/plugin-product-reviews）完整指南：从安装构建到源码级原理

洁净室工程核心技术解析：HVAC设计、风量计算与压差控制

智诺方AI｜论文中引用与间接转述，降重降AIGC的区分处理办法

智能制造导论PPT教学落地：感知-决策-执行-反馈四层实战框架

朝代历史视频的疆域图与战争动效怎么做：结构化分镜与 AI 自动成片的实战拆解

今日更新

我发现了一个新思路：用 Remotion + Claude Code 像写代码一样自动化生成短视频

Windows下 Codex 中 Chrome 和 Computer Use 插件不可用问题排查及解决参考方式：TaoToken 统一 Key 配置与验证

2026 大模型集体涨价：用 Python 做企业 Token 成本测算与选型避坑（附配置）

本周精选

如何彻底离线使用 Laya-CoreML：Hugging Face 下载、缓存机制与 local_files_only 详解

基于1Panel 部署MySQL MCP 服务：TaoToken 统一 Key 接入与 config.toml 配置实战

崇州园区营销网站建设避坑指南：5大注意事项保备案安全

本月热门

我发现了一个新思路：用 Remotion + Claude Code 像写代码一样自动化生成短视频

Windows下 Codex 中 Chrome 和 Computer Use 插件不可用问题排查及解决参考方式：TaoToken 统一 Key 配置与验证

2026 大模型集体涨价：用 Python 做企业 Token 成本测算与选型避坑（附配置）

读完文章，想聊聊您的网站？