企业官网建设流程全解析

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 用户打开 PowerShell，macOS/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_server：

mkdir F:\mcp_server cd F:\mcp_server uv init . -p 3.13

uv 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_source=taotoken_aicg_blog_end&utm_medium=csdn&utm_campaign=rewrite&utm_content= 。注册后进入控制台创建 API Key，控制台地址是 https://taotoken.net/console?utm_source=taotoken_aicg_blog_end&utm_medium=csdn&utm_campaign=rewrite&utm_content= 。Key 的创建入口在 API Keys 页面：https://taotoken.net/api-keys?utm_source=taotoken_aicg_blog_end&utm_medium=csdn&utm_campaign=rewrite&utm_content= 。

拿到 Key 之后，API 的基础地址是 https://taotoken.net/api ，注意这个地址不加 UTM 参数，直接用于代码里的 base_url。模型对话调试可以用 https://taotoken.net/models?utm_source=taotoken_aicg_blog_end&utm_medium=csdn&utm_campaign=rewrite&utm_content= 来验证模型是否可用。如果你打算长期做编码类 Agent，可以看 Coding Plan：https://taotoken.net/coding-plan?utm_source=taotoken_aicg_blog_end&utm_medium=csdn&utm_campaign=rewrite&utm_content= 。

接入文档在 https://taotoken.net/doc?utm_source=taotoken_aicg_blog_end&utm_medium=csdn&utm_campaign=rewrite&utm_content= ，里面会说明不同协议的调用方式。Claude Code 相关的 Anthropic 兼容入口在 https://taotoken.net/ClaudeCodeAnthropic?utm_source=taotoken_aicg_blog_end&utm_medium=csdn&utm_campaign=rewrite&utm_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_URL=https://taotoken.net/api

macOS/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 f"Hello, {name}!" if __name__ == '__main__': mcp.run(transport="stdio")

这段代码注册了一个工具 add 和一个资源 greeting。transport="stdio"表示用标准输入输出通信，这是本地 MCP 最常用的方式。另外两种协议是 sse 和 streamableHttp，前者适合远程服务，后者适合 HTTP 流式场景。本地调试优先 stdio，因为不需要处理端口和网络。

代码写完后，先本地跑一下确认没报错：

uv run server.py

如果进程挂起等待输入，说明 stdio 服务端正常启动了。按 Ctrl+C 退出。

接下来配置 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 服务器，然后提问“8+9 等于几”。模型会识别到 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 服务器，提问“8+9 等于几”。观察返回：如果模型直接说 17 但没有工具调用痕迹，可能是模型自己算的；如果返回里带有工具调用记录，比如add(a=8, b=9)然后返回 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 版本不对、路径写错。

成功的结果长这样：你提问，模型决定调用 add，Cherry Studio 把请求通过 stdio 发给 server.py，server.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.13，uv init时指定的版本和实际安装的一致。

stdio 通信无响应：如果服务端启动了但客户端收不到响应，检查是否有 print 语句干扰了 stdio。stdio 模式下，标准输出被用于协议通信，任何额外的 print 都可能导致解析失败。调试信息用 stderr 输出，比如print(..., file=sys.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_source=taotoken_aicg_blog_end&utm_medium=csdn&utm_campaign=rewrite&utm_content= 。接入文档在 https://taotoken.net/doc?utm_source=taotoken_aicg_blog_end&utm_medium=csdn&utm_campaign=rewrite&utm_content= ，里面有不同协议的详细说明。

如果你想先验证模型是否可用，或者调试模型输出，去模型对话页面：https://taotoken.net/models?utm_source=taotoken_aicg_blog_end&utm_medium=csdn&utm_campaign=rewrite&utm_content= 。在这里可以快速测试 Base URL、Key、Model ID 三件套是否配置正确。

如果你打算长期做编码类 Agent，或者 MCP 工具需要频繁调用模型，看 Coding Plan：https://taotoken.net/coding-plan?utm_source=taotoken_aicg_blog_end&utm_medium=csdn&utm_campaign=rewrite&utm_content= 。这个适合需要稳定额度和统一管理的场景。

控制台入口：https://taotoken.net/console?utm_source=taotoken_aicg_blog_end&utm_medium=csdn&utm_campaign=rewrite&utm_content= 。Claude Code 相关的 Anthropic 兼容入口：https://taotoken.net/ClaudeCodeAnthropic?utm_source=taotoken_aicg_blog_end&utm_medium=csdn&utm_campaign=rewrite&utm_content= 。

最后给一个实用技巧：MCP 服务端的工具会随着你的需求增长。建议把每个工具拆成独立函数，docstring 写清楚参数和返回值。这样模型调用时更准确。另外，stdio 模式下不要用 print 调试，用 stderr。每次改完 server.py，重启 MCP 服务器再测试。

如果你要把这个 MCP 服务端分享给别人，记得把 Key 从代码里去掉，用环境变量或配置文件。TaoToken 的统一 Key 让鉴权集中管理，换 Key 不用改代码。整个流程跑通后，你可以继续加工具，比如文件操作、数据库查询、API 调用，逐步把你的 MCP 服务器变成真正的工具箱。