企业官网建设流程全解析

1. 环境准备：FastMCP 开发 MCP 服务到底需要装什么

如果你刚接触 MCP（Model Context Protocol），可以把它理解成一套“让大模型调用外部工具”的通用插座标准。而 FastMCP 就是 Python 世界里把这套标准封装好的工具箱，你写几个带装饰器的函数，它就能帮你生成一个符合协议的服务端。阿里云百炼则提供了托管这些 MCP 服务的运行环境，让你开发的工具能被智能体直接引用。

这套流程适合谁？适合已经会写 Python 函数、想把自己的业务逻辑暴露给大模型调用的开发者。你不需要从零实现协议通信，只要把环境搭对，剩下的就是写函数。

我这次的目标很明确：在本地用 FastMCP 跑通一个 MCP 服务，验证工具能被正常调用，然后为后续部署到阿里云百炼函数计算做准备。环境准备阶段最容易卡住的地方不是代码，而是 Python 版本、UVX 工具链和依赖之间的配合。下面按我实际操作的顺序，把每一步的命令和验证方式都列出来。

先说结论：你需要三样东西——Python 3.12、uv 包管理器、FastMCP 库。Node.js 不是必须的，但如果你后续要用 npx 方式启动某些社区 MCP 服务，装一个也无妨。阿里云函数计算目前对 Python 运行时最高支持到 3.12，所以本地开发环境直接对齐这个版本，能避免部署时出现解释器不兼容的问题。

环境准备的核心检索词是“FastMCP 环境配置”和“UVX 工具链安装”，这两个词贯穿整个第一章。你跟着做的时候，建议每装完一个组件就验证一次版本号，不要等全部装完再排查，否则出错时很难定位是哪一步的问题。

2. TaoToken 前置：统一 Key 与 API 通道的接入方式

在写 MCP 工具函数之前，有一个容易被忽略但很关键的前置动作：模型侧的接入通道。你的 MCP 服务本身不直接调用大模型，但后续在百炼智能体里测试工具调用时，智能体需要访问模型。如果你在本地调试阶段就想模拟“模型选择工具”的链路，就需要一个稳定的 API 入口。

TaoToken 在这里的作用是提供统一的 Key 和 API 通道。你可以把它理解成一个聚合入口，用同一个 Key 就能访问多种模型，不用为每个模型单独申请和切换配置。对于 MCP 开发来说，这意味着你在本地测试工具调用逻辑时，可以快速切换不同模型来验证兼容性。

接入方式很简单，先拿到 API Key，然后配置 Base URL。TaoToken 的 API 地址是https://taotoken.net/api，这个地址不加任何查询参数，直接作为 OpenAI 兼容接口的基础路径使用。如果你用的是 OpenAI SDK 或兼容的客户端，把base_url指向这个地址，api_key填你申请到的 Key 即可。

这里要提醒一点：TaoToken 不是让你绕过什么限制，它就是一个正常的 API 服务入口。你在百炼里部署 MCP 服务时，百炼本身会处理模型调用，TaoToken 更多是在本地开发和调试阶段帮你统一管理 Key，避免在代码里硬编码多个平台的密钥。

配置的时候建议用环境变量管理，不要写死在代码里。后面部署到函数计算时，百炼的env字段可以直接注入这些变量，代码不用改。具体来说，你需要在项目根目录建一个.env文件，把TAOTOKEN_API_KEY和TAOTOKEN_BASE_URL写进去，然后用python-dotenv加载。这样本地跑和线上跑用的是同一套读取逻辑。

如果你还没有 Key，可以到 TaoToken 的 API Keys 页面创建一个。创建时注意权限范围，开发阶段给最小必要权限就行。拿到 Key 之后先别急着写业务代码，用一条最简单的请求验证通道是否通，确认返回正常再继续。

3. 可复制配置：Python 3.12 + uv + FastMCP 完整安装清单

这一节是整篇的核心操作区，所有命令都可以直接复制执行。我按“先装 Python，再装 uv，最后建项目装 FastMCP”的顺序来，每一步都有验证命令。

3.1 安装 Python 3.12

Windows 用户打开 PowerShell，用 winget 安装最省事：

winget install Python.Python.3.12

如果你习惯手动下载，去 Python 官网找 3.12.10 的 64 位安装包，安装时勾选“Add Python to PATH”。装完验证：

python --version

预期输出Python 3.12.10。如果显示的是其他版本，说明 PATH 里有多个 Python，需要用py -3.12 --version明确指定。

