从0-1使用Fastmcp开发一个MCP服务，并部署到阿里云百炼【1.环境准备】

1. 环境准备FastMCP 开发 MCP 服务到底需要装什么如果你刚接触 MCPModel 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.12Windows 用户打开 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 用户可以用 Homebrewbrew install python3.12Linux 用户根据发行版用 apt 或 yum 安装注意确认版本号。3.2 安装 uv 工具链uv 是 Rust 写的 Python 包管理器速度比 pip 快很多而且能管理虚拟环境和依赖锁定。Windows 上用官方脚本安装powershell -ExecutionPolicy ByPass -c irm https://astral.sh/uv/install.ps1 | iexmacOS 和 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_testuv init会生成pyproject.toml和基础目录结构。接着创建虚拟环境uv venv激活虚拟环境Windows 用.venv\Scripts\activatemacOS/Linux 用source .venv/bin/activate激活后命令行前面会出现(.venv)标识。然后安装 FastMCPuv 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 [ fastmcp2.0.0, ]如果你需要额外装python-dotenv和pydantic继续执行uv add python-dotenv pydantic这两个库在后面管理环境变量和参数校验时会用到。装完后pyproject.toml的dependencies列表会自动更新。3.5 环境变量文件模板在项目根目录创建.env文件内容如下TAOTOKEN_API_KEYyour_taotoken_api_key_here TAOTOKEN_BASE_URLhttps://taotoken.net/api MCP_SERVICE_NAMEmy_bailian_mcp MCP_SERVICE_PORT8000 TIMEOUT30注意.env不要提交到 Git在.gitignore里加上这一行。代码里用load_dotenv()加载后通过os.getenv()读取。4. 验证请求跑通第一个 FastMCP 服务并确认工具可调用环境装好之后必须用一个最小可运行的服务来验证整条链路。这一步不做后面写复杂工具时出了问题你分不清是环境问题还是代码问题。4.1 写一个最小服务端在项目目录下新建my_server.pyfrom fastmcp import FastMCP mcp FastMCP(My MCP Server) mcp.tool() def greet(name: str) - str: 根据名字返回问候语 return fHello, {name}! if __name__ __main__: mcp.run()这段代码定义了一个名为greet的工具接收字符串参数返回拼接后的问候语。mcp.tool()装饰器负责把函数注册到 MCP 服务实例。4.2 启动服务端在终端执行uv run my_server.py如果一切正常你会看到服务启动日志默认使用 stdio 传输协议。stdio 模式下服务通过标准输入输出通信适合本地调试。4.3 写一个客户端调用另开一个终端窗口新建my_client.pyimport 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_keyos.getenv(TAOTOKEN_API_KEY), base_urlos.getenv(TAOTOKEN_BASE_URL) ) response client.chat.completions.create( modelgpt-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。