企业官网建设流程全解析

1. 为什么你的 LLM 工具链总在“重复造轮子”

如果你最近在折腾 Claude Desktop、Cursor 或者自己写的 Agent，大概率会遇到一个很烦的问题：每接一个外部数据源，就要重写一遍适配代码。今天接本地文件系统，明天接数据库，后天接公司内部 API，每个工具的调用格式、鉴权方式、返回结构都不一样。LLM 本身很聪明，但它被这些五花八门的接口卡住了脖子。

MCP（Model Context Protocol，模型上下文协议）就是 Anthropic 针对这个问题给出的开放规范。它做的事情，说白了就是给 LLM 应用和外部上下文之间定一套统一的“插座标准”。你可以把它理解成 AI 世界的 USB-C：不管你是接文件、接数据库、接远程 API，只要双方都遵守 MCP，就能即插即用。MCP 采用客户端-服务器架构，主机应用（比如 Claude Desktop、IDE、自研 Agent）作为客户端，通过一对一连接挂载多个 MCP 服务器，服务器再以资源、工具、提示三种原语向 LLM 暴露能力。

这篇文章面向的是需要让 LLM 工具链稳定接入外部上下文的开发者。我会从 MCP 的客户端-服务器骨架讲起，给出可复制的config.toml/settings.json配置示例，再结合 TaoToken 统一 Key 的接入方式，最后用连通性验证动作帮你判断 MCP 服务端与客户端到底有没有握手成功。整套流程走下来，你应该能搭出一个最小可用的 MCP 接入骨架。

2. MCP 客户端-服务器架构拆解与 TaoToken 前置准备

2.1 四个角色，一张图装进脑子

MCP 的架构不复杂，但角色边界要分清，否则配置时很容易把该填服务端的地方填成客户端。

关键点在于：客户端和服务器是一对一关系。一个主机可以同时挂多个客户端，每个客户端连一个服务器。这样设计的好处是隔离性强，某个服务器挂了不会拖垮整个主机。

2.2 三种原语：资源、工具、提示

服务器向 LLM 暴露能力，靠的是三种原语，别搞混：

• 资源（Resources）：类似 REST 的 GET，只读，用来把数据加载进上下文，不应该产生副作用。
• 工具（Tools）：类似 POST，会执行计算或产生副作用，比如写文件、发请求。
• 提示（Prompts）：可复用的交互模板，帮 LLM 更高效地和服务器对话。

我试过在同一个服务器里混用这三种原语，结果调试时发现工具被误当成资源调用，排查了半天。建议你在命名上就区分开，比如read_*给资源，do_*给工具。

2.3 TaoToken 统一 Key 的前置准备

MCP 服务器要调用 LLM，就得有模型访问凭证。如果每个服务器各配一套 Key，管理起来会很乱。TaoToken 的思路是提供一个统一 Key，让多个 MCP 服务器共用同一套接入凭证，减少重复配置。

你需要先拿到 Key。访问控制台创建：

https://taotoken.net/api-keys?utm_source=taotoken_aicg_blog_end&utm_content=api_keys&utm_campaign=rewrite

创建后把 Key 存到环境变量里，别硬编码进配置文件：

export TAOTOKEN_API_KEY="sk-你的统一Key"

API 基础地址用这个，注意它不带 UTM 参数：

https://taotoken.net/api

如果你还没决定用哪个模型，可以先在模型对话页面试一下：

https://taotoken.net/chat?utm_source=taotoken_aicg_blog_end&utm_content=model_chat&utm_campaign=rewrite

3. 可复制的 config.toml / settings.json 骨架

3.1 通用 config.toml 骨架

很多 MCP 服务器用 TOML 做配置。下面这个骨架把服务器声明、传输方式、环境变量注入都留了位置，你可以直接改：

# config.toml - MCP 服务器通用骨架 [mcp] name = "local-tools" version = "0.1.0" transport = "stdio" # 本地用 stdio，远程用 sse [mcp.server] command = "python" args = ["-m", "my_mcp_server"] env = { TAOTOKEN_API_KEY = "${TAOTOKEN_API_KEY}" } [llm] provider = "taotoken" base_url = "https://taotoken.net/api" api_key_env = "TAOTOKEN_API_KEY" model = "claude-3-5-sonnet" [capabilities] resources = true tools = true prompts = false

transport选stdio表示客户端通过标准输入输出和服务器通信，适合本地进程；远程服务器用sse。env里用${}引用环境变量，避免 Key 泄露到版本库。

3.2 Claude Desktop 的 settings.json 骨架

Claude Desktop 的 MCP 配置走claude_desktop_config.json，结构类似但字段名不同：

{ "mcpServers": { "local-tools": { "command": "python", "args": ["-m", "my_mcp_server"], "env": { "TAOTOKEN_API_KEY": "sk-你的统一Key", "TAOTOKEN_BASE_URL": "https://taotoken.net/api" } } } }

注意mcpServers下可以挂多个服务器，每个键名就是服务器标识。Claude Desktop 启动时会为每个条目拉起一个客户端连接。

3.3 自研 Agent 的客户端初始化骨架

如果你自己写主机，客户端初始化大概长这样：