macOS 用户可以用 Homebrew：

brew install python@3.12

Linux 用户根据发行版用 apt 或 yum 安装，注意确认版本号。

3.2 安装 uv 工具链

uv 是 Rust 写的 Python 包管理器，速度比 pip 快很多，而且能管理虚拟环境和依赖锁定。Windows 上用官方脚本安装：

powershell -ExecutionPolicy ByPass -c "irm https://astral.sh/uv/install.ps1 | iex"

macOS 和 Linux 用：

curl -LsSf https://astral.sh/uv/install.sh | sh

装完关闭当前终端，重新打开一个，验证：

uv --version

预期输出类似uv 0.5.x。如果提示命令找不到，检查安装脚本输出的路径是否加到了 PATH。

3.3 创建项目并安装 FastMCP

先建一个工作目录，比如D:\art\fastmcp，然后进入该目录执行：

uv init 01_env_test cd 01_env_test

uv init会生成pyproject.toml和基础目录结构。接着创建虚拟环境：

uv venv

激活虚拟环境，Windows 用：

.venv\Scripts\activate

macOS/Linux 用：

source .venv/bin/activate

激活后命令行前面会出现(.venv)标识。然后安装 FastMCP：

uv add fastmcp

这条命令会把 FastMCP 及其依赖写入pyproject.toml并安装到虚拟环境。验证安装：

uv run python -c "from fastmcp import FastMCP; print('FastMCP imported')"

如果输出FastMCP imported，说明环境通了。

3.4 项目配置文件参考

pyproject.toml里应该能看到类似这样的依赖声明：

[project] name = "01-env-test" version = "0.1.0" requires-python = ">=3.12" dependencies = [ "fastmcp>=2.0.0", ]

如果你需要额外装python-dotenv和pydantic，继续执行：

uv add python-dotenv pydantic

这两个库在后面管理环境变量和参数校验时会用到。装完后pyproject.toml的dependencies列表会自动更新。

3.5 环境变量文件模板

在项目根目录创建.env文件，内容如下：

TAOTOKEN_API_KEY=your_taotoken_api_key_here TAOTOKEN_BASE_URL=https://taotoken.net/api MCP_SERVICE_NAME=my_bailian_mcp MCP_SERVICE_PORT=8000 TIMEOUT=30

注意.env不要提交到 Git，在.gitignore里加上这一行。代码里用load_dotenv()加载后，通过os.getenv()读取。

4. 验证请求：跑通第一个 FastMCP 服务并确认工具可调用

环境装好之后，必须用一个最小可运行的服务来验证整条链路。这一步不做，后面写复杂工具时出了问题你分不清是环境问题还是代码问题。

4.1 写一个最小服务端

在项目目录下新建my_server.py：

from fastmcp import FastMCP mcp = FastMCP("My MCP Server") @mcp.tool() def greet(name: str) -> str: """根据名字返回问候语""" return f"Hello, {name}!" if __name__ == "__main__": mcp.run()

这段代码定义了一个名为greet的工具，接收字符串参数，返回拼接后的问候语。@mcp.tool()装饰器负责把函数注册到 MCP 服务实例。

4.2 启动服务端

在终端执行：

uv run my_server.py

如果一切正常，你会看到服务启动日志，默认使用 stdio 传输协议。stdio 模式下服务通过标准输入输出通信，适合本地调试。

4.3 写一个客户端调用

另开一个终端窗口，新建my_client.py：

import asyncio from fastmcp import Client client = Client("my_server.py") async def call_tool(name: str): async with client: result = await client.call_tool("greet", {"name": name}) print(result) asyncio.run(call_tool("TaoToken"))

客户端通过文件路径连接到服务端，然后调用greet工具并传入参数。执行：

uv run my_client.py

预期输出包含Hello, TaoToken!。看到这个结果，说明 FastMCP 的安装、服务注册、工具调用整条链路都是通的。

4.4 验证模型侧通道

如果你在.env里配了 TaoToken 的 Key，可以用一段简单脚本验证 API 通道：

import os from openai import OpenAI from dotenv import load_dotenv load_dotenv() client = OpenAI( api_key=os.getenv("TAOTOKEN_API_KEY"), base_url=os.getenv("TAOTOKEN_BASE_URL") ) response = client.chat.completions.create( model="gpt-4o-mini", messages=[{"role": "user", "content": "回复OK两个字"}] ) print(response.choices[0].message.content)

