企业官网建设流程全解析

1. 从本地脚本到可发布服务：MCP 开发链路到底卡在哪

MCP（Model Context Protocol）说白了就是给 AI 助手接一台「能调外部工具、能读外部数据」的终端。你写一个独立进程，把函数注册成工具，Claude Code 这类客户端在需要时就会去调它。听起来简单，但真正从零走到「发布出去别人能用」，中间会卡在几个很具体的地方：工具注册完客户端连不上、鉴权 Key 到处散落、401 报错不知道是 Key 问题还是 Base URL 问题、本地 stdio 跑通了换成 HTTP 就挂。

这篇就按「本地开发 → 接入验证 → 发布」这条完整链路走一遍。技术栈用 Python + FastMCP（官方高层 API，最省事），鉴权统一走 TaoToken 的 Key 和 API 通道，客户端侧用 Claude Code 的 settings 配置接入。适合谁看：已经会写 Python 函数、想把项目里的查询逻辑暴露给 AI 调用、但还没跑通完整链路的开发者。如果你只是想了解 MCP 是什么，前面这段已经够了；想真正跑起来，往下跟做。

先说清楚一个关键认知，很多人第一步就理解偏了：MCP Server 是一个独立运行的进程，不是你项目里的一段函数。它通过 stdin/stdout（本地）或 HTTP（远程）和 AI 客户端通信。所以你的工具逻辑可以复用项目里已有的代码，但入口必须是一个能被客户端拉起的独立程序。这个认知决定了后面所有配置的写法。

我试过把工具直接写在主项目里让客户端 import，结果就是客户端根本不知道怎么启动它。正确做法是单独建一个 server 文件，里面用装饰器注册工具，工具内部再去调你项目里的执行逻辑。这样职责清晰：server 负责协议和注册，项目代码负责业务。

整条链路我拆成六段：先讲清楚要解决的原问题和场景，再讲 TaoToken 的前置准备（统一 Key 和 API 通道），然后给可复制的 FastMCP 服务端配置和 Claude Code 侧 settings 片段，接着做一次真实的验证请求看成功结果，再对照 401 这类常见报错排查，最后给接入文档和 API Keys 的入口。每一段都有可复制的代码或配置，不玩虚的。

2. TaoToken 前置：统一 Key 与 API 通道怎么准备

在写 server 之前，先把鉴权这条线理清楚。MCP 工具里如果要调大模型能力（比如工具内部需要做一次语义判断、或者你的 server 本身要转发请求），就需要一个稳定的 API 通道和一把统一的 Key。散落各处的 Key 是后面 401 报错的最大来源，所以这一步值得单独做。

TaoToken 在这里的角色是提供统一的 API 通道和 Key 管理。你注册后在控制台创建一把 Key，所有需要鉴权的地方都用这一把，Base URL 统一指向https://taotoken.net/api。注意 API 地址不带任何查询参数，就是干净的https://taotoken.net/api，这点在配置里很容易写错。

具体操作路径：先到官网 https://taotoken.net/?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_content=console&utm_campaign=rewrite 创建 API Key。创建完先别关页面，Key 只显示一次，复制下来存到环境变量里，别硬编码进代码。

创建 Key 的入口在 https://taotoken.net/api-keys?utm_source=taotoken_aicg_blog_end&utm_content=api-keys&utm_campaign=rewrite ，进去后点新建，起个能认出来的名字，比如mcp-dev。生成后立刻复制，格式通常是一串以特定前缀开头的字符串。

拿到 Key 之后，本地先验证一下通道是通的。用 curl 测一次最直接：

export TAOTOKEN_API_KEY="你的Key" curl https://taotoken.net/api/v1/models \ -H "Authorization: Bearer $TAOTOKEN_API_KEY"

如果返回模型列表的 JSON，说明 Key 和 Base URL 都对。如果返回 401，先检查 Key 有没有复制全、有没有多余空格。这一步单独验证的价值在于：把「通道问题」和「MCP 配置问题」隔离开，后面出问题能快速定位是哪一层。

关于模型 ID，TaoToken 的模型对话页面 https://taotoken.net/models?utm_source=taotoken_aicg_blog_end&utm_content=models&utm_campaign=rewrite 能看到当前可用的模型列表，配置里填的 Model ID 要和这里一致。如果你后面要做长期编码或 Agent 类任务，可以了解下 Coding Plan https://taotoken.net/coding-plan?utm_source=taotoken_aicg_blog_end&utm_content=coding-plan&utm_campaign=rewrite ，它更适合高频调用的场景。

这里有个设计原则要提前说：MCP 工具里的身份信息（比如当前用户是谁）不要硬编码，也不该让 AI 每次手动传。正确做法是从环境变量注入，配置在客户端的 settings 里。这样工具函数签名干净，AI 调用时不用关心「用户 ID 是多少」这种它根本不知道的信息。这个原则在下一节的配置里会具体体现。

3. 可复制配置：FastMCP 服务端 + Claude Code settings

这一节是全文的核心，给两份可直接复制的配置：一份是 FastMCP 服务端，一份是 Claude Code 侧的 settings。先装依赖：

pip install mcp python -c "from mcp.server.fastmcp import FastMCP; print('OK')"

需要 Python 3.10+。装完打印 OK 就说明环境没问题。

先写一个最小可用的 server，文件叫hello_mcp.py：

from mcp.server.fastmcp import FastMCP mcp = FastMCP("hello") @mcp.tool() def add(a: int, b: int) -> int: """两个数相加""" return a + b if __name__ == "__main__": mcp.run()

逐块看：FastMCP("hello")创建 server，名字只是标识；@mcp.tool()把函数注册成 AI 可调用的工具，函数名add就是工具名，参数类型注解int自动变成参数说明，docstring 自动变成用途说明——不用额外写 schema，这是 FastMCP 最省事的地方；mcp.run()默认走 stdio，等待客户端连接。

现在把它接到真实项目场景。假设你项目里有个查询逻辑，要暴露成工具，同时身份从环境变量注入：

import asyncio import os from mcp.server.fastmcp import FastMCP mcp = FastMCP("qxl-tools") def _user_id() -> int: """当前用户 ID，从配置注入，无需 AI 手动传""" return int(os.environ.get("USER_ID", "0")) @mcp.tool() def get_family_info() -> str: """查询当前用户的家庭成员概况。""" from app.tools.registry import execute_tool return asyncio.run(execute_tool("get_family_info", {}, _user_id())) @mcp.tool() def get_child_courses(cid: int) -> str: """查询当前用户某孩子的已报名课程。""" from app.tools.registry import execute_tool return asyncio.run(execute_tool("get_child_courses", {"cid": cid}, _user_id())) if __name__ == "__main__": mcp.run()

注意user_id不作为工具参数，它从环境变量USER_ID注入；只有cid这种需要 AI 现场判断的参数才保留。这是 MCP 工具设计里最容易被忽略的点：身份该由配置提供，不该让 AI 猜。

接下来是 Claude Code 侧的配置。在项目根目录建.mcp.json：

{ "mcpServers": { "qxl-tools": { "command": "python", "args": ["qxl_mcp_server.py"], "env": { "USER_ID": "7", "TAOTOKEN_API_KEY": "你的Key", "TAOTOKEN_BASE_URL": "https://taotoken.net/api" } } } }

这份 JSON 里三件套齐全：command+args告诉 Claude Code 怎么启动 server；env注入身份和鉴权信息。Base URL 是https://taotoken.net/api，Key 用你前面创建的那把，Model ID 如果工具内部要调模型，从模型列表页取。

如果你用的是 Claude Code 的 settings 文件（比如~/.claude/settings.json或项目级.claude/settings.json），把 MCP 相关配置写进去，结构类似：

{ "mcpServers": { "qxl-tools": { "command": "python", "args": ["qxl_mcp_server.py"], "env": { "USER_ID": "7", "TAOTOKEN_API_KEY": "你的Key", "TAOTOKEN_BASE_URL": "https://taotoken.net/api" } } } }

如果你用 CC Switch 或 Cline 这类工具管理多个 MCP，配置项同样是三件套：Base URL 填https://taotoken.net/api，Key 填你的 TaoToken Key，Model ID 填模型列表里的 ID。三者缺一不可，少任何一个都会在调用时报错。

配置写完，重启 Claude Code。它启动时会自动拉起python qxl_mcp_server.py这个进程，通过 stdio 通信。改代码后必须重启，stdio 进程不会热更新。

4. 验证请求：一次工具调用成功与结果对照

配置完不验证等于没配。这一节做一次真实的工具调用，看成功结果长什么样，同时把 401 报错的对照动作也做了。

先单独验证 server 本身能不能跑起来。用官方 Inspector：

npx @modelcontextprotocol/inspector python qxl_mcp_server.py

浏览器打开它给的地址，你能看到 server 里注册了哪些工具、每个工具的参数和描述。手动点一个工具、填参数、看返回结果。这一步不需要 Claude Code，能单独验证 MCP 逻辑对不对，是开发期最常用的调试手段。

Inspector 里调add工具，参数a=1, b=2，返回3，说明工具注册和调用链路通了。调get_family_info，如果返回了家庭成员数据，说明环境变量注入和项目逻辑对接都正常。

然后回到 Claude Code，在对话里问「帮我查一下家庭成员」。它应该会自动识别并调用get_family_info工具，返回结果。成功的标志是：对话里出现工具调用记录，且返回内容是你项目里的真实数据。

如果工具内部要调 TaoToken 的 API，验证请求可以这样测：

curl https://taotoken.net/api/v1/chat/completions \ -H "Authorization: Bearer $TAOTOKEN_API_KEY" \ -H "Content-Type: application/json" \ -d '{ "model": "你的ModelID", "messages": [{"role": "user", "content": "ping"}] }'

返回带choices字段的 JSON 就说明通道正常。这一步和 MCP 分开验证，能快速区分是通道问题还是 MCP 配置问题。

成功结果的对照：Inspector 里工具列表能看到你注册的所有工具，参数说明和 docstring 一致；Claude Code 对话里工具被正确调用，返回真实数据；curl 返回choices数组。三者都通过，链路就算打通了。

这里提醒一个细节：stdio 传输下，别在工具函数里用print调试。stdio 通道被 MCP 协议占用，print会污染协议导致客户端解析失败。要调试用sys.stderr.write或者直接用 Inspector。

5. 常见报错排查：401、local proxy failed、reading choices

这一节对照几个真实报错，给出定位思路。这些错我都踩过，按顺序排查能省不少时间。

401 Unauthorized：最常见。先确认 Key 有没有复制全、有没有多余空格或换行。然后确认 Base URL 是不是https://taotoken.net/api，注意不要多加/v1之外的路径，也不要在末尾加斜杠。如果 Key 和 URL 都对还报 401，去控制台确认这把 Key 有没有被禁用或额度耗尽。排查顺序：Key 格式 → Base URL → 控制台状态。

local proxy failed / connection refused：通常是客户端拉不起 server 进程。检查.mcp.json里的command和args路径对不对，python是不是在 PATH 里。如果用了虚拟环境，command要指向虚拟环境里的 python 绝对路径。另一个常见原因是 server 启动就崩了，手动在终端跑一遍python qxl_mcp_server.py，看有没有 import 错误。

reading choices 相关报错：一般是 API 返回结构不符合预期。检查 Model ID 是否和模型列表页一致，请求体格式是否正确。如果返回的是错误 JSON 而不是choices，先看错误信息里的message字段，通常是模型名写错或参数不合法。