import os from mcp import ClientSession, StdioServerParameters from mcp.client.stdio import stdio_client server_params = StdioServerParameters( command="python", args=["-m", "my_mcp_server"], env={ "TAOTOKEN_API_KEY": os.environ["TAOTOKEN_API_KEY"], "TAOTOKEN_BASE_URL": "https://taotoken.net/api", }, ) async def main(): async with stdio_client(server_params) as (read, write): async with ClientSession(read, write) as session: await session.initialize() tools = await session.list_tools() print("已暴露工具:", [t.name for t in tools.tools])

这段代码做了三件事：拉起服务器进程、建立会话、初始化后列出工具。initialize()是握手的关键，没它后面调用会报未初始化。

4. 连通性验证：判断握手是否成功

4.1 用 MCP Inspector 做第一轮验证

MCP Inspector 是官方提供的调试工具，能直观看到服务器暴露了哪些工具、资源、提示。启动方式：

npx @modelcontextprotocol/inspector python -m my_mcp_server

它会打开一个本地页面，你可以在里面手动触发工具调用。如果工具列表是空的，说明服务器没正确注册能力；如果连接直接失败，多半是command或args写错了。

4.2 用最小请求验证 LLM 链路

工具能列出来，不代表 LLM 调用链路通了。写个最小验证脚本：

import httpx, os resp = httpx.post( "https://taotoken.net/api/v1/messages", headers={ "Authorization": f"Bearer {os.environ['TAOTOKEN_API_KEY']}", "Content-Type": "application/json", }, json={ "model": "claude-3-5-sonnet", "max_tokens": 64, "messages": [{"role": "user", "content": "回复 OK 两个字母"}], }, timeout=30, ) print(resp.status_code, resp.json())

返回 200 且内容里有OK，说明统一 Key 和 API 地址都通了。如果返回 401，检查 Key 是否带上了Bearer前缀；返回 404，检查 base_url 有没有多写或少写/v1。

4.3 端到端握手成功的判断标准

一次完整的握手成功，应该同时满足：

• 客户端initialize()无异常返回
• list_tools()返回非空列表
• 手动调用一个工具能拿到结构化结果
• LLM 请求返回 200 且内容符合预期

四个条件缺一个，都说明链路还有断点。建议把这四步写成一个health_check.py，每次改配置后跑一遍。

5. 本篇常见错排查

5.1 服务器进程起不来

最常见的原因是command路径不对。比如你在虚拟环境里装了包，但配置里写的是系统python。解决办法是用绝对路径：

"command": "/Users/you/venv/bin/python"

另一个坑是args里的模块名拼错，服务器进程会静默退出。把stderr重定向到文件，能看到真实报错。

5.2 工具列表为空

服务器起来了，但list_tools()返回空。通常是装饰器没生效，比如 FastMCP 里忘了@mcp.tool()。检查你的工具函数上方有没有正确注册。还有一种情况是capabilities里把tools设成了false，客户端就不会去拉工具列表。

5.3 401 / 403 鉴权失败

统一 Key 的问题集中在三处：环境变量没导出、配置文件里写的是字面量${TAOTOKEN_API_KEY}而没被替换、Key 前后有空格。建议在脚本里打印os.environ.get("TAOTOKEN_API_KEY")[:8]确认前几位，别打印全量。

5.4 超时与连接重置

远程 MCP 服务器用sse传输时，如果网络中间有设备掐断长连接，会频繁超时。可以加心跳和重连：

server_params = StdioServerParameters( command="python", args=["-m", "my_mcp_server"], env={...}, ) # 在客户端侧设置超时和重试 session = ClientSession(read, write, read_timeout_seconds=60)

本地stdio一般不会超时，如果超时了，多半是服务器主循环被阻塞，检查有没有同步阻塞调用。

5.5 配置改了不生效

Claude Desktop 改完claude_desktop_config.json必须完全退出再重启，不是关窗口。自研 Agent 如果用了缓存，记得清掉__pycache__和会话缓存。这个坑我踩过，改了半天配置发现进程根本没重新加载。

6. 把骨架跑通之后

MCP 的价值在于它把“接外部上下文”这件事从一次性适配变成了标准化插拔。你搭好这套客户端-服务器骨架后，新增一个数据源只需要写一个符合规范的服务器，主机侧几乎不用改。统一 Key 则让多个服务器共享同一套模型凭证，省去重复配置。

如果你在排障阶段卡在鉴权或接入细节，先去 API Keys 页面确认 Key 状态，再对照接入文档核对 base_url 和请求头：

https://taotoken.net/api-keys?utm_source=taotoken_aicg_blog_end&utm_content=api_keys&utm_campaign=rewrite https://taotoken.net/doc?utm_source=taotoken_aicg_blog_end&utm_content=doc&utm_campaign=rewrite

如果你打算长期跑编码类 Agent，或者需要更稳定的模型调用配额，可以看看 Coding Plan：

https://taotoken.net/coding-plan?utm_source=taotoken_aicg_blog_end&utm_content=coding_plan&utm_campaign=rewrite

最后留一个实用建议：把health_check.py挂到 CI 里，每次改 MCP 配置自动跑一遍四步验证。这样你就不用等到线上 Agent 报错才发现握手断了。