这段代码需要先uv add openai。如果返回正常内容，说明模型侧通道可用，后续在百炼里测试智能体调用 MCP 工具时，模型选择逻辑就有了本地验证基础。

4.5 检查服务信息

FastMCP 提供了命令行工具查看版本和已注册的工具列表：

uv run fastmcp version

这个命令会输出 FastMCP 的版本号。你还可以在代码里加一个资源端点，返回服务的基础信息，方便后续在百炼控制台确认服务状态。

5. 本篇常见错排查：401、local proxy failed、reading choices 怎么处理

环境准备阶段报错集中在几个固定位置，下面按真实遇到的错误信息来对照排查。

5.1 401 Unauthorized

这个错误通常出现在调用模型 API 时。原因有三个：Key 没填、Key 填错、Key 对应的权限不足。先检查.env文件里的TAOTOKEN_API_KEY是否和申请到的一致，注意不要有多余空格。然后确认base_url写的是https://taotoken.net/api，不要在后面加/v1或其他路径，除非文档明确要求。

如果 Key 确认无误还是 401，到 TaoToken 控制台检查这个 Key 是否被禁用或过期。开发阶段建议新建一个 Key 专门用于测试，避免和线上 Key 混用。

5.2 local proxy failed

这个报错一般出现在客户端连接服务端时。如果你用的是 stdio 传输，客户端通过文件路径启动服务端进程，路径写错或 Python 解释器找不到就会报这个错。检查Client("my_server.py")里的路径是否相对于当前工作目录正确。建议用绝对路径排除歧义。

另一个原因是虚拟环境没激活，uv run找不到依赖。确认终端前面有(.venv)标识，或者直接用uv run前缀执行命令，让 uv 自动处理环境。

5.3 reading choices 相关错误

这个错误通常出现在解析模型返回结果时。如果你用的是 OpenAI 兼容接口，返回结构里应该有choices字段。报错说明返回体不符合预期，可能是base_url配错导致请求打到了非兼容接口，或者模型名称写错导致服务端返回了错误信息。

排查方法：先把原始返回打印出来，看response对象的完整结构。如果choices为空，检查model参数是否是该通道支持的模型 ID。TaoToken 的模型列表可以在模型对话页面查看，确认你用的模型名在支持范围内。

5.4 uv 安装后命令找不到

Windows 上安装 uv 后需要重开终端，因为 PATH 更新不会自动生效到已打开的会话。如果重开后还是找不到，手动把 uv 安装路径加到系统环境变量。安装脚本最后会输出安装位置，通常在%USERPROFILE%\.local\bin或类似目录。

5.5 FastMCP 导入失败

ModuleNotFoundError: No module named 'fastmcp'说明依赖没装到当前虚拟环境。确认你执行uv add fastmcp时虚拟环境是激活状态，或者用uv run python -c "import fastmcp"让 uv 自动解析环境。如果pyproject.toml里有 fastmcp 但导入失败，执行uv sync重新同步依赖。

5.6 Python 版本不匹配

如果uv init时提示 Python 版本不符合要求，检查pyproject.toml里的requires-python字段。默认可能是>=3.8，但 FastMCP 新版本可能要求 3.10 以上。手动改成>=3.12后执行uv sync。另外确认系统里python --version输出的是 3.12，如果指向了旧版本，用uv python pin 3.12固定项目使用的解释器。

6. 语义一致 CTA：环境就绪后下一步做什么

环境准备做完，你手上应该有一个能跑通的 FastMCP 服务、一个验证过的客户端调用、以及一条可用的模型 API 通道。接下来就是在这个基础上写实际的工具函数，然后打包部署到阿里云百炼。

如果你在配置 Key 或调试 API 通道时遇到问题，可以直接到 TaoToken 的 API Keys 页面重新生成一个 Key 试试，有时候是复制粘贴时带了不可见字符。接入文档里有各语言 SDK 的配置示例，对照检查base_url和认证头的写法。

想先验证模型返回是否正常，可以用模型对话页面发一条测试消息，确认通道本身没问题。如果你打算长期做 MCP 开发和 Agent 集成，Coding Plan 提供了更稳定的调用额度，适合反复调试工具调用逻辑的场景。

环境这一步看起来琐碎，但它是后面所有工作的地基。我建议你把my_server.py和my_client.py这两个最小示例保留在项目里，后面写复杂工具时如果怀疑环境出了问题，先跑一遍这两个文件，能快速排除是环境退化还是新代码的 bug。