1. 从空目录到可运行MCP 服务器环境搭建到底难在哪MCP 服务器听起来像是个很玄的东西其实你可以把它理解成一个“给大模型外挂的小工具箱”。模型本身只会聊天但通过 MCP 协议它能调用你本地写好的函数比如算个数、查个文件、读个数据库。问题在于很多人第一次配 MCP 服务器时卡在环境上Python 版本乱、依赖装不上、stdio 通信没反应、Cherry Studio 里填了参数却连不上。这篇就按“从零开始配置 MCP 服务器环境及手动编写自己的 MCP 程序”这个目标用 uv Python stdio 这条最稳的路线走一遍。适合谁适合已经会用 Cherry Studio 或 Cline但没自己写过 MCP 服务端的人也适合想把内部工具接进对话流、又不想折腾复杂框架的开发者。核心检索词就是 MCP 服务器、uv、python、stdio、cherry studio这几个词会贯穿全文。我试过用系统 Python 直接 pip install结果版本冲突到怀疑人生。后来换成 uv 管理虚拟环境和 Python 版本整个流程干净很多。下面每一步都给可复制的命令和配置你跟着做就能从空目录跑到一次端到端调用。先明确整体链路uv 负责装 Python 和依赖 → 写一个 stdio 模式的 MCP 服务端 → Cherry Studio 作为客户端启动这个服务端 → 服务端通过 TaoToken 统一 Key 完成鉴权如果你的工具需要调模型→ 对话里提问模型调用 add 工具返回结果。这条链路里stdio 是最容易本地调试的传输方式不需要开端口进程间直接通信。环境准备阶段Windows 用户打开 PowerShellmacOS/Linux 用户打开终端。uv 的安装脚本官方给得很直接Windows 下执行powershell -ExecutionPolicy ByPass -c irm https://astral.sh/uv/install.ps1 | iex装完先验证uv --version能打印出版本号就说明 uv 可用了。接着看当前机器上有哪些 Python 版本uv python list如果没看到 3.13就装一个uv python install 3.13这一步 uv 会把 Python 装到它自己的缓存目录不会污染系统环境。然后新建项目目录比如 F 盘下建 mcp_servermkdir F:\mcp_server cd F:\mcp_server uv init . -p 3.13uv init会生成 pyproject.toml 和基础结构-p 3.13指定 Python 版本。接着加 MCP 依赖uv add mcp[cli]这个命令会把 mcp 包和 CLI 工具一起装进虚拟环境。到这里环境部分就完成了。很多人卡在“uv add 报错”多半是网络或版本问题可以先uv python list确认 3.13 存在再重试。环境搭好后目录结构大概是这样pyproject.toml、uv.lock、.venv、还有你即将创建的 server.py。接下来就是写第一个 MCP 程序。MCP 的 Python SDK 提供了 FastMCP 这个高层封装几行代码就能注册工具和资源。stdio 模式下服务端通过标准输入输出和客户端通信所以不需要监听端口Cherry Studio 直接以子进程方式拉起它。写代码前先想清楚你的 MCP 服务端要暴露什么能力最简单的就是 add 工具再加一个动态 greeting 资源。工具是模型可以主动调用的函数资源是模型可以读取的数据。两者注册方式不同但都在同一个 FastMCP 实例上完成。下面进入具体编码和配置环节。2. TaoToken 前置统一 Key 与 API 通道准备在写 MCP 服务端之前先把鉴权通道准备好。如果你的 MCP 工具只是纯本地计算比如 add那其实不需要外部 Key。但真实场景里MCP 服务端经常要调模型、查知识库、走 API这时候就需要一个统一的入口来管理 Key 和额度。TaoToken 在这里的角色就是统一 Key 和 API 通道让你不用在多个服务商之间来回切换配置。先访问官网了解整体能力https://taotoken.net/?utm_sourcetaotoken_aicg_blog_endutm_mediumcsdnutm_campaignrewriteutm_content 。注册后进入控制台创建 API Key控制台地址是 https://taotoken.net/console?utm_sourcetaotoken_aicg_blog_endutm_mediumcsdnutm_campaignrewriteutm_content 。Key 的创建入口在 API Keys 页面https://taotoken.net/api-keys?utm_sourcetaotoken_aicg_blog_endutm_mediumcsdnutm_campaignrewriteutm_content 。拿到 Key 之后API 的基础地址是 https://taotoken.net/api 注意这个地址不加 UTM 参数直接用于代码里的 base_url。模型对话调试可以用 https://taotoken.net/models?utm_sourcetaotoken_aicg_blog_endutm_mediumcsdnutm_campaignrewriteutm_content 来验证模型是否可用。如果你打算长期做编码类 Agent可以看 Coding Planhttps://taotoken.net/coding-plan?utm_sourcetaotoken_aicg_blog_endutm_mediumcsdnutm_campaignrewriteutm_content 。接入文档在 https://taotoken.net/doc?utm_sourcetaotoken_aicg_blog_endutm_mediumcsdnutm_campaignrewriteutm_content 里面会说明不同协议的调用方式。Claude Code 相关的 Anthropic 兼容入口在 https://taotoken.net/ClaudeCodeAnthropic?utm_sourcetaotoken_aicg_blog_endutm_mediumcsdnutm_campaignrewriteutm_content 。为什么 MCP 服务端需要这个因为很多 MCP 工具的本质是“把模型能力封装成工具”。比如你写一个 summarize 工具内部要调模型这时候就需要 base_url api_key model_id 三件套。TaoToken 的统一 Key 让你在 MCP 服务端里只配一次后续换模型只改 model_id不用动鉴权逻辑。在 MCP 服务端代码里通常用环境变量读取 Key避免硬编码。比如set TAOTOKEN_API_KEY你的Key set TAOTOKEN_BASE_URLhttps://taotoken.net/apimacOS/Linux 用 export。然后在 Python 里用 os.environ 读取。这样 Cherry Studio 启动服务端时只要把环境变量传进去服务端就能拿到鉴权信息。这里要提醒一点不要把 Key 写进 server.py 提交到 Git。用 .env 或系统环境变量都行。如果你在 Cherry Studio 里配置 MCP 服务器它支持在配置里写 env 字段后面会给具体片段。模型 ID 怎么选在模型对话页面能看到可用模型列表选一个适合你任务的。比如做代码相关工具选编码能力强的做文本总结选通用对话模型。记住三件套Base URL 是 https://taotoken.net/api Key 是你创建的Model ID 按需选。这三样在后续配置里会反复出现。准备好这些之后回到 MCP 服务端本身。下一节给出完整的 server.py 代码和 Cherry Studio 配置片段包括 JSON 格式的配置路径和原文一致你可以直接复制。3. 可复制配置server.py 与 Cherry Studio 接入片段现在进入核心部分。在 F:\mcp_server 目录下创建 server.py内容如下from mcp.server.fastmcp import FastMCP # Create an MCP server mcp FastMCP(Demo) # Add an addition tool mcp.tool() def add(a: int, b: int) - int: Add two numbers return a b # Add a dynamic greeting resource mcp.resource(greeting://{name}) def get_greeting(name: str) - str: Get a personalized greeting return fHello, {name}! if __name__ __main__: mcp.run(transportstdio)这段代码注册了一个工具 add 和一个资源 greeting。transportstdio表示用标准输入输出通信这是本地 MCP 最常用的方式。另外两种协议是 sse 和 streamableHttp前者适合远程服务后者适合 HTTP 流式场景。本地调试优先 stdio因为不需要处理端口和网络。代码写完后先本地跑一下确认没报错uv run server.py如果进程挂起等待输入说明 stdio 服务端正常启动了。按 CtrlC 退出。接下来配置 Cherry Studio。打开 Cherry Studio进入 MCP 服务器设置添加一个新的 stdio 类型服务器。参数 args 填写--directory F:\mcp_server run main.py等等这里有个细节原文里写的是 run main.py但我们的文件叫 server.py。所以实际配置应该是--directory F:\mcp_server run server.py如果你把文件命名为 main.py那就用 main.py。关键是--directory后面跟项目绝对路径run后面跟入口文件名。Cherry Studio 会以子进程方式启动这个命令。完整的配置片段如果用 JSON 表示大概是这样{ mcpServers: { demo-server: { command: uv, args: [ --directory, F:\\mcp_server, run, server.py ], env: { TAOTOKEN_API_KEY: 你的Key, TAOTOKEN_BASE_URL: https://taotoken.net/api } } } }注意 Windows 路径里的反斜杠要转义成双反斜杠。如果你在 Cherry Studio 图形界面里填直接填单反斜杠即可。env 字段是可选的如果你的工具不需要调外部 API可以省略。但既然我们讲 TaoToken 统一 Key 接入建议保留后续扩展工具时直接用。配置保存后Cherry Studio 会尝试启动这个 MCP 服务器。如果启动成功你会看到工具列表里出现 add。如果失败检查 uv 是否在 PATH 里以及路径是否正确。这里有个常见坑Cherry Studio 启动子进程时工作目录可能不是 F:\mcp_server所以必须用--directory指定。另外uv run 会自动使用项目里的 .venv不需要手动激活虚拟环境。配置完成后在对话界面选择这个 MCP 服务器然后提问“89 等于几”。模型会识别到 add 工具调用它并返回 17。这就是一次端到端调用。如果模型没有调用工具检查工具描述是否清晰或者换一个明确要求使用工具的提问方式。如果你想让 MCP 服务端内部调用 TaoToken 的模型能力可以在 server.py 里加一个工具用 requests 或 openai SDK 调 https://taotoken.net/api 。三件套配置就是 Base URL、Key、Model ID。这样你的 MCP 工具就具备了模型能力而鉴权统一走 TaoToken。下一节讲验证请求和成功结果的具体观察点以及怎么确认工具真的被调用了。4. 验证请求与成功结果从提问到工具返回配置完成后最关键的一步是验证。很多人配完不知道有没有生效其实有几个明确的观察点。第一Cherry Studio 的 MCP 服务器状态。添加后如果显示绿色或“已连接”说明子进程启动成功。如果显示红色或报错点开日志看具体错误。常见的是command not found: uv说明 uv 没在系统 PATH 里或者 Cherry Studio 没继承环境变量。第二工具列表。连接成功后Cherry Studio 会列出这个 MCP 服务器暴露的工具。你应该能看到 add。如果看不到说明 server.py 里的mcp.tool()没生效检查代码缩进和装饰器。第三实际对话调用。在对话窗口选择该 MCP 服务器提问“89 等于几”。观察返回如果模型直接说 17 但没有工具调用痕迹可能是模型自己算的如果返回里带有工具调用记录比如add(a8, b9)然后返回 17说明 MCP 链路通了。为了更明确地验证可以问一个模型不容易直接算的比如“请用 add 工具计算 12345 67890”。这样模型必须调用工具才能得到准确结果。返回 80235 就说明工具执行成功。如果你想验证资源可以问“greeting://Alice 是什么”。模型会读取 greeting 资源并返回 Hello, Alice!。资源用mcp.resource注册URI 格式是greeting://{name}。如果 MCP 服务端内部要调 TaoToken 的模型验证方式类似加一个工具内部发 HTTP 请求到 https://taotoken.net/api 带上 Key 和 Model ID返回模型输出。然后在对话里触发这个工具看是否返回预期内容。这一步能验证统一 Key 是否配置正确。实测下来stdio 模式的好处是日志直接打在 Cherry Studio 的 MCP 日志里方便排查。如果请求失败先看日志里有没有 Python traceback。常见错误包括依赖没装全、Python 版本不对、路径写错。成功的结果长这样你提问模型决定调用 addCherry Studio 把请求通过 stdio 发给 server.pyserver.py 执行 add 返回结果Cherry Studio 把结果回传给模型模型组织语言回复你。整个过程在本地完成不需要网络除非工具内部调 API。验证通过后你可以继续扩展工具。比如加一个 read_file 工具读本地文件或者加一个 query_db 工具查数据库。每加一个工具重启 MCP 服务器Cherry Studio 会重新加载工具列表。下一节集中讲常见报错和排查方法包括 401、local proxy failed、reading choices、OAuth 这些真实错误。5. 本篇常见错排查401、local proxy failed、reading choices、OAuth配 MCP 服务器时报错信息往往很模糊。这里列几个真实遇到的错误和排查思路。401 Unauthorized这个通常出现在 MCP 服务端内部调 TaoToken API 时。原因就三个Key 没传、Key 错了、Base URL 错了。检查三件套Base URL 必须是 https://taotoken.net/api Key 从 API Keys 页面复制Model ID 在模型列表里选。如果 Key 放在环境变量里确认 Cherry Studio 的 env 字段有没有正确传递。可以在 server.py 里打印 os.environ.get(TAOTOKEN_API_KEY) 的前几位来确认。local proxy failed这个错误一般出现在客户端尝试连接 MCP 服务器时。stdio 模式下Cherry Studio 启动子进程失败就会报这个。排查顺序uv 是否在 PATH、--directory路径是否存在、入口文件是否存在、Python 版本是否匹配。可以在终端手动执行uv --directory F:\mcp_server run server.py看是否报错。如果终端能跑通但 Cherry Studio 报错说明是环境变量或工作目录问题。reading choices 相关错误这个通常出现在调模型 API 时返回格式不符合预期。检查请求体里的 model 字段是否正确以及 API 返回是否被正确解析。如果用的是 OpenAI 兼容 SDK确认 base_url 设置正确。TaoToken 的 API 地址是 https://taotoken.net/api 不要多加路径。OAuth 错误如果你在 MCP 配置里用了需要 OAuth 的远程服务可能会遇到 token 过期或回调失败。本地 stdio 模式一般不需要 OAuth。如果确实需要检查回调地址和 client_id。对于 TaoToken 的 Key 鉴权不涉及 OAuth直接用 API Key 即可。工具没被调用模型不调用工具通常是工具描述不够清晰。mcp.tool()的 docstring 会作为工具描述传给模型所以要写清楚功能。比如 “Add two numbers” 就比 “add” 好。另外提问方式也有影响明确说“请使用 add 工具”能提高调用率。Cherry Studio 里看不到工具先确认 MCP 服务器状态是已连接。如果连接成功但工具列表为空检查 server.py 里是否有mcp.tool()装饰的函数以及mcp.run()是否在__main__里执行。重启 Cherry Studio 和 MCP 服务器再试。uv add 失败网络问题居多。可以设置国内镜像或者重试。确认uv python list里有 3.13uv init时指定的版本和实际安装的一致。stdio 通信无响应如果服务端启动了但客户端收不到响应检查是否有 print 语句干扰了 stdio。stdio 模式下标准输出被用于协议通信任何额外的 print 都可能导致解析失败。调试信息用 stderr 输出比如print(..., filesys.stderr)。排查时记住一个原则先在终端手动跑通再放到 Cherry Studio 里跑。终端能跑通说明代码和依赖没问题问题就在客户端配置。终端跑不通就先解决代码和依赖。如果涉及 Claude Code 或 Codex 的 auth.json 配置三件套依然是 Base URL、Key、Model ID。Base URL 用 https://taotoken.net/api Key 用创建的Model ID 按需选。配置文件和路径要和实际使用的一致。排障完成后回到正常使用。下一节给出 CTA 分流按你的场景选入口。6. 按场景选入口API Keys、模型对话与 Coding Plan走到这里你已经完成了从空目录到可运行 MCP 服务的全流程。接下来按你的实际场景选下一步入口。如果你还在排障或接入阶段需要创建和管理 Key直接去 API Keys 页面https://taotoken.net/api-keys?utm_sourcetaotoken_aicg_blog_endutm_mediumcsdnutm_campaignrewriteutm_content 。接入文档在 https://taotoken.net/doc?utm_sourcetaotoken_aicg_blog_endutm_mediumcsdnutm_campaignrewriteutm_content 里面有不同协议的详细说明。如果你想先验证模型是否可用或者调试模型输出去模型对话页面https://taotoken.net/models?utm_sourcetaotoken_aicg_blog_endutm_mediumcsdnutm_campaignrewriteutm_content 。在这里可以快速测试 Base URL、Key、Model ID 三件套是否配置正确。如果你打算长期做编码类 Agent或者 MCP 工具需要频繁调用模型看 Coding Planhttps://taotoken.net/coding-plan?utm_sourcetaotoken_aicg_blog_endutm_mediumcsdnutm_campaignrewriteutm_content 。这个适合需要稳定额度和统一管理的场景。控制台入口https://taotoken.net/console?utm_sourcetaotoken_aicg_blog_endutm_mediumcsdnutm_campaignrewriteutm_content 。Claude Code 相关的 Anthropic 兼容入口https://taotoken.net/ClaudeCodeAnthropic?utm_sourcetaotoken_aicg_blog_endutm_mediumcsdnutm_campaignrewriteutm_content 。最后给一个实用技巧MCP 服务端的工具会随着你的需求增长。建议把每个工具拆成独立函数docstring 写清楚参数和返回值。这样模型调用时更准确。另外stdio 模式下不要用 print 调试用 stderr。每次改完 server.py重启 MCP 服务器再测试。如果你要把这个 MCP 服务端分享给别人记得把 Key 从代码里去掉用环境变量或配置文件。TaoToken 的统一 Key 让鉴权集中管理换 Key 不用改代码。整个流程跑通后你可以继续加工具比如文件操作、数据库查询、API 调用逐步把你的 MCP 服务器变成真正的工具箱。
从零开始配置MCP服务器环境及手动编写自己的MCP程序：TaoToken统一Key接入实战
1. 从空目录到可运行MCP 服务器环境搭建到底难在哪MCP 服务器听起来像是个很玄的东西其实你可以把它理解成一个“给大模型外挂的小工具箱”。模型本身只会聊天但通过 MCP 协议它能调用你本地写好的函数比如算个数、查个文件、读个数据库。问题在于很多人第一次配 MCP 服务器时卡在环境上Python 版本乱、依赖装不上、stdio 通信没反应、Cherry Studio 里填了参数却连不上。这篇就按“从零开始配置 MCP 服务器环境及手动编写自己的 MCP 程序”这个目标用 uv Python stdio 这条最稳的路线走一遍。适合谁适合已经会用 Cherry Studio 或 Cline但没自己写过 MCP 服务端的人也适合想把内部工具接进对话流、又不想折腾复杂框架的开发者。核心检索词就是 MCP 服务器、uv、python、stdio、cherry studio这几个词会贯穿全文。我试过用系统 Python 直接 pip install结果版本冲突到怀疑人生。后来换成 uv 管理虚拟环境和 Python 版本整个流程干净很多。下面每一步都给可复制的命令和配置你跟着做就能从空目录跑到一次端到端调用。先明确整体链路uv 负责装 Python 和依赖 → 写一个 stdio 模式的 MCP 服务端 → Cherry Studio 作为客户端启动这个服务端 → 服务端通过 TaoToken 统一 Key 完成鉴权如果你的工具需要调模型→ 对话里提问模型调用 add 工具返回结果。这条链路里stdio 是最容易本地调试的传输方式不需要开端口进程间直接通信。环境准备阶段Windows 用户打开 PowerShellmacOS/Linux 用户打开终端。uv 的安装脚本官方给得很直接Windows 下执行powershell -ExecutionPolicy ByPass -c irm https://astral.sh/uv/install.ps1 | iex装完先验证uv --version能打印出版本号就说明 uv 可用了。接着看当前机器上有哪些 Python 版本uv python list如果没看到 3.13就装一个uv python install 3.13这一步 uv 会把 Python 装到它自己的缓存目录不会污染系统环境。然后新建项目目录比如 F 盘下建 mcp_servermkdir F:\mcp_server cd F:\mcp_server uv init . -p 3.13uv init会生成 pyproject.toml 和基础结构-p 3.13指定 Python 版本。接着加 MCP 依赖uv add mcp[cli]这个命令会把 mcp 包和 CLI 工具一起装进虚拟环境。到这里环境部分就完成了。很多人卡在“uv add 报错”多半是网络或版本问题可以先uv python list确认 3.13 存在再重试。环境搭好后目录结构大概是这样pyproject.toml、uv.lock、.venv、还有你即将创建的 server.py。接下来就是写第一个 MCP 程序。MCP 的 Python SDK 提供了 FastMCP 这个高层封装几行代码就能注册工具和资源。stdio 模式下服务端通过标准输入输出和客户端通信所以不需要监听端口Cherry Studio 直接以子进程方式拉起它。写代码前先想清楚你的 MCP 服务端要暴露什么能力最简单的就是 add 工具再加一个动态 greeting 资源。工具是模型可以主动调用的函数资源是模型可以读取的数据。两者注册方式不同但都在同一个 FastMCP 实例上完成。下面进入具体编码和配置环节。2. TaoToken 前置统一 Key 与 API 通道准备在写 MCP 服务端之前先把鉴权通道准备好。如果你的 MCP 工具只是纯本地计算比如 add那其实不需要外部 Key。但真实场景里MCP 服务端经常要调模型、查知识库、走 API这时候就需要一个统一的入口来管理 Key 和额度。TaoToken 在这里的角色就是统一 Key 和 API 通道让你不用在多个服务商之间来回切换配置。先访问官网了解整体能力https://taotoken.net/?utm_sourcetaotoken_aicg_blog_endutm_mediumcsdnutm_campaignrewriteutm_content 。注册后进入控制台创建 API Key控制台地址是 https://taotoken.net/console?utm_sourcetaotoken_aicg_blog_endutm_mediumcsdnutm_campaignrewriteutm_content 。Key 的创建入口在 API Keys 页面https://taotoken.net/api-keys?utm_sourcetaotoken_aicg_blog_endutm_mediumcsdnutm_campaignrewriteutm_content 。拿到 Key 之后API 的基础地址是 https://taotoken.net/api 注意这个地址不加 UTM 参数直接用于代码里的 base_url。模型对话调试可以用 https://taotoken.net/models?utm_sourcetaotoken_aicg_blog_endutm_mediumcsdnutm_campaignrewriteutm_content 来验证模型是否可用。如果你打算长期做编码类 Agent可以看 Coding Planhttps://taotoken.net/coding-plan?utm_sourcetaotoken_aicg_blog_endutm_mediumcsdnutm_campaignrewriteutm_content 。接入文档在 https://taotoken.net/doc?utm_sourcetaotoken_aicg_blog_endutm_mediumcsdnutm_campaignrewriteutm_content 里面会说明不同协议的调用方式。Claude Code 相关的 Anthropic 兼容入口在 https://taotoken.net/ClaudeCodeAnthropic?utm_sourcetaotoken_aicg_blog_endutm_mediumcsdnutm_campaignrewriteutm_content 。为什么 MCP 服务端需要这个因为很多 MCP 工具的本质是“把模型能力封装成工具”。比如你写一个 summarize 工具内部要调模型这时候就需要 base_url api_key model_id 三件套。TaoToken 的统一 Key 让你在 MCP 服务端里只配一次后续换模型只改 model_id不用动鉴权逻辑。在 MCP 服务端代码里通常用环境变量读取 Key避免硬编码。比如set TAOTOKEN_API_KEY你的Key set TAOTOKEN_BASE_URLhttps://taotoken.net/apimacOS/Linux 用 export。然后在 Python 里用 os.environ 读取。这样 Cherry Studio 启动服务端时只要把环境变量传进去服务端就能拿到鉴权信息。这里要提醒一点不要把 Key 写进 server.py 提交到 Git。用 .env 或系统环境变量都行。如果你在 Cherry Studio 里配置 MCP 服务器它支持在配置里写 env 字段后面会给具体片段。模型 ID 怎么选在模型对话页面能看到可用模型列表选一个适合你任务的。比如做代码相关工具选编码能力强的做文本总结选通用对话模型。记住三件套Base URL 是 https://taotoken.net/api Key 是你创建的Model ID 按需选。这三样在后续配置里会反复出现。准备好这些之后回到 MCP 服务端本身。下一节给出完整的 server.py 代码和 Cherry Studio 配置片段包括 JSON 格式的配置路径和原文一致你可以直接复制。3. 可复制配置server.py 与 Cherry Studio 接入片段现在进入核心部分。在 F:\mcp_server 目录下创建 server.py内容如下from mcp.server.fastmcp import FastMCP # Create an MCP server mcp FastMCP(Demo) # Add an addition tool mcp.tool() def add(a: int, b: int) - int: Add two numbers return a b # Add a dynamic greeting resource mcp.resource(greeting://{name}) def get_greeting(name: str) - str: Get a personalized greeting return fHello, {name}! if __name__ __main__: mcp.run(transportstdio)这段代码注册了一个工具 add 和一个资源 greeting。transportstdio表示用标准输入输出通信这是本地 MCP 最常用的方式。另外两种协议是 sse 和 streamableHttp前者适合远程服务后者适合 HTTP 流式场景。本地调试优先 stdio因为不需要处理端口和网络。代码写完后先本地跑一下确认没报错uv run server.py如果进程挂起等待输入说明 stdio 服务端正常启动了。按 CtrlC 退出。接下来配置 Cherry Studio。打开 Cherry Studio进入 MCP 服务器设置添加一个新的 stdio 类型服务器。参数 args 填写--directory F:\mcp_server run main.py等等这里有个细节原文里写的是 run main.py但我们的文件叫 server.py。所以实际配置应该是--directory F:\mcp_server run server.py如果你把文件命名为 main.py那就用 main.py。关键是--directory后面跟项目绝对路径run后面跟入口文件名。Cherry Studio 会以子进程方式启动这个命令。完整的配置片段如果用 JSON 表示大概是这样{ mcpServers: { demo-server: { command: uv, args: [ --directory, F:\\mcp_server, run, server.py ], env: { TAOTOKEN_API_KEY: 你的Key, TAOTOKEN_BASE_URL: https://taotoken.net/api } } } }注意 Windows 路径里的反斜杠要转义成双反斜杠。如果你在 Cherry Studio 图形界面里填直接填单反斜杠即可。env 字段是可选的如果你的工具不需要调外部 API可以省略。但既然我们讲 TaoToken 统一 Key 接入建议保留后续扩展工具时直接用。配置保存后Cherry Studio 会尝试启动这个 MCP 服务器。如果启动成功你会看到工具列表里出现 add。如果失败检查 uv 是否在 PATH 里以及路径是否正确。这里有个常见坑Cherry Studio 启动子进程时工作目录可能不是 F:\mcp_server所以必须用--directory指定。另外uv run 会自动使用项目里的 .venv不需要手动激活虚拟环境。配置完成后在对话界面选择这个 MCP 服务器然后提问“89 等于几”。模型会识别到 add 工具调用它并返回 17。这就是一次端到端调用。如果模型没有调用工具检查工具描述是否清晰或者换一个明确要求使用工具的提问方式。如果你想让 MCP 服务端内部调用 TaoToken 的模型能力可以在 server.py 里加一个工具用 requests 或 openai SDK 调 https://taotoken.net/api 。三件套配置就是 Base URL、Key、Model ID。这样你的 MCP 工具就具备了模型能力而鉴权统一走 TaoToken。下一节讲验证请求和成功结果的具体观察点以及怎么确认工具真的被调用了。4. 验证请求与成功结果从提问到工具返回配置完成后最关键的一步是验证。很多人配完不知道有没有生效其实有几个明确的观察点。第一Cherry Studio 的 MCP 服务器状态。添加后如果显示绿色或“已连接”说明子进程启动成功。如果显示红色或报错点开日志看具体错误。常见的是command not found: uv说明 uv 没在系统 PATH 里或者 Cherry Studio 没继承环境变量。第二工具列表。连接成功后Cherry Studio 会列出这个 MCP 服务器暴露的工具。你应该能看到 add。如果看不到说明 server.py 里的mcp.tool()没生效检查代码缩进和装饰器。第三实际对话调用。在对话窗口选择该 MCP 服务器提问“89 等于几”。观察返回如果模型直接说 17 但没有工具调用痕迹可能是模型自己算的如果返回里带有工具调用记录比如add(a8, b9)然后返回 17说明 MCP 链路通了。为了更明确地验证可以问一个模型不容易直接算的比如“请用 add 工具计算 12345 67890”。这样模型必须调用工具才能得到准确结果。返回 80235 就说明工具执行成功。如果你想验证资源可以问“greeting://Alice 是什么”。模型会读取 greeting 资源并返回 Hello, Alice!。资源用mcp.resource注册URI 格式是greeting://{name}。如果 MCP 服务端内部要调 TaoToken 的模型验证方式类似加一个工具内部发 HTTP 请求到 https://taotoken.net/api 带上 Key 和 Model ID返回模型输出。然后在对话里触发这个工具看是否返回预期内容。这一步能验证统一 Key 是否配置正确。实测下来stdio 模式的好处是日志直接打在 Cherry Studio 的 MCP 日志里方便排查。如果请求失败先看日志里有没有 Python traceback。常见错误包括依赖没装全、Python 版本不对、路径写错。成功的结果长这样你提问模型决定调用 addCherry Studio 把请求通过 stdio 发给 server.pyserver.py 执行 add 返回结果Cherry Studio 把结果回传给模型模型组织语言回复你。整个过程在本地完成不需要网络除非工具内部调 API。验证通过后你可以继续扩展工具。比如加一个 read_file 工具读本地文件或者加一个 query_db 工具查数据库。每加一个工具重启 MCP 服务器Cherry Studio 会重新加载工具列表。下一节集中讲常见报错和排查方法包括 401、local proxy failed、reading choices、OAuth 这些真实错误。5. 本篇常见错排查401、local proxy failed、reading choices、OAuth配 MCP 服务器时报错信息往往很模糊。这里列几个真实遇到的错误和排查思路。401 Unauthorized这个通常出现在 MCP 服务端内部调 TaoToken API 时。原因就三个Key 没传、Key 错了、Base URL 错了。检查三件套Base URL 必须是 https://taotoken.net/api Key 从 API Keys 页面复制Model ID 在模型列表里选。如果 Key 放在环境变量里确认 Cherry Studio 的 env 字段有没有正确传递。可以在 server.py 里打印 os.environ.get(TAOTOKEN_API_KEY) 的前几位来确认。local proxy failed这个错误一般出现在客户端尝试连接 MCP 服务器时。stdio 模式下Cherry Studio 启动子进程失败就会报这个。排查顺序uv 是否在 PATH、--directory路径是否存在、入口文件是否存在、Python 版本是否匹配。可以在终端手动执行uv --directory F:\mcp_server run server.py看是否报错。如果终端能跑通但 Cherry Studio 报错说明是环境变量或工作目录问题。reading choices 相关错误这个通常出现在调模型 API 时返回格式不符合预期。检查请求体里的 model 字段是否正确以及 API 返回是否被正确解析。如果用的是 OpenAI 兼容 SDK确认 base_url 设置正确。TaoToken 的 API 地址是 https://taotoken.net/api 不要多加路径。OAuth 错误如果你在 MCP 配置里用了需要 OAuth 的远程服务可能会遇到 token 过期或回调失败。本地 stdio 模式一般不需要 OAuth。如果确实需要检查回调地址和 client_id。对于 TaoToken 的 Key 鉴权不涉及 OAuth直接用 API Key 即可。工具没被调用模型不调用工具通常是工具描述不够清晰。mcp.tool()的 docstring 会作为工具描述传给模型所以要写清楚功能。比如 “Add two numbers” 就比 “add” 好。另外提问方式也有影响明确说“请使用 add 工具”能提高调用率。Cherry Studio 里看不到工具先确认 MCP 服务器状态是已连接。如果连接成功但工具列表为空检查 server.py 里是否有mcp.tool()装饰的函数以及mcp.run()是否在__main__里执行。重启 Cherry Studio 和 MCP 服务器再试。uv add 失败网络问题居多。可以设置国内镜像或者重试。确认uv python list里有 3.13uv init时指定的版本和实际安装的一致。stdio 通信无响应如果服务端启动了但客户端收不到响应检查是否有 print 语句干扰了 stdio。stdio 模式下标准输出被用于协议通信任何额外的 print 都可能导致解析失败。调试信息用 stderr 输出比如print(..., filesys.stderr)。排查时记住一个原则先在终端手动跑通再放到 Cherry Studio 里跑。终端能跑通说明代码和依赖没问题问题就在客户端配置。终端跑不通就先解决代码和依赖。如果涉及 Claude Code 或 Codex 的 auth.json 配置三件套依然是 Base URL、Key、Model ID。Base URL 用 https://taotoken.net/api Key 用创建的Model ID 按需选。配置文件和路径要和实际使用的一致。排障完成后回到正常使用。下一节给出 CTA 分流按你的场景选入口。6. 按场景选入口API Keys、模型对话与 Coding Plan走到这里你已经完成了从空目录到可运行 MCP 服务的全流程。接下来按你的实际场景选下一步入口。如果你还在排障或接入阶段需要创建和管理 Key直接去 API Keys 页面https://taotoken.net/api-keys?utm_sourcetaotoken_aicg_blog_endutm_mediumcsdnutm_campaignrewriteutm_content 。接入文档在 https://taotoken.net/doc?utm_sourcetaotoken_aicg_blog_endutm_mediumcsdnutm_campaignrewriteutm_content 里面有不同协议的详细说明。如果你想先验证模型是否可用或者调试模型输出去模型对话页面https://taotoken.net/models?utm_sourcetaotoken_aicg_blog_endutm_mediumcsdnutm_campaignrewriteutm_content 。在这里可以快速测试 Base URL、Key、Model ID 三件套是否配置正确。如果你打算长期做编码类 Agent或者 MCP 工具需要频繁调用模型看 Coding Planhttps://taotoken.net/coding-plan?utm_sourcetaotoken_aicg_blog_endutm_mediumcsdnutm_campaignrewriteutm_content 。这个适合需要稳定额度和统一管理的场景。控制台入口https://taotoken.net/console?utm_sourcetaotoken_aicg_blog_endutm_mediumcsdnutm_campaignrewriteutm_content 。Claude Code 相关的 Anthropic 兼容入口https://taotoken.net/ClaudeCodeAnthropic?utm_sourcetaotoken_aicg_blog_endutm_mediumcsdnutm_campaignrewriteutm_content 。最后给一个实用技巧MCP 服务端的工具会随着你的需求增长。建议把每个工具拆成独立函数docstring 写清楚参数和返回值。这样模型调用时更准确。另外stdio 模式下不要用 print 调试用 stderr。每次改完 server.py重启 MCP 服务器再测试。如果你要把这个 MCP 服务端分享给别人记得把 Key 从代码里去掉用环境变量或配置文件。TaoToken 的统一 Key 让鉴权集中管理换 Key 不用改代码。整个流程跑通后你可以继续加工具比如文件操作、数据库查询、API 调用逐步把你的 MCP 服务器变成真正的工具箱。