OAuth 相关报错：如果你在配置里误开了 OAuth 认证但没配完整，会报这个。本地开发用配置注入（环境变量）就够了，不需要 OAuth。把配置里多余的认证字段去掉。

工具调用返回空或超时：检查工具函数内部逻辑，尤其是asyncio.run()的用法。FastMCP 的 tool 函数是同步的，如果你要调异步逻辑，用asyncio.run()包一层。但注意asyncio.run()不能在已有事件循环里调用，如果报「event loop is already running」，说明调用栈里已经有循环了，需要换方式。

改了代码不生效：stdio 进程是启动时拉起的，改代码不会热更新。重启 Claude Code，或者用 Inspector 重新拉起。

排查的通用思路：先用 Inspector 单独验证 server，再用 curl 单独验证 API 通道，最后才看客户端集成。把三层隔离开，问题定位会快很多。接入相关的文档在 https://taotoken.net/doc?utm_source=taotoken_aicg_blog_end&utm_content=doc&utm_campaign=rewrite ，Key 管理在 https://taotoken.net/api-keys?utm_source=taotoken_aicg_blog_end&utm_content=api-keys&utm_campaign=rewrite 。

6. 发布与接入：从本地跑通到别人能用

本地跑通只是第一步，发布出去才算完整链路。发布方式有三种，按场景选。

方式一，pip 包。适合给 Python 用户。建包结构，在pyproject.toml里声明入口点：

[project.scripts] qxl-mcp = "my_mcp.server:main"

用户pip install后，.mcp.json里command直接写qxl-mcp就行。

方式二，可执行文件。适合非 Python 用户。用 PyInstaller 打包：

pip install pyinstaller pyinstaller --onefile qxl_mcp_server.py

生成dist/qxl_mcp_server，用户配置command指向它，无需装 Python。

方式三，托管到 MCP 目录。适合最大化传播。以 Smithery 为例，Python server 要改成 Streamable HTTP 传输，并用 Docker 运行。server 末尾改成：

if __name__ == "__main__": mcp.run(transport="streamable-http", host="0.0.0.0", port=8080)

写 Dockerfile：

FROM python:3.12-slim WORKDIR /app COPY requirements.txt . RUN pip install --no-cache-dir -r requirements.txt COPY . . EXPOSE 8080 CMD ["python", "qxl_mcp_server.py"]

写smithery.yaml：

runtime: "container" startCommand: type: "http" configSchema: type: "object" properties: USER_ID: type: "string" description: "用户 ID" required: ["USER_ID"] build: dockerfile: "Dockerfile" dockerBuildPath: "."

然后推 GitHub，到目录网站一键部署。部署后别人能搜到并一键安装。

发布后，接入方需要的信息就是三件套：Base URLhttps://taotoken.net/api、Key（在控制台创建）、Model ID（在模型列表页取）。把这三个给到使用者，他们就能在自己的客户端里配置。

如果你要做长期编码或 Agent 类任务，Coding Plan https://taotoken.net/coding-plan?utm_source=taotoken_aicg_blog_end&utm_content=coding-plan&utm_campaign=rewrite 更适合高频调用场景。模型对话验证在 https://taotoken.net/models?utm_source=taotoken_aicg_blog_end&utm_content=models&utm_campaign=rewrite 。接入文档在 https://taotoken.net/doc?utm_source=taotoken_aicg_blog_end&utm_content=doc&utm_campaign=rewrite 。

最后给一个实用技巧：把.mcp.json里的 Key 用环境变量引用而不是硬编码，比如"TAOTOKEN_API_KEY": "${TAOTOKEN_API_KEY}"，这样配置文件可以进版本库而不会泄露 Key。本地开发时在 shell 里 export，CI 或部署时用密钥管理注入。这个习惯能避免很多「Key 不小心提交了」的麻烦